Définir des modèles de données pour Fabric Apps

Fabric Apps utilise des décorateurs TypeScript pour définir des modèles de données qui génèrent des tables de base de données et des API. Vous définissez chaque entité en tant que classe décorée avec @entity(), ajoutez des décorateurs de champs pour les types de données et mappez les relations entre les entités.

Pour obtenir des conseils sur le contrôle d’autorisation et d’accès, consultez Définir des autorisations de données.

Prerequisites

  • Projet Fabric Apps créé avec npm create @microsoft/rayfin@latest ou initialisé avec npx rayfin init.
  • Compréhension de base des classes et des décorateurs TypeScript.

Définir une entité

Pour créer un modèle de données, ajoutez le @entity() décorateur à une classe TypeScript. Ensuite, importez les décorateurs requis à partir de @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;
}

Cette entité génère une Todo table avec des colonnes pour id, , titledescription, , createdAtet updatedAt.

Clés primaires

Chaque entité utilise un champ UUID string nommé id comme clé primaire. Si vous ne déclarez pas id explicitement, Fabric Apps l'ajoute automatiquement au schéma.

  • Le id champ est facultatif pendant les opérations de création : le serveur génère un UUID si vous l’omettez.
  • Vous pouvez fournir votre propre UUID au moment de la création si vous préférez les identificateurs générés par le client.
  • Les clés primaires composites et les noms de clés personnalisés ne sont pas pris en charge.
@entity()
export class Note {
  @uuid() id!: string;  // UUID primary key, auto-generated when omitted
  @text() title!: string;
  @text() content!: string;
}

Types de données prises en charge

Utilisez ces décorateurs pour définir des types de champs :

Décorateur Type Description
@uuid() string Champ Identificateur unique.
@text() string Champ de texte avec contraintes de longueur facultatives.
@int() Numéro Champ de type entier.
@decimal() Numéro Champ décimal ou numérique.
@boolean() booléen Champ True ou false.
@date() Date Champ de date et d’heure, se sérialise depuis des chaînes ISO ou des objets Date.
@email() string Champ texte avec validation par e-mail.
@set() string Ensemble de littéraux de type chaîne de caractères énumérés.

Exemple avec plusieurs types

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

Modificateurs de type

Ajoutez des modificateurs aux décorateurs de champs pour configurer la validation et les contraintes :

Modificateur Description
{ optional: true } Autoriser les valeurs NULL. Les champs sont obligatoires par défaut.
{ unique: true } Ajoutez une contrainte unique.
{ default: value } Définissez une expression de valeur par défaut.
{ max: n }, { min: n } Contraintes de longueur de chaîne (nombre maximal et minimal de caractères).
{ min: n }, { max: n } Contraintes de valeur numérique.

Note

Le marqueur facultatif TypeScript (? après un nom de propriété) affecte uniquement le type TypeScript statique. Elle ne rend pas la colonne de base de données nullable. Pour rendre un champ nullable, ajoutez { optional: true } à l’élément décoratif. Utilisez ! pour indiquer qu’un champ obligatoire est initialisé par le framework.

Exemple avec des modificateurs

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

Définir des relations

Utilisez les décorateurs @one() et @many() pour définir les propriétés de navigation entre les entités. Fabric Apps génère automatiquement des colonnes clés étrangères lorsque vous définissez des relations.

  • Un-à-plusieurs : utiliser @many() sur le parent et @one() sur l’enfant.
  • Plusieurs-à-un : utiliser @one() sur l’enfant pour référencer le parent.
  • Les relations plusieurs-à-plusieurs ne sont pas prises en charge : utilisez plutôt une entité de jointure explicite.

Exemple avec une relation un-à-plusieurs

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

Lorsque vous définissez @one(() => Notebook) sur l’entité Note, Fabric Apps crée automatiquement une colonne de clé étrangère notebook_id. Déclarez explicitement le champ de clé étrangère uniquement si vous envisagez de le lire ou de le définir dans le code de l’application.

Convention d’affectation de noms de clé étrangère

Lorsque vous définissez un champ de clé étrangère, utilisez la convention d’affectation {property}_id de noms :

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

Les noms personnalisés de clés étrangères (foreignKey, targetKey options) ne sont pas pris en charge.

Entités système de référence

Fabric Apps ne prend pas en charge les relations @one() qui pointent vers des entités système telles que l'entité intégrée USER. Pour associer une ligne à l’utilisateur connecté, ajoutez un champ brut user_id de type @text() et remplissez-le à partir des revendications d’authentification (généralement claims.sub) :

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

Filtrez les lignes en fonction de user_id dans vos stratégies de rôle pour appliquer un contrôle d’accès par utilisateur.

Inscrire des entités dans le schéma

Ajoutez toutes les classes d’entités à rayfin/data/schema.ts afin que le client puisse générer des proxys GraphQL :

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

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

Mettez à jour ce type chaque fois que vous créez une entité.

Appliquer les modifications de schéma

Après avoir défini ou modifié des entités, appliquez les modifications à la base de données :

  1. Déployez le schéma mis à jour sur Fabric :

    npx rayfin up db apply

  2. Si le changement de schéma inclut des opérations destructrices (suppression de colonnes, renommage des tables), l’interface CLI vous avertit et refuse de continuer. Permet --force de remplacer le contrôle de sécurité :

    npx rayfin up db apply --force

Note

L’utilisation --force peut entraîner une perte de données. Passez en revue attentivement les opérations répertoriées avant de continuer.

Bonnes pratiques

  • Définissez les champs de clé étrangère uniquement lorsque vous devez les lire ou les définir dans le code, Fabric Apps les génère automatiquement à partir de décorateurs de navigation.
  • Utilisez des importations relatives avec les extensions .js dans les fichiers d’entité pour que le JavaScript ESM généré soit correctement résolu.
  • Pour connaître les modèles d’autorisation et l’accès en fonction du rôle, consultez Définir des autorisations de données.

Résolution des problèmes

Relations manquantes

Si les relations n’apparaissent pas dans l’API, vérifiez que :

  • Le décorateur de navigation (@one() ou @many()) est présent.
  • L’entité est inscrite dans rayfin/data/schema.ts.

Contenu connexe

  • Last updated on