Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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@latesto inicializado connpx 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
idcampo 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.
Implemente el esquema actualizado en Fabric:
npx rayfin up db applySi 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
--forcepara 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
.jsen 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.tspara una plantilla plana.