Definujte dátové modely pre Fabric Apps

Fabric Apps používa dekorátory TypeScript na definovanie dátových modelov, ktoré generujú databázové tabuľky a API. Každú entitu definujete ako triedu ozdobenú , @entity()pridáte dekorátory polí pre dátové typy a mapujete vzťahy medzi entitami.

Pre usmernenia k autorizácii a správe prístupu pozri Definujte dátové oprávnenia.

Predpoklady

  • Projekt Fabric Apps vytvorený pomocou npm create @microsoft/rayfin@latest alebo inicializovaný pomocou npx rayfin init.
  • Základné pochopenie tried a dekoratérov v TypeScripte.

Definujte entitu

Na vytvorenie dátového modelu pridajte @entity() dekorátor do triedy TypeScript. Potom importujte požadovaných dekoratérov z @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;
}

Táto entita generuje tabuľku Todo so stĺpcami pre id, title, description, createdAt, a .updatedAt

Primárne kľúče

Každá entita používa UUID string pole pomenované id ako svoj primárny kľúč. Ak nedeclarujete id explicitne, Fabric Apps ho automaticky pridá do schémy.

  • Pole id je voliteľné počas operácií vytvárania – server vygeneruje UUID, ak ho vynecháte.
  • Ak preferujete identifikátory generované klientom, môžete pri vytvorení poskytnúť vlastné UUID.
  • Kompozitné primárne kľúče a vlastné názvy kľúčov nie sú podporované.
@entity()
export class Note {
  @uuid() id!: string;  // UUID primary key, auto-generated when omitted
  @text() title!: string;
  @text() content!: string;
}

Podporované typy údajov

Použite týchto dekorátorov na definovanie typov polí:

Dekoratér Typ Description
@uuid() reťazec Pole s jedinečným identifikátorom.
@text() reťazec Textové pole s voliteľnými obmedzeniami dĺžky.
@int() číslo Celočíselné pole.
@decimal() číslo Desatinné alebo číselné pole.
@boolean() boolean Pole pravdy alebo nepravdy.
@date() Dátum Pole dátumu a času serializuje z ISO reťazcov alebo Date objektov.
@email() reťazec Textové pole s overením e-mailu.
@set() reťazec Enumerovaná množina literálov reťazcov.

Príklad s viacerými typmi

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

Typové modifikátory

Pridajte modifikátory do dekorátorov polí na konfiguráciu validácie a obmedzení:

Modifikátor Description
{ optional: true } Povoľte hodnoty NULL. Polia sú predvolene povinné.
{ unique: true } Pridajte jedinečné obmedzenie.
{ default: value } Nastavte predvolený hodnotový výraz.
{ max: n }, { min: n } Obmedzenia dĺžky reťazcov (maximálny a minimálny počet znakov).
{ min: n }, { max: n } Číselné hodnotové obmedzenia.

Poznámka

Voliteľný marker TypeScript (? po názve vlastnosti) ovplyvňuje iba statický typ TypeScriptu. Nerobí to stĺpec databázy nulovateľným. Aby bolo pole zneplatniteľné, pridaj { optional: true } do dekorátora. Použite na ! potvrdenie, že požadované pole je inicializované rámcom.

Príklad s modifikátormi

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

Definujte vzťahy

Použite @one() a dekorátory @many() na definovanie navigačných vlastností medzi entitami. Fabric Apps automaticky generujú stĺpce cudzích kľúčov, keď definujete vzťahy.

  • Jeden ku mnohým – Použitie @many() na rodiča a @one() na dieťa.
  • Many-to-one – Použite @one() na dieťa na odkaz na rodiča.
  • Vzťahy mnoho-na-mnohých nie sú podporované – namiesto toho použite explicitnú entitu spojenia.

Príklad s vzťahom jeden ku mnohým

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

Keď definujete @one(() => Notebook) na entite Note, Fabric Apps automaticky vytvorí stĺpec notebook_id cudzieho kľúča. Pole cudzieho kľúča deklarujte explicitne len vtedy, ak ho plánujete čítať alebo nastavovať v aplikačnom kóde.

Konvencia pomenovania cudzích kľúčov

Keď definujete pole cudzieho kľúča, použite {property}_id konvenciu pomenovania:

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

Vlastné názvy cudzích kľúčov (foreignKey, targetKey možnosti) nie sú podporované.

Entity referenčného systému

Fabric Apps nepodporuje vzťahy @one(), ktoré by smerovali na systémové entity, ako je zabudovaná entita USER. Na priradenie riadku k prihlásenému používateľovi pridajte obyčajné user_id pole typu @text() a vyplňte ho z autentifikačných nárokov (typicky claims.sub):

@entity()
export class Task {
  @uuid() id!: string;
  @text() title!: string;
  @text() user_id!: string;  // System user ID from claims.sub
}

Filtrujte riadky podľa user_id pravidiel vašej roly, aby ste vynútili prístup používateľa.

Registrujte entity v schéme

Pridajte všetky triedy entít do , rayfin/data/schema.ts aby klient mohol generovať GraphQL proxy:

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

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

Tento typ aktualizujte vždy, keď vytvoríte novú entitu.

Použitie zmien schémy

Po definovaní alebo úprave entít aplikujte zmeny na databázu:

  1. Nasadiť aktualizovanú schému do Fabric:

    npx rayfin up db apply

  2. Ak zmena schémy zahŕňa deštruktívne operácie (vynechávanie stĺpcov, premenovanie tabuliek), CLI vás varuje a odmieta pokračovať. Použitie --force na obídenie bezpečnostnej kontroly:

    npx rayfin up db apply --force

Poznámka

Používanie --force môže spôsobiť stratu dát. Pred pokračovaním si starostlivo preštudujte uvedené operácie.

Osvedčené postupy

  • Definujte cudzie kľúčové polia len vtedy, keď ich potrebujete čítať alebo nastaviť v kóde – Fabric Apps ich generuje automaticky z navigačných dekorátorov.
  • Používajte relatívne importy s .js príponami v súboroch entít, aby sa emitovaný ESM JavaScript správne vyriešil.
  • Pre autorizačné vzory a prístup založený na rolách pozri Definujte dátové oprávnenia.

Riešenie problémov

Chýbajúce vzťahy

Ak sa vzťahy v API nezobrazujú, overte, že:

  • Navigačný dekoratér (@one() alebo @many()) je prítomný.
  • Subjekt je registrovaný v rayfin/data/schema.ts.

Súvisiaci obsah

  • Last updated on