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

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

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

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

Ondersteunde gegevenstypen

Gebruik deze decorators om veldtypen te definiëren:

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

Voorbeeld met modifiers

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

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

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() 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. Als u een rij wilt koppelen aan de aangemelde gebruiker, voegt u een gewoon user_id veld van het type @text() toe en vult u deze in vanuit de verificatieclaims (meestal claims.sub):

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

Voeg alle entiteitsklassen toe zodat rayfin/data/schema.ts de client GraphQL-proxy's kan genereren:

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

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

Werk dit type bij wanneer u een nieuwe entiteit maakt.

Schemawijzigingen toepassen

Nadat u entiteiten hebt gedefinieerd of gewijzigd, past u de wijzigingen toe op de database:

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
   

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

Verwante inhoud

• Query's uitvoeren op gegevens met GraphQL
• Gegevensmachtigingen definiëren
• Implementeren naar Fabric