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

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() title!: string;
  @text({ optional: true }) 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.

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

Datatyper som stöds

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

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() 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:

Exempel med modifierare

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

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() 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 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() 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. Om du vill associera en rad med den inloggade användaren lägger du till ett oformaterat user_id fält av typen @text() och fyller i det från autentiseringsanspråken (vanligtvis claims.sub):

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

Lägg till alla entitetsklasser i rayfin/data/schema.ts så att klienten kan generera GraphQL-proxyer:

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

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

Uppdatera den här typen när du skapar en ny entitet.

Tillämpa schemaändringar

När du har definierat eller ändrat entiteter tillämpar du ändringarna på databasen:

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
   

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 rayfin/data/schema.ts.

Relaterat innehåll

• Fråga efter data med GraphQL
• Definiera databehörigheter
• Distribuera till Fabric