Definování datových modelů pro Fabric Apps

Fabric Apps používá dekorátory TypeScriptu k definování datových modelů, které generují databázové tabulky a rozhraní API. Každou entitu definujete jako třídu zdobenou @entity(), přidáte dekorátory polí pro datové typy a mapujete vztahy mezi entitami.

Pokyny k autorizaci a řízení přístupu najdete v tématu Definování oprávnění k datům.

Předpoklady

  • Projekt Fabric Apps vytvořený pomocí npm create @microsoft/rayfin@latest nebo inicializovaný pomocí npx rayfin init.
  • Základní znalost tříd a dekorátorů v TypeScriptu.

Definování entity

Pokud chcete vytvořit datový model, přidejte @entity() dekorátor do třídy TypeScript. Potom naimportujte požadované dekorátory 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;
}

Tato entita Todo generuje tabulku se sloupci pro id, titledescription, , createdAta updatedAt.

Primární klíče

Každá entita používá pole UUID string pojmenované id jako primární klíč. Pokud explicitně nehlásíte id, Fabric Apps ho automaticky přidá do schématu.

  • Pole id je volitelné během operací vytváření – pokud ho vynecháte, server vygeneruje UUID.
  • Pokud dáváte přednost identifikátorům generovaným klientem, můžete při vytváření zadat vlastní UUID.
  • Složené primární klíče a názvy vlastních klíčů se nepodporují.
@entity()
export class Note {
  @uuid() id!: string;  // UUID primary key, auto-generated when omitted
  @text() title!: string;
  @text() content!: string;
}

Podporované datové typy

K definování typů polí použijte tyto dekorátory:

Dekoratér Typ Description
@uuid() řetězec Pole jedinečného identifikátoru
@text() řetězec Textové pole s volitelnými omezeními délky
@int() Číslo Celočíselné pole
@decimal() Číslo Desetinné nebo číselné pole
@boolean() boolean Pole typu pravda/nepravda
@date() Date Pole pro datum a čas, serializuje se z řetězců ISO nebo objektů Date.
@email() řetězec Textové pole s ověřením e-mailu
@set() řetězec Výčtová množina řetězcových literálů

Příklad s více typy

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

Modifikátory typů

Přidání modifikátorů do dekorátorů polí pro konfiguraci ověřování a omezení:

Modifikátor Description
{ optional: true } Povolit hodnoty NULL. Pole jsou ve výchozím nastavení povinná.
{ unique: true } Přidejte jedinečné omezení.
{ default: value } Nastavte výchozí výraz hodnoty.
{ max: n }, { min: n } Omezení délky řetězce (maximální a minimální počet znaků)
{ min: n }, { max: n } Omezení číselných hodnot

Poznámka:

Volitelná značka TypeScriptu (? za názvem vlastnosti) má vliv pouze na statický typ TypeScriptu. Nenastaví databázový sloupec tak, aby povoloval hodnotu NULL. Pokud chcete nastavit pole s možnou hodnotou null, přidejte { optional: true } do dekorátoru. Slouží ! k tvrzení, že rozhraní inicializuje požadované pole.

Příklad s modifikátory

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

Definování relací

K definování vlastností navigace mezi entitami použijte @one() a @many() dekorátory. Fabric Apps automaticky generuje sloupce cizího klíče při definování relací.

  • 1:N – používá se @many() u nadřazeného objektu a @one() u podřízeného objektu.
  • Mnoho k jednomu – U podřízeného objektu použijte @one() k odkazování na nadřazený objekt.
  • Relace M:N nejsou podporovány – místo toho použijte explicitní spojovací entitu.

Příklad s relací jeden k mnoha

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

Když definujete @one(() => Notebook) u entity Note, Fabric Apps automaticky vytvoří sloupec notebook_id cizího klíče. Deklarujte pole cizího klíče explicitně pouze v případě, že plánujete číst nebo nastavovat v kódu aplikace.

Zásady vytváření názvů cizích klíčů

Při definování pole cizího klíče použijte {property}_id konvenci pojmenování:

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

Vlastní názvy cizích klíčů (foreignKey, targetKey možnosti) se nepodporují.

Referenční systémové entity

Fabric Apps nepodporuje relace @one(), které odkazují na systémové entity, jako je integrovaná entita USER. Chcete-li přiřadit řádek přihlášenému uživateli, přidejte jednoduché pole user_id typu @text() a naplňte jej z claimů ověření (obvykle claims.sub):

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

Filtrujte řádky podle user_id v zásadách rolí, abyste vynutili přístup na úrovni jednotlivých uživatelů.

Zaregistrujte entity ve schématu

Přidejte do rayfin/data/schema.ts všechny třídy entit, aby klient mohl generovat proxy objekty GraphQL:

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

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

Tento typ aktualizujte vždy, když vytvoříte novou entitu.

Použití změn ve schématu

Po definování nebo úpravě entit použijte změny v databázi:

  1. Nasaďte aktualizované schéma do Fabric:

    npx rayfin up db apply

  2. Pokud změna schématu zahrnuje destruktivní operace (vyřazení sloupců, přejmenování tabulek), rozhraní příkazového řádku vás upozorní a odmítne pokračovat. Použijte --force k obejití bezpečnostní kontroly:

    npx rayfin up db apply --force

Poznámka:

Použití --force může způsobit ztrátu dat. Než budete pokračovat, pečlivě si projděte uvedené operace.

Osvědčené postupy

  • Pole cizího klíče definujte pouze tehdy, když je potřebujete v kódu číst nebo nastavovat – aplikace Fabric je automaticky generuje z navigačních dekorátorů.
  • Používejte v souborech entit relativní importy s příponami .js, aby se vygenerovaný JavaScript ESM správně načítal.
  • Vzory autorizace a přístup na základě role najdete v tématu Definování oprávnění k datům.

Řešení problémů

Chybějící relace

Pokud se relace v rozhraní API nezobrazí, ověřte, že:

  • Nachází se dekorátor navigace (@one() nebo @many()).
  • Entita je zaregistrována v rayfin/data/schema.ts.

Související obsah

  • Last updated on