Definér datamodeller for Fabric Apps

Fabric Apps bruger TypeScript-dekoratorer til at definere datamodeller, der genererer databasetabeller og API'er. Du definerer hver enhed som en klasse dekoreret med @entity(), tilføjer feltdekoratorer for datatyper og kortlægger relationer mellem enheder.

For vejledning om autorisation og adgangskontrol, se Definér datatilladelser.

Forudsætninger

• Et Fabric Apps-projekt oprettet med npm create @microsoft/rayfin@latest eller initialiseret med npx rayfin init.
• Grundlæggende forståelse af TypeScript-klasser og dekorationer.

Definér en enhed

For at oprette en datamodel tilføjes decoratoren @entity() til en TypeScript-klasse. Importer derefter de nødvendige dekoratører fra @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;
}

Denne enhed genererer en Todo tabel med kolonner for id, title, description, , createdAtog updatedAt.

Primære nøgler

Hver enhed bruger et UUID-felt string med navnet id som sin primære nøgle. Hvis du ikke erklærer id eksplicit, tilføjer Fabric Apps det automatisk til skemaet.

• Feltet id er valgfrit under oprettelsesoperationer – serveren genererer en UUID, hvis du udelader det.
• Du kan levere din egen UUID ved oprettelse, hvis du foretrækker klientgenererede identifikatorer.
• Sammensatte primærnøgler og brugerdefinerede nøglenavne understøttes ikke.

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

Understøttede datatyper

Brug disse dekoratorer til at definere felttyper:

Eksempel med flere typer

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';
}

Typemodifikatorer

Tilføj modifikatorer til feltdekoratorer for at konfigurere validering og begrænsninger:

Eksempel med modifikatorer

@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;
}

Definér relationer

Brug @one() og @many() dekoratører til at definere navigationsegenskaber mellem enheder. Fabric Apps genererer automatisk fremmednøglekolonner, når du definerer relationer.

• Én-til-mange – Brug @many() på både forælderen og @one() barnet.
• Mange-til-en – Brug @one() på barnet som reference til forælderen.
• Mange-til-mange-relationer understøttes ikke—brug i stedet en eksplicit join-entitet.

Eksempel med én-til-mange-forhold

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;
}

Når du definerer @one(() => Notebook) på Note-enheden, opretter Fabric Apps automatisk en notebook_id fremmednøglekolonne. Deklarér eksplicit fremmednøglefeltet kun hvis du planlægger at læse eller sætte det i applikationskoden.

Navngivningskonvention for fremmednøgler

Når du definerer et fremmednøglefelt, brug navngivningskonventionen {property}_id :

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

Brugerdefinerede fremmednøglenavne (foreignKey, targetKey valgmuligheder) understøttes ikke.

Referencesystemenheder

Fabric Apps understøtter ikke @one()-relationer, der peger på systementiteter som den indbyggede USER-entitet. For at tilknytte en række til den indloggede bruger, tilføj et almindeligt user_id felt af typen @text() og udfyld det fra autentificeringskravene (typisk claims.sub):

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

Filtrer rækker efter user_id i dine rollepolitikker for at håndhæve adgang pr. bruger.

Registrer enheder i skemaet

Tilføj alle entitetsklasser til rayfin/data/schema.ts , så klienten kan generere GraphQL-proxies:

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

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

Opdater denne type, hver gang du opretter en ny entitet.

Påfør skemaændringer

Efter at have defineret eller ændret enheder, anvendes ændringerne på databasen:

1. Udrul det opdaterede skema til Fabric:

   npx rayfin up db apply
   

2. Hvis skemaændringen inkluderer destruktive operationer (at fjerne kolonner, omdøbe tabeller), advarer CLI'en dig og nægter at fortsætte. Brug --force til at tilsidesætte sikkerhedstjekket:

   npx rayfin up db apply --force
   

Bedste praksis

• Definer fremmednøglefelter kun, når du skal læse eller sætte dem i kode – Fabric Apps genererer dem automatisk fra navigationsdekoratorer.
• Brug relative imports med .js endelser i entitetsfiler, så den udsendte ESM-JavaScript løses korrekt.
• For autorisationsmønstre og rollebaseret adgang, se Definér datarettigheder.

Fejlfinding

Manglende forhold

Hvis relationer ikke vises i API'et, så verificér at:

• Navigationsdekoratøren (@one() eller @many()) er til stede.
• Enheden er registreret i rayfin/data/schema.ts.

Relateret indhold

• Forespørg data med GraphQL
• Definér datatilladelser
• Udrul til Fabric