Definer datamodeller for Fabric Apps

Fabric Apps bruker TypeScript-dekoratorer for å definere datamodeller som genererer databasetabeller og API-er. Du definerer hver entitet som en klasse dekorert med @entity(), legger til feltdekoratorer for datatyper, og kartlegger relasjoner mellom entiteter.

For veiledning om autorisasjon og tilgangskontroll, se Definer datatillatelser.

Forutsetninger

  • Et Fabric Apps-prosjekt opprettet med npm create @microsoft/rayfin@latest eller initialisert med npx rayfin init.
  • Grunnleggende forståelse av TypeScript-klasser og dekoratører.

Definer en enhet

For å lage en datamodell, legg dekoratoren @entity() til en TypeScript-klasse. Importer deretter de nødvendige dekoratørene 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 enheten genererer en Todo tabell med kolonner for id, title, , description, createdAt, og updatedAt.

Primærnøkler

Hver enhet bruker et UUID-felt string som sin id primærnøkkel. Hvis du ikke erklærer id eksplisitt, legger Fabric Apps det automatisk til skjemaet.

  • Feltet id er valgfritt under opprettelsesoperasjoner—serveren genererer en UUID hvis du utelater det.
  • Du kan levere din egen UUID ved opprettelsen hvis du foretrekker klientgenererte identifikatorer.
  • Sammensatte primærnøkler og egendefinerte nøkkelnavn støttes ikke.
@entity()
export class Note {
  @uuid() id!: string;  // UUID primary key, auto-generated when omitted
  @text() title!: string;
  @text() content!: string;
}

Datatyper som støttes

Bruk disse dekoratørene til å definere felttyper:

Dekoratør Type: Beskrivelse
@uuid() streng Unikt identifikatorfelt.
@text() streng Tekstfelt med valgfrie lengdebegrensninger.
@int() nummer Heltallig felt.
@decimal() nummer Desimal- eller numerisk felt.
@boolean() boolsk Sant eller falskt felt.
@date() Dato Dato- og tidsfeltet, serialiseres fra ISO-strenger eller Date objekter.
@email() streng Tekstfelt med e-postvalidering.
@set() streng Opplistet sett av strenglitteraler.

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

Legg til modifikatorer til feltdekoratorer for å konfigurere validering og begrensninger:

Endringstast Beskrivelse
{ optional: true } Tillat NULL-verdier. Felt er obligatoriske som standard.
{ unique: true } Legg til en unik begrensning.
{ default: value } Sett et standardverdiuttrykk.
{ max: n }, { min: n } Strenglengdebegrensninger (maksimalt og minimum antall tegn).
{ min: n }, { max: n } Numeriske verdibegrensninger.

Note

Den valgfrie markøren TypeScript (? etter et egenskapsnavn) påvirker kun den statiske TypeScript-typen. Det gjør ikke databasekolonnen null. For å gjøre et felt null, legg til { optional: true } i dekoratøren. Bruk ! for å hevde at et nødvendig felt initialiseres av rammeverket.

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

Definer relasjoner

Bruk @one() og @many() dekoratører for å definere navigasjonsegenskaper mellom enheter. Fabric Apps genererer automatisk fremmednøkkelkolonner når du definerer relasjoner.

  • Én-til-mange – Bruk @many() på både forelderen og @one() barnet.
  • Mange-til-én – Bruk @one() på barnet for å referere til forelderen.
  • Mange-til-mange-relasjoner støttes ikke—bruk heller en eksplisitt 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-enheten, lager Fabric Apps automatisk en kolonne med notebook_id fremmednøkkel. Deklarer fremmednøkkelfeltet eksplisitt kun hvis du planlegger å lese eller sette det i applikasjonskode.

Navnekonvensjon for fremmednøkkel

Når du definerer et fremmednøkkelfelt, bruk navnekonvensjonen {property}_id :

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

Egendefinerte fremmednøkkelnavn (foreignKey, targetKey alternativer) støttes ikke.

Referansesystemenheter

Fabric Apps støtter ikke @one()-relasjoner som peker til systemenheter som den innebygde USER-enheten. For å knytte en rad til den innloggede brukeren, legg til et vanlig user_id felt av typen @text() og fyll det ut fra autentiseringskravene (vanligvis claims.sub):

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

Filtrer rader etter user_id rollepolicyer for å håndheve tilgang per bruker.

Registrer enheter i skjemaet

Legg til alle entitetsklasser slik rayfin/data/schema.ts at klienten kan generere GraphQL-proxyer:

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

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

Oppdater denne typen hver gang du oppretter en ny entitet.

Påfør skjemaendringer

Etter å ha definert eller endret enhetene, bruk endringene i databasen:

  1. Distribuer det oppdaterte skjemaet til Fabric:

    npx rayfin up db apply

  2. Hvis skjemaendringen inkluderer destruktive operasjoner (fjerne kolonner, omdøpe tabeller), advarer CLI-en deg og nekter å fortsette. Bruk --force for å overstyre sikkerhetssjekken:

    npx rayfin up db apply --force

Note

--force Bruk kan føre til datatap. Gå nøye gjennom de oppførte operasjonene før du går videre.

Beste fremgangsmåter

  • Definer fremmednøkkelfelt kun når du trenger å lese eller sette dem i kode – Fabric Apps genererer dem automatisk fra navigasjonsdekoratorer.
  • Bruk relative importer med .js filendelser i entitetsfiler slik at den utsendte ESM-JavaScript løses korrekt.
  • For autorisasjonsmønstre og rollebasert tilgang, se Definer datatillatelser.

Feilsøking

Manglende relasjoner

Hvis relasjoner ikke vises i API-et, verifiser at:

  • Navigasjonsdekoratøren (@one() eller @many()) er til stede.
  • Enheten er registrert i rayfin/data/schema.ts.

Relatert innhold

  • Last updated on