Introducción al modelo de programación

El SDK de Rayfin usa un modelo de programación controlado por decoradores en el que se define el esquema de datos una vez en TypeScript y se reciben automáticamente las API listas para producción, los clientes seguros para tipos y la infraestructura.

Conceptos clave

El SDK de Rayfin combina tres elementos principales:

  • Esquema basado en decoradores: Use decoradores de TypeScript para definir modelos de datos, permisos y relaciones.
  • Generación automática de API: las clases decoradas se convierten en puntos de conexión de GraphQL sin escribir código de controlador.
  • Clientes con seguridad de tipos: los clientes TypeScript generados proporcionan validación en tiempo de compilación para consultas y mutaciones.

Cómo funciona

Al crear una aplicación de Fabric, el código fluye a través de estas fases:

# Stage ¿Qué ocurre?
1 Desarrollador Crea la aplicación en el editor que prefiera.
2 TypeScript Las clases de entidad se escriben en TypeScript.
3 Decorators Anota las clases y los campos con @entity, @uuid, @text, @roley otros decoradores.
4 Schema La CLI compila las clases decoradas en un esquema de base de datos, directivas de permisos y configuración de API.
5 APIs (Interfaz de Programación de Aplicaciones) El esquema se publica como puntos de conexión de GraphQL.
6 Client El RayfinClient generado expone un cliente de datos y autenticación con seguridad de tipos para esos puntos de conexión.
7 Application La aplicación de front-end consume el cliente para leer y escribir datos.

1. Definir modelos de datos con decoradores

La estructura de datos se define mediante clases y decoradores de TypeScript de @microsoft/rayfin-core:

import { entity, uuid, text, int } from '@microsoft/rayfin-core';

@entity()
export class Product {
  @uuid() id!: string;
  @text() name!: string;
  @text({ optional: true }) description?: string;
  @int() price!: number;
}

2. Generación de esquemas

La CLI de Rayfin (npx rayfin) analiza las clases decoradas y genera:

  • Esquema de base de datos : tablas, columnas, restricciones e índices
  • Configuración de API : definiciones de punto de conexión de GraphQL
  • Directivas de permisos : seguridad de nivel de fila y control de acceso de nivel de campo

4. Uso de cliente seguro para tipos

Las API de GraphQL están disponibles para realizar operaciones CRUD en la base de datos. El SDK de Rayfin proporciona de forma predeterminada una operación de cliente para leer, escribir o eliminar datos.

import { RayfinClient } from '@microsoft/rayfin-client';

const client = new RayfinClient();

// TypeScript knows about Product fields
const products = await client.data.products.query()
  .select(['id', 'name', 'price'])
  .execute();

// Compile-time error if field doesn't exist
const invalid = await client.data.products.query()
  .select(['nonexistentField'])  // ❌ TypeScript error
  .execute();

Referencia del decorador

El SDK de Rayfin proporciona decoradores para patrones comunes de modelado de datos:

Decoradores de entidades

Decorador Purpose Ejemplo
@entity() Marcar una clase como una entidad de base de datos @entity() class Product

Decoradores de propiedades

Decorador Tipo de base de datos Tipo typeScript
@uuid() UNIQUEIDENTIFIER string
@text() NVARCHAR string
@int() INT number
@decimal() DECIMAL number
@bool() BIT boolean
@date() FECHA Y HORA 2 Date

Decoradores de permisos

Decorador Purpose
@role() Definición de permisos basados en roles

Consulte Definición de permisos de datos para obtener detalles de autorización.

Functions

Crea una UserDataFunctions instancia y registra cada función llamando udf.func(name, handler, connections?)a .

Sigue estas reglas cuando definas una función:

  • Coloca el RayfinContext parámetro en cualquier parte de la firma del manejador. El entorno de ejecución lo identifica por tipo, lo inyecta y lo excluye de los parámetros de entrada de la función generada.
  • Declara una conexión para cada token delegado que la función necesita. Omite el array de conexiones para funciones que solo acceden a datos de apps o que no necesitan tokens delegados.

El siguiente ejemplo registra una función sencilla y una función que utiliza el contexto de invocación:

import {
  UserDataFunctions,
  type RayfinContext,
} from '@microsoft/fabric-user-data-functions';

// Match rayfin/data/schema.ts so getDataClient() is fully typed.
import type { TripPlan } from '../../data/TripPlan.js';

type AppSchema = { TripPlan: TripPlan };

const udf = new UserDataFunctions();

udf.func('greet', async (name: string): Promise<string> => {
  return `Hello, ${name}!`;
});

udf.func(
  'whoAmI',
  async (ctx: RayfinContext<AppSchema>): Promise<string> => {
    return ctx.accessToken ? 'authenticated' : 'anonymous';
  },
);

El RayfinContext proporciona los servicios de tiempo de ejecución de la función:

Miembro Purpose
ctx.accessToken Proporciona el Rayfin JSON Web Token (JWT) del usuario iniciado sesión. Descodifica la notificación sub para obtener un identificador de usuario estable.
ctx.Tokens.<Audience> Obtiene un token de recurso proporcionado por la plataforma para la audiencia declarada en la anotación RayfinContext. Las Funciones Desplegadas utilizan la identidad de la aplicación y sus permisos. Para más detalles, consulte Conectar funciones a recursos externos.
ctx.getSecret('NAME') Obtiene un secreto para la invocación actual. Devuelve undefined cuando el secreto no se ha configurado.
ctx.getDataClient() Obtiene la API de datos tipados para tus entidades. El cliente soporta operaciones de creación, findManyactualización, eliminación y upsert.
ctx.baseUrl Proporciona el punto final Rayfin para el elemento actual.
ctx.publishableKey Proporciona la clave publicable para el elemento actual.

Para la configuración, depuración local y instrucciones de despliegue, consulta Usar funciones en aplicaciones Fabric.

Flujo de trabajo de desarrollo

Un ciclo de desarrollo típico sigue este patrón:

  1. Definir o modificar modelos de datos : agregar o actualizar clases typeScript con decoradores
  2. Pruebe localmente con un backend remoto - Ejecute npm run dev para probar los cambios del código de su frontend con el backend de su aplicación en Fabric.
  3. Implementar en Fabric - Ejecuta npx rayfin up para implementar en el servicio administrado de Fabric y aplicar los cambios en el esquema.

Los cambios en los modelos de TypeScript se propagan automáticamente a través de toda la pila, desde el esquema de base de datos hasta los puntos de conexión de API a los tipos de cliente.

Authorization

Los permisos se definen junto con los modelos de datos mediante el @role decorador:

@entity()
@role('authenticated', ['create', 'read', 'update', 'delete'], {
  policy: (claims, item) => claims.sub.eq(item.userId)
})
export class UserDocument {
  @uuid() id!: string;
  @text() userId!: string;
  @text() content!: string;
}

Este enfoque garantiza:

  • Las reglas de seguridad residen junto a los datos que protegen
  • Las expresiones de directiva seguras para tipos detectan errores en tiempo de compilación
  • La refactorización de campos de entidad actualiza automáticamente las comprobaciones de permisos.

Contenido relacionado

  • Se actualizó por última vez el