Definiera datamodeller för Fabric-appar

Fabric Apps använder TypeScript-dekoratörer för att definiera datamodeller som genererar databastabeller och API:er. Du definierar varje entitet som en klass som är dekorerad med @entity(), lägger till fältdekoratörer för datatyper och mappar relationer mellan entiteter.

Vägledning för auktorisering och åtkomstkontroll finns i Definiera databehörigheter.

Förutsättningar

  • Ett Fabric Apps-projekt som skapats med npm create @microsoft/rayfin@latest eller initierats med npx rayfin init.
  • Grundläggande förståelse för TypeScript-klasser och dekoratörer.

Definiera en entitet

Standardmallen blankapp skapar en Universal App-arbetsyta med Data inaktiverad. Aktivera det med mallens datamodelleringsfunktion:

npm run pack:add -- data-modeling

Detta steg lägger till en startentitet och ett delat kontrakt. Lägg in entitetsklasser i packages/data/src/, registrera dem i packages/data/src/index.ts, och upprätthåll deras klientinriktade avtal i packages/shared/src/index.ts. Datatjänsten använder services.data.path: packages/data i rayfin/rayfin.yml. När du konfigurerar Data manuellt för Fabric, sätt enabled: true också och dialect: mssql.

Platta mallar kan istället behålla entiteter i rayfin/data/ och använda rayfin/data/schema.ts. Följ dina konfigurerade sökvägar för tjänsten istället för att skapa en andra datamapp. Se projektstruktur.

Om du vill skapa en datamodell lägger du till dekoratören i @entity() en TypeScript-klass. Importera sedan de nödvändiga dekoratörerna från @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;
}

Den här entiteten genererar en Todo tabell med kolumner för id, title, description, createdAtoch updatedAt.

Important

Ge sparade textfält en explicit maxlängd som är lämplig för dina data. På Microsoft SQL Server genererar text utan NVARCHAR(MAX)max, vilket kan förhindra generering av metadata i GraphQL. Exemplen använder avgränsad text, inklusive ägar- och främmande nyckelsträngar. Se Felsök problem med datamodellen.

Primärnycklar

Varje entitet använder ett UUID-fält string med namnet id som primärnyckel. Om du inte deklarerar id explicit lägger Fabric Apps till den i schemat automatiskt.

  • Fältet id är valfritt under skapandeåtgärder – servern genererar ett UUID om du utelämnar det.
  • Du kan ange ditt eget UUID vid skapandetillfället om du föredrar klientgenererade identifierare.
  • Sammansatta primära nycklar och anpassade nyckelnamn stöds inte.
@entity()
export class Note {
  @uuid() id!: string;  // UUID primary key, auto-generated when omitted
  @text({ max: 200 }) title!: string;
  @text({ max: 4000 }) content!: string;
}

Datatyper som stöds

Använd dessa dekoratörer för att definiera fälttyper:

Dekoratör Type Description
@uuid() snöre Unikt ID-fält.
@text({ max: n }) snöre Textfält med en explicit maximal längd för persisterade MSSQL-kolumner.
@int() nummer Heltalsfält.
@decimal() nummer Decimal- eller numeriskt fält.
@boolean() boolean Sant eller falskt fält.
@date() Datum Datum- och tidsfält, serialiserar från ISO-strängar eller Date -objekt.
@email() snöre Textfält med e-postverifiering.
@set() snöre Uppräknad mängd strängliteraler.

Exempel med flera 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';
}

Typmodifierare

Lägg till modifierare i fältdekoratörer för att konfigurera validering och begränsningar:

Modifierare Description
{ optional: true } Tillåt NULL-värden. Fält är obligatoriska som standard.
{ unique: true } Lägg till en unik begränsning.
{ default: value } Ange ett standardvärdeuttryck.
{ max: n }, { min: n } Begränsningar för stränglängd (maximalt och minsta antal tecken).
{ min: n }, { max: n } Numeriska värdebegränsningar.

Note

Den valfria TypeScript-markören (? efter ett egenskapsnamn) påverkar bara den statiska TypeScript-typen. Det gör inte databaskolumnen nullbar. Om du vill göra ett fält nullbart lägger du till { optional: true } i dekoratören. Använd ! för att bekräfta att ett obligatoriskt fält initieras av ramverket.

Exempel med modifierare

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

Definiera relationer

Använd @one() och @many() dekoratörer för att definiera navigeringsegenskaper mellan entiteter. Fabric Apps genererar automatiskt kolumner med främmande nyckel när du definierar relationer.

  • En-till-flera – Använd @many() på föräldraobjektet och @one() på barnobjektet.
  • Många till en – Använd @one() på barnet för att referera till föräldern.
  • Många-till-många-relationer stöds inte – använd en explicit kopplingsentitet i stället.

Exempel med en-till-många-relation

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 definierar @one(() => Notebook) på entiteten Note skapar Fabric Apps automatiskt en notebook_id sekundärnyckelkolumn. Deklarera endast fältet för främmande nyckel explicit om du planerar att läsa eller ställa in det i applikationskod.

Namngivningskonvention för främmande nyckel

När du definierar ett främmande nyckelfält ska du använda följande namngivningskonvention: {property}_id

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

Anpassade namn på främmande nycklar (foreignKey, targetKey-alternativen) stöds inte.

Entiteter i referenssystem

Fabric Apps stöder inte @one() relationer som pekar på systementiteter som den inbyggda USER-entiteten. För att associera en rad med den inloggade användaren, lägg till ett begränsat user_id textfält och fyll i det från autentiseringsanspråken (vanligtvis 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
}

Filtrera rader efter user_id i dina rollpolicyer för att tillämpa åtkomst på användarnivå.

Registrera entiteter i schemat

I en Universal App-arbetsyta, registrera runtime-entitetsklasser i packages/data/src/index.ts:

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

export const schema = [Note, Notebook];

Se till att motsvarande postgränssnitt och UniversalAppSchema mappning i packages/shared/src/index.ts överensstämmer med dessa entiteter. Frontend importerar UniversalAppSchema från @rayfin-app/shared; den importerar inte dekorerade runtime-klasser. Lägg till Product i båda registren om du använder numeriska aggregeringsexempel i Läs och skriv data.

För ett alternativ till flat template, mappa entitetstyper i rayfin/data/schema.ts:

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

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

Uppdatera registreringarna och schematyperna för din valda layout varje gång du skapar en ny entitet.

Tillämpa schemaändringar

Efter att ha definierat eller ändrat enheterna, applicera ändringarna i databasen. För hela arbetsflödet för distribution och verifiering, se Tillämpa och verifiera schemaändringar.

  1. Distribuera det uppdaterade schemat till Fabric:

    npx rayfin up db apply
    
  2. Om schemaändringen innehåller destruktiva åtgärder (släppa kolumner, byta namn på tabeller) varnar CLI dig och vägrar att fortsätta. Använd --force för att åsidosätta säkerhetskontrollen:

    npx rayfin up db apply --force
    

Note

Användning --force kan orsaka dataförlust. Granska de angivna åtgärderna noggrant innan du fortsätter.

Metodtips

  • Definiera fält med sekundärnyckel endast när du behöver läsa eller ange dem i kod – Fabric Appar genererar dem automatiskt från navigeringsdekoratörer.
  • Använd relativa importer med filändelsen .js i entitetsfiler så att den genererade ESM-JavaScripten tolkas korrekt.
  • Information om auktoriseringsmönster och rollbaserad åtkomst finns i Definiera databehörigheter.

Troubleshooting

Saknade relationer

Om relationer inte visas i API:et kontrollerar du att:

  • Navigeringsdekoratören (@one() eller @many()) finns.
  • Entiteten är registrerad i ditt konfigurerade datapaket och delade schema, eller i rayfin/data/schema.ts för en platt mall.