Definición de modelos de datos para aplicaciones de Fabric

Fabric Apps usa decoradores typeScript para definir modelos de datos que generan tablas y API de base de datos. Cada entidad se define como una clase decorada con @entity(), se agregan decoradores de campo para tipos de datos y se asignan relaciones entre entidades.

Para obtener instrucciones sobre autorización y control de acceso, consulte Definición de permisos de datos.

Prerequisites

  • Un proyecto Fabric Apps creado con npm create @microsoft/rayfin@latest o inicializado con npx rayfin init.
  • Conocimientos básicos de las clases y decoradores de TypeScript.

Definición de una entidad

La plantilla predeterminada blankapp crea un espacio de trabajo de aplicación universal con Datos desactivados. Actívala con la función de modelado de datos de la plantilla:

npm run pack:add -- data-modeling

Este paso añade una entidad inicial y un contrato compartido. Incluir clases de entidad en packages/data/src/, registrarlas en packages/data/src/index.ts, y mantener sus contratos de cara al cliente en packages/shared/src/index.ts. El servicio de datos utiliza services.data.path: packages/data en rayfin/rayfin.yml. Cuando configuras manualmente los datos para Fabric, también configura enabled: true y dialect: mssql.

Las plantillas planas pueden mantener las entidades en rayfin/data/ y usar rayfin/data/schema.ts. Sigue tus rutas de servicio configuradas en lugar de crear una segunda carpeta de datos. Véase Estructura del proyecto.

Para crear un modelo de datos, agregue el @entity() decorador a una clase TypeScript. A continuación, importe los decoradores necesarios desde @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;
}

Esta entidad genera una Todo tabla con columnas para id, title, description, createdAty updatedAt.

Importante

Asigna a los campos de texto persistentes una longitud máxima explícita adecuada para tus datos. En Microsoft SQL Server, el texto sin max genera NVARCHAR(MAX), lo que puede impedir la generación de metadatos de GraphQL. Los ejemplos utilizan texto acotado, incluyendo cadenas de propietario y de clave foránea. Consulta Solucionar problemas con el modelo de datos.

Claves principales

Cada entidad usa un campo UUID string denominado id como clave principal. Si no declara id explícitamente, Fabric Apps lo agrega al esquema automáticamente.

  • El id campo es opcional durante las operaciones de creación; el servidor genera un UUID si lo omite.
  • Puede proporcionar su propio UUID en tiempo de creación si prefiere identificadores generados por el cliente.
  • No se admiten claves principales compuestas ni nombres de clave personalizados.
@entity()
export class Note {
  @uuid() id!: string;  // UUID primary key, auto-generated when omitted
  @text({ max: 200 }) title!: string;
  @text({ max: 4000 }) content!: string;
}

Supported data types (Tipos de datos admitidos)

Use estos decoradores para definir tipos de campo:

Decorador Tipo Descripción
@uuid() string Campo de identificador único.
@text({ max: n }) string Campo de texto con una longitud máxima explícita para columnas MSSQL persistentes.
@int() número Campo entero.
@decimal() número Campo decimal o numérico.
@boolean() booleano Campo verdadero o falso.
@date() Date Campo de fecha y hora, se serializa desde cadenas en formato ISO o objetos Date.
@email() string Campo de texto con validación de correo electrónico.
@set() string Conjunto enumerado de literales de cadena de texto.

Ejemplo con varios tipos

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

Modificadores de tipo

Agregue modificadores a decoradores de campo para configurar la validación y las restricciones:

Modificador Descripción
{ optional: true } Permitir valores NULL. Los campos son obligatorios de forma predeterminada.
{ unique: true } Agregue una restricción única.
{ default: value } Establezca una expresión de valor predeterminada.
{ max: n }, { min: n } Restricciones de longitud de cadena (número máximo y mínimo de caracteres).
{ min: n }, { max: n } Restricciones de valores numéricos.

Note

El marcador opcional TypeScript (? después de un nombre de propiedad) solo afecta al tipo TypeScript estático. No hace que la columna de base de datos admita valores NULL. Para hacer que un campo admita valores NULL, añada { optional: true } al decorador. Use ! para afirmar que el marco inicializa un campo obligatorio.

Ejemplo con modificadores

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

Definir relaciones

Use @one() y @many() decoradores para definir propiedades de navegación entre entidades. Fabric Apps genera automáticamente columnas de clave externa al definir las relaciones.

  • De uno a varios – Use @many() en el elemento principal y @one() en el elemento secundario.
  • Muchos a uno – Use @one() en el elemento secundario para hacer referencia al elemento padre.
  • No se admiten relaciones de muchos a muchos; use en su lugar una entidad de unión explícita.

Ejemplo con una relación de uno a varios

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

Al definir @one(() => Notebook) en la entidad Note, Fabric Apps crea automáticamente una columna de clave externa notebook_id. Declare explícitamente el campo de clave externa solo si planea leerlo o establecerlo en el código de aplicación.

Convención de nomenclatura de clave foránea

Al definir un campo de clave foránea, use la convención de nomenclatura {property}_id:

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

No se admiten nombres de clave externa personalizados (foreignKey, targetKey opciones).

Entidades del sistema de referencia

Fabric Apps no admite relaciones @one() que apuntan a entidades del sistema como la entidad integrada USER. Para asociar una fila con el usuario que ha iniciado sesión, añade un campo de texto vinculado user_id y rellénalo a partir de las reclamaciones de autenticación (normalmente 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
}

Filtre las filas por user_id en las directivas de rol para aplicar el acceso por usuario.

Registro de entidades en el esquema

En un espacio de trabajo de Universal App, registra clases de entidad del tiempo de ejecución en packages/data/src/index.ts:

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

export const schema = [Note, Notebook];

Mantén las interfaces de registros correspondientes y el mapeo de UniversalAppSchema en packages/shared/src/index.ts alineados con esas entidades. El frontend importa UniversalAppSchema desde @rayfin-app/shared; no importa clases de runtime decoradas. Añade Product a ambos registros si usas ejemplos de agregación numérica en Leer y escribir datos.

Para una alternativa de plantilla plana, asigna los tipos de entidad en rayfin/data/schema.ts:

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

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

Actualiza los registros y tipos de esquema para el diseño elegido cada vez que crees una nueva entidad.

Aplicar los cambios de esquema.

Después de definir o modificar las entidades, aplica los cambios a la base de datos. Para ver el flujo de trabajo completo de despliegue y verificación, consulte Aplicar y verificar cambios de esquema.

  1. Implemente el esquema actualizado en Fabric:

    npx rayfin up db apply
    
  2. Si el cambio de esquema incluye operaciones destructivas (quitar columnas, cambiar el nombre de las tablas), la CLI le advierte y se niega a continuar. Use --force para invalidar la comprobación de seguridad:

    npx rayfin up db apply --force
    

Note

El uso --force de puede provocar la pérdida de datos. Revise detenidamente las operaciones enumeradas antes de continuar.

procedimientos recomendados

  • Defina campos de clave externa solo cuando necesite leerlos o establecerlos en el código; Fabric Aplicaciones los genera automáticamente a partir de decoradores de navegación.
  • Use importaciones relativas con extensiones .js en archivos de entidad para que el JavaScript ESM generado se resuelva correctamente.
  • Para conocer los patrones de autorización y el acceso basado en roles, consulte Definición de permisos de datos.

Solución de problemas

Relaciones que faltan

Si las relaciones no aparecen en la API, compruebe que:

  • El decorador de navegación (@one() o @many()) está presente.
  • La entidad está registrada en tu paquete de datos configurado y esquema compartido, o en rayfin/data/schema.ts para una plantilla plana.