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

Standardskabelonen blankapp opretter et Universal App-arbejdsområde med Data deaktiveret. Aktiver det med skabelonens datamodelleringsfunktion:

npm run pack:add -- data-modeling

Dette trin tilføjer en start-enhed og en delt kontrakt. Sæt enhedsklasser i packages/data/src/, registrer dem i packages/data/src/index.ts, og vedligehold deres kundeorienterede kontrakter i packages/shared/src/index.ts. Datatjenesten bruger services.data.path: packages/data i rayfin/rayfin.yml. Når du konfigurerer Data manuelt for Fabric, sæt enabled: true også og dialect: mssql.

Flade skabeloner kan i stedet beholde enheder i rayfin/data/ og bruge rayfin/data/schema.ts. Følg dine konfigurerede servicestier i stedet for at oprette en anden datamappe. Se Project struktur.

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

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

Important

Giv vedvarende tekstfelter en eksplicit maksimal længde, der passer til dine data. På Microsoft SQL Server genererer NVARCHAR(MAX)tekst uden max , hvilket kan forhindre generering af GraphQL-metadata. Eksemplerne bruger begrænset tekst, inklusive ejer- og fremmednøglestrenge. Se Fejlfinding af datamodelproblemer.

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

Understøttede datatyper

Brug disse dekoratorer til at definere felttyper:

Dekoratør Type Beskrivelse
@uuid() streng Unikt identifikatorfelt.
@text({ max: n }) streng Tekstfelt med en eksplicit maksimal længde for vedvarende MSSQL-kolonner.
@int() nummer Heltalsfelt.
@decimal() nummer Decimal- eller numerisk felt.
@boolean() boolesk Sandt eller falsk felt.
@date() Dato Dato- og tidsfeltet, serialiseres fra ISO-strenge eller Date objekter.
@email() streng Tekstfelt med e-mailvalidering.
@set() streng Opregnet sæt af strengliteraler.

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

Modifikator Beskrivelse
{ optional: true } Tillad NULL-værdier. Felter er påkrævet som standard.
{ unique: true } Tilføj en unik begrænsning.
{ default: value } Sæt et standardværdiudtryk.
{ max: n }, { min: n } Strenglængdebegrænsninger (maksimum og minimum antal tegn).
{ min: n }, { max: n } Numeriske værdibegrænsninger.

Bemærkning

TypeScript-valgmarkøren (? efter et egenskabsnavn) påvirker kun den statiske TypeScript-type. Det gør ikke databasekolonnen null. For at gøre et felt neutralt, tilføj { optional: true } til dekoratøren. Brug ! til at hævde, at et krævet felt initialiseres af frameworket.

Eksempel med modifikatorer

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

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

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({ max: 36 }) 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 begrænset user_id tekstfelt og udfyld det fra autentificeringskravene (typisk 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
}

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

Registrer enheder i skemaet

I et Universal App-arbejdsområde, registrer runtime-entitetsklasser i packages/data/src/index.ts:

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

export const schema = [Note, Notebook];

Hold de tilsvarende record-interfaces og UniversalAppSchema mapping justeret packages/shared/src/index.ts med disse enheder. Frontenden importeres UniversalAppSchema fra @rayfin-app/shared; den importerer ikke dekorerede runtime-klasser. Tilføj Product til begge registreringer, hvis du bruger de numeriske aggregeringseksempler i Read and write-data.

For et flad-skabelon alternativ, map entity types i rayfin/data/schema.ts:

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

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

Opdater registreringerne og skematyperne for dit valgte layout, hver gang du opretter en ny entitet.

Påfør skemaændringer

Efter at have defineret eller ændret enheder, anvendes ændringerne på databasen. For den komplette implementerings- og verifikationsproces, se Anvend og verificér skemaændringer.

  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

Bemærkning

--force Brug kan forårsage datatab. Gennemgå de listede operationer grundigt, før du går videre.

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.
  • Entiteten er registreret i din konfigurerede datapakke og delte skema, eller i rayfin/data/schema.ts en flad skabelon.

Relateret indhold

  • Sidst opdateret den