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à

Il template predefinito blankapp crea uno spazio di lavoro Universal App con i Dati disabilitati. Attivalo con la capacità di modellazione dei dati del modello:

npm run pack:add -- data-modeling

Questo passaggio aggiunge un'entità iniziale e un contratto condiviso. Inserire classi di entità in packages/data/src/, registrarle in packages/data/src/index.ts, e mantenere i loro contratti esposti al client in packages/shared/src/index.ts. Il servizio dati utilizza services.data.path: packages/data in rayfin/rayfin.yml. Quando configuri manualmente i dati per Fabric, imposta enabled: true anche e dialect: mssql.

I template piatti possono invece mantenere le entità in rayfin/data/ e usare rayfin/data/schema.ts. Segui i percorsi di servizio configurati invece di creare una seconda cartella dati. Vedi struttura del progetto.

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({ max: 200 }) title!: string;
  @text({ optional: true, max: 2000 }) description?: string;
  @date() createdAt!: Date;
  @date() updatedAt!: Date;
}

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

Importante

Assegna ai campi di testo persistenti una lunghezza massima esplicita adeguata ai tuoi dati. Su Microsoft SQL Server, il testo senza max genera NVARCHAR(MAX), che può impedire la generazione di metadati GraphQL. Gli esempi usano testo delimitato, inclusi le stringhe di proprietario e chiave esterna. Vedi Risolvere i problemi del modello di dati.

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({ max: 200 }) title!: string;
  @text({ max: 4000 }) content!: string;
}

Tipi di dati supportati

Usa questi decoratori per definire i tipi di campo:

Decoratore Tipo Description
@uuid() corda Campo identificatore univoco.
@text({ max: n }) corda Campo testo con una lunghezza massima esplicita per le colonne MSSQL persistenti.
@int() Numero Campo Integer.
@decimal() Numero Campo decimale o numerico.
@boolean() Boolean Campo vero o falso.
@date() Date Campo data e ora, viene serializzato da stringhe ISO o oggetti Date.
@email() corda Campo di testo con convalida della posta elettronica.
@set() corda Set enumerato di valori letterali stringa.

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({ max: 200 }) 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:

Modificatore Description
{ optional: true } Consenti valori NULL. I campi sono obbligatori per impostazione predefinita.
{ unique: true } Aggiungere un vincolo univoco.
{ default: value } Impostare un'espressione di valore predefinita.
{ max: n }, { min: n } Vincoli di lunghezza stringa (numero massimo e minimo di caratteri).
{ min: n }, { max: n } Vincoli di valore numerico.

Note

Il marcatore facoltativo TypeScript (? dopo un nome di proprietà) influisce solo sul tipo TypeScript statico. Non rende la colonna del database in grado di accettare valori NULL. Per rendere un campo ammissibile a valori null, aggiungi { optional: true } al decoratore. Utilizzare ! per asserire che un campo obbligatorio viene inizializzato dal framework.

Esempio con modificatori

@entity()
export class User {
  @uuid() id!: string;
  @email({ unique: true, max: 254 }) 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({ max: 200 }) name!: string;
  @date() createdAt!: Date;
  @many(() => Note) notes?: Note[];
}

@entity()
export class Note {
  @uuid() id!: string;
  @text({ max: 200 }) title!: string;
  @text({ max: 4000 }) content!: string;
  @date() createdAt!: Date;
  @text({ max: 36 }) 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({ max: 36 }) 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 campo di testo delimitato user_id e popolalo dai claim di autenticazione (tipicamente claims.sub):

@entity()
export class Task {
  @uuid() id!: string;
  @text({ max: 200 }) title!: string;
  @text({ max: 255 }) 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

In uno spazio di lavoro Universal App, registra le classi di entità in runtime in packages/data/src/index.ts:

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

export const schema = [Note, Notebook];

Mantieni le corrispondenti interfacce di record e la mappa in packages/shared/src/index.tsUniversalAppSchema allineate a tali entità. Il frontend importa UniversalAppSchema da @rayfin-app/shared; non importa classi runtime decorate. Aggiungi Product a entrambe le registrazioni se usi gli esempi di aggregazione numerica in Leggere e scrivere dati.

Per un'alternativa a modello piatto, mappa i tipi di entità in rayfin/data/schema.ts:

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

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

Aggiorna le registrazioni e i tipi di schema per il layout scelto ogni volta che crei una nuova entità.

Applicare modifiche allo schema

Dopo aver definito o modificato le entità, applicare le modifiche al database. Per il flusso di lavoro completo di distribuzione e verifica, vedi Applica e verifica le modifiche dello schema.

  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
    

Note

L'uso --force di può causare la perdita di dati. Prima di procedere, esaminare attentamente le operazioni elencate.

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 nel pacchetto dati configurato e nello schema condiviso, oppure in rayfin/data/schema.ts per un modello flat.