Definire modelli di dati per le app di Fabric

Fabric Apps usa i decorator di TypeScript per definire modelli di dati che generano tabelle di database e API. Ogni entità viene definita come classe decorata con @entity(), aggiungere elementi decorati di campo per i tipi di dati e mappare le relazioni tra entità.

Per indicazioni sull'autorizzazione e sul controllo di accesso, vedere Definire le autorizzazioni per i dati.

Prerequisiti

• Progetto app di Fabric creato con npm create @microsoft/rayfin@latest o inizializzato con npx rayfin init.
• Conoscenza di base delle classi TypeScript e dei decoratori.

Definire un'entità

Per creare un modello di dati, aggiungere l'elemento @entity() Decorator a una classe TypeScript. Importare quindi i decorator necessari da @microsoft/rayfin-core:

import { entity, uuid, text, date } from '@microsoft/rayfin-core';

@entity()
export class Todo {
  @uuid() id!: string;
  @text() title!: string;
  @text({ optional: true }) description?: string;
  @date() createdAt!: Date;
  @date() updatedAt!: Date;
}

Questa entità genera una Todo tabella con colonne per id, titledescription, createdAt, e updatedAt.

Chiavi primarie

Ogni entità usa un campo UUID string denominato id come chiave primaria. Se non si dichiara id in modo esplicito, Fabric App lo aggiunge automaticamente allo schema.

• Il campo è facoltativo durante le operazioni di creazione. Il id server genera un UUID se viene omesso.
• È possibile specificare il proprio UUID in fase di creazione se si preferisce gli identificatori generati dal client.
• Le chiavi primarie composite e i nomi di chiave personalizzati non sono supportati.

@entity()
export class Note {
  @uuid() id!: string;  // UUID primary key, auto-generated when omitted
  @text() title!: string;
  @text() content!: string;
}

Tipi di dati supportati

Usa questi decoratori per definire i tipi di campo:

Esempio con più tipi

import { entity, uuid, text, int, decimal, boolean, date, set } from '@microsoft/rayfin-core';

@entity()
export class Product {
  @uuid() id!: string;
  @text() name!: string;
  @decimal() price!: number;
  @int() stockQuantity!: number;
  @boolean() isAvailable!: boolean;
  @date() createdAt!: Date;
  @set('draft', 'published', 'archived') status!: 'draft' | 'published' | 'archived';
}

Modificatori di tipo

Aggiungi modificatori ai decoratori di campo per configurare la convalida e i vincoli:

Esempio con modificatori

@entity()
export class User {
  @uuid() id!: string;
  @email({ unique: true }) email!: string;
  @text({ min: 3, max: 50 }) username!: string;
  @text({ optional: true, max: 500 }) bio?: string;
  @int({ min: 0, max: 150 }) age!: number;
  @boolean({ default: false }) isVerified!: boolean;
}

Definire le relazioni

Usare i decoratori @one() e @many() per definire le proprietà di navigazione tra le entità. Fabric App genera automaticamente colonne chiave esterna quando si definiscono le relazioni.

• Uno-a-molti – Usa @many() nel genitore e @one() nel figlio.
• Molti-a-uno : usare @one() sul figlio per fare riferimento all'elemento padre.
• Le relazioni molti a molti non sono supportate: usa invece un'entità di collegamento esplicita.

Esempio con relazione uno a molti

import { entity, uuid, text, date, one, many } from '@microsoft/rayfin-core';

@entity()
export class Notebook {
  @uuid() id!: string;
  @text() name!: string;
  @date() createdAt!: Date;
  @many(() => Note) notes?: Note[];
}

@entity()
export class Note {
  @uuid() id!: string;
  @text() title!: string;
  @text() content!: string;
  @date() createdAt!: Date;
  @text() notebook_id!: string;
  @one(() => Notebook) notebook?: Notebook;
}

Quando si definisce @one(() => Notebook) nell'entità Note, Fabric App crea automaticamente una colonna chiave esterna notebook_id. Dichiarare il campo della chiave esterna in modo esplicito solo se si prevede di leggerlo o impostarlo nel codice dell'applicazione.

Convenzione di denominazione delle chiavi esterne

Quando si definisce un campo di chiave esterna, usare la convenzione di denominazione {property}_id:

@entity()
export class Note {
  @uuid() id!: string;
  @text() notebook_id!: string;      // Foreign key field
  @one(() => Notebook) notebook?: Notebook;  // Navigation property
}

I nomi di chiave esterna personalizzati (foreignKey, targetKey le opzioni) non sono supportati.

Entità di sistema di riferimento

Fabric App non supporta le relazioni @one() che puntano alle entità di sistema, ad esempio l'entità predefinita USER. Per associare una riga all'utente connesso, aggiungi un semplice campo user_id di tipo @text() e popolalo con i claims di autenticazione (in genere claims.sub):

@entity()
export class Task {
  @uuid() id!: string;
  @text() title!: string;
  @text() user_id!: string;  // System user ID from claims.sub
}

Filtrare le righe in base a user_id nelle policy di ruolo per imporre un accesso per utente.

Registrare le entità nello schema

Aggiungere tutte le classi di entità a rayfin/data/schema.ts in modo che il client possa generare proxy GraphQL:

import type { Note } from './Note.js';
import type { Notebook } from './Notebook.js';

export type NotesAppSchema = {
  Note: Note;
  Notebook: Notebook;
};

Aggiornare questo tipo ogni volta che si crea una nuova entità.

Applicare modifiche allo schema

Dopo aver definito o modificato le entità, applicare le modifiche al database:

1. Distribuire lo schema aggiornato in Fabric:

   npx rayfin up db apply
   

2. Se la modifica dello schema include operazioni distruttive (eliminazione di colonne, ridenominazione delle tabelle), l'interfaccia della riga di comando avvisa e rifiuta di continuare. Usare --force per eseguire l'override del controllo di sicurezza:

   npx rayfin up db apply --force
   

Procedure consigliate

• Definisci i campi di chiave esterna solo quando devi leggerli o impostarli nel codice: Fabric Apps li genera automaticamente a partire dai decoratori di navigazione.
• Usare importazioni relative con le estensioni .js nei file delle entità in modo che il codice JavaScript ESM generato venga risolto correttamente.
• Per i modelli di autorizzazione e l'accesso basato sui ruoli, vedere Definire le autorizzazioni per i dati.

Troubleshooting

Relazioni mancanti

Se le relazioni non vengono visualizzate nell'API, verificare che:

• Il decoratore di navigazione (@one() o @many()) è presente.
• L'entità è registrata in rayfin/data/schema.ts.

Contenuti correlati

• Eseguire query sui dati con GraphQL
• Definire le autorizzazioni per i dati
• Distribuisci in Fabric