Gegevensmodellen definiëren voor Fabric Apps

Fabric Apps maakt gebruik van TypeScript-decorators om gegevensmodellen te definiëren die databasetabellen en API's genereren. U definieert elke entiteit als een klasse met @entity(), voegt veld decorators toe voor gegevenstypen en wijst relaties tussen entiteiten toe.

Zie Gegevensmachtigingen definiëren voor richtlijnen voor autorisatie- en toegangsbeheer.

Prerequisites

• Een Fabric Apps-project gemaakt met npm create @microsoft/rayfin@latest of geïnitialiseerd met npx rayfin init.
• Basiskennis van TypeScript-klassen en decorators.

Een entiteit definiëren

De standaardtemplate blankapp maakt een Universal App-werkruimte aan met Data uitgeschakeld. Schakel het in met de functie voor datamodellering van het sjabloon:

npm run pack:add -- data-modeling

Deze stap voegt een starter-entiteit en een gedeeld contract toe. Plaats entiteitsklassen in packages/data/src/, registreer ze in packages/data/src/index.ts, en onderhoud hun klantgerichte contracten in packages/shared/src/index.ts. De datadienst gebruikt services.data.path: packages/data in rayfin/rayfin.yml. Wanneer je Data handmatig configureert voor Fabric, stel ook enabled: true en dialect: mssql in.

Flat templates kunnen in plaats daarvan entiteiten in rayfin/data/ behouden en rayfin/data/schema.ts gebruiken. Volg je geconfigureerde servicepaden in plaats van een tweede datamap aan te maken. Zie Projectstructuur.

Als u een gegevensmodel wilt maken, voegt u de @entity() decorator toe aan een TypeScript-klasse. Importeer vervolgens de vereiste decorators uit @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;
}

Deze entiteit genereert een Todo tabel met kolommen voor id, title, descriptionen createdAtupdatedAt.

Important

Geef opgeslagen tekstvelden een expliciete maximale lengte die past bij je gegevens. Op Microsoft SQL Server genereert tekst zonder NVARCHAR(MAX)max, wat de generatie van metadata door GraphQL kan voorkomen. De voorbeelden gebruiken afgebakende tekst, inclusief eigenaar- en vreemde sleutelstrings. Zie Problemen met datamodellen oplossen.

Primaire sleutels

Elke entiteit gebruikt een UUID-veld string met de naam id als primaire sleutel. Als u id niet expliciet declareert, voegt Fabric Apps deze automatisch toe aan het schema.

• Het id veld is optioneel tijdens het maken van bewerkingen. De server genereert een UUID als u dit weglaat.
• U kunt bij het aanmaken uw eigen UUID opgeven als u de voorkeur geeft aan door de client gegenereerde identificatoren.
• Samengestelde primaire sleutels en aangepaste sleutelnamen worden niet ondersteund.

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

Ondersteunde gegevenstypen

Gebruik deze decorators om veldtypen te definiëren:

Decorateur	Type	Beschrijving
@uuid()	touw	Uniek id-veld.
@text({ max: n })	touw	Tekstveld met een expliciete maximale lengte voor persistente MSSQL-kolommen.
@int()	nummer	Veld voor gehele getallen.
@decimal()	nummer	Veld voor decimalen of getallen.
@boolean()	boolean	Waar- of onwaarveld.
@date()	Datum	Datum- en tijdveld, serialiseert van ISO-tekenreeksen of Date -objecten.
@email()	touw	Tekstveld met e-mailvalidatie.
@set()	touw	Opgesomde verzameling van tekenreeksconstanten.

Voorbeeld met meerdere typen

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

Typemodificatoren

Voeg modifiers toe aan veld decorators om validatie en beperkingen te configureren:

Wijziger	Beschrijving
{ optional: true }	NULL-waarden toestaan. Velden zijn standaard vereist.
{ unique: true }	Voeg een unieke beperking toe.
{ default: value }	Stel een standaardwaardeexpressie in.
{ max: n }, { min: n }	Beperkingen voor tekenreekslengte (maximum- en minimumaantal tekens).
{ min: n }, { max: n }	Beperkingen voor numerieke waarden.

Opmerking

De optionele TypeScript-markering (? na een eigenschapsnaam) is alleen van invloed op het statische TypeScript-type. Hierdoor gaat de databasekolom geen NULL-waarden toestaan. Als u een veld nullbaar wilt maken, voegt u { optional: true } toe aan de decorator. Gebruik ! dit om te bevestigen dat een vereist veld wordt geïnitialiseerd door het framework.

Voorbeeld met modifiers

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

Relaties definiëren

Gebruik @one() en @many() decorators om navigatie-eigenschappen tussen entiteiten te definiëren. Fabric Apps genereert automatisch kolommen met externe sleutels wanneer u relaties definieert.

• Een-op-veel - gebruik @many() op het bovenliggende item en @one() op het kind.
• Veel-op-één – Gebruik @one() op het kind om naar het bovenliggende item te verwijzen.
• Veel-op-veel-relaties worden niet ondersteund. Gebruik in plaats daarvan een expliciete join-entiteit.

Voorbeeld met een-op-veel-relatie

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

Wanneer u @one(() => Notebook) definieert op de entiteit Note, maakt Fabric Apps automatisch een foreign key-kolom notebook_id. Definieer het veld voor de vreemde sleutel alleen expliciet als u van plan bent dit in de applicatiecode te lezen of in te stellen.

Naamgevingsconventie voor externe sleutels

Wanneer u een veld met een externe sleutel definieert, gebruikt u de {property}_id naamgevingsconventie:

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

Aangepaste namen voor vreemde sleutels (foreignKey, targetKey opties) worden niet ondersteund.

Referentiesysteementiteiten

Fabric Apps biedt geen ondersteuning voor @one()-relaties die verwijzen naar systeementiteiten zoals de ingebouwde entiteit USER. Om een rij te koppelen aan de ingelogde gebruiker, voeg je een begrensd user_id tekstveld toe en vul je het in vanuit de authenticatieclaims (meestal 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
}

Filter rijen op user_id in uw rolbeleidsregels om toegang per gebruiker af te dwingen.

Entiteiten registreren in het schema

In een Universal App-werkruimte registreer runtime entity-klassen in packages/data/src/index.ts:

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

export const schema = [Note, Notebook];

Houd de bijbehorende recordinterfaces en UniversalAppSchema map in packages/shared/src/index.ts uitgelijnd met die entiteiten. De frontend importeert UniversalAppSchema uit @rayfin-app/shared; het importeert geen versierde runtime-klassen. Voeg aan beide registraties toe Product als je de numerieke aggregatievoorbeelden in Read and Write data gebruikt.

Voor een alternatief voor een flat template, entiteitstypen toewijzen in rayfin/data/schema.ts:

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

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

Werk de registraties en schema-typen bij voor je gekozen lay-out telkens wanneer je een nieuwe entiteit aanmaakt.

Schemawijzigingen toepassen

Na het definiëren of wijzigen van entiteiten, pas je de wijzigingen toe op de database. Voor de volledige implementatie- en verificatieworkflow, zie Schemawijzigingen toepassen en verifiëren.

1. Implementeer het bijgewerkte schema in Fabric:

   npx rayfin up db apply
   

2. Als de schemawijziging destructieve bewerkingen bevat (kolommen verwijderen, tabellen een andere naam geven), waarschuwt de CLI u en weigert u verder te gaan. Gebruik --force dit om de veiligheidscontrole te overschrijven:

   npx rayfin up db apply --force
   

Opmerking

Het gebruik --force kan leiden tot gegevensverlies. Bekijk de vermelde bewerkingen zorgvuldig voordat u doorgaat.

Beste praktijken

• Definieer velden voor externe sleutels alleen wanneer u ze in code moet lezen of instellen—Fabric Apps genereert ze automatisch op basis van navigatiedecorators.
• Gebruik relatieve importbewerkingen met .js extensies in entiteitsbestanden, zodat het verzonden ESM JavaScript correct wordt omgezet.
• Zie Gegevensmachtigingen definiëren voor autorisatiepatronen en op rollen gebaseerde toegang.

Troubleshooting

Ontbrekende relaties

Als relaties niet worden weergegeven in de API, controleert u of:

• De navigatiedecorator (@one() of @many()) is aanwezig.
• De entiteit wordt geregistreerd in je geconfigureerde datapakket en gedeelde schema, of in rayfin/data/schema.ts voor een flat template.

Verwante inhoud

• Query's uitvoeren op gegevens met GraphQL
• Pas schemawijzigingen toe en verifieer
• Gegevensmachtigingen definiëren
• Implementeren naar Fabric