Panoramica del modello di programmazione

Rayfin SDK usa un modello di programmazione basato su decoratori in cui definisci lo schema dei dati una sola volta in TypeScript e ricevi automaticamente API pronte per l’uso in produzione, client con sicurezza di tipo e l’infrastruttura.

Concetti chiave

Rayfin SDK combina tre elementi principali:

  • Schema guidato dai decoratori: Usa i decoratori TypeScript per definire modelli di dati, autorizzazioni e relazioni.
  • Generazione automatica dell'API: le classi decorate diventano endpoint GraphQL senza scrivere codice controller.
  • Client con controllo dei tipi: i client TypeScript generati offrono la convalida in fase di compilazione per query e modifiche.

Come funziona

Quando si crea un'app Fabric, il codice passa attraverso queste fasi:

# Stage Che succede
1 Developer L'app viene creata nell'editor preferito.
2 TypeScript Le classi di entità sono scritte in TypeScript.
3 Decorators Si annotano classi e campi con @entity, @uuid, @text, @role e altri decoratori.
4 Schema L'interfaccia della riga di comando compila le classi decorate in uno schema di database, criteri di autorizzazione e configurazione API.
5 API (Interfaccia di Programmazione delle Applicazioni) Lo schema è pubblicato come endpoint GraphQL.
6 Client L'elemento generato RayfinClient espone un client per dati e autenticazione con sicurezza di tipo tramite quegli endpoint.
7 Applicazione L'applicazione front-end usa il client per leggere e scrivere dati.

1. Definire modelli di dati con i decorator

Definisci la struttura dei dati utilizzando classi TypeScript e decoratori da @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. Generazione dello schema

La CLI di Rayfin (npx rayfin) analizza le classi decorate e genera:

  • Schema del database - Tabelle, colonne, vincoli e indici
  • Configurazione dell'API - Definizioni di endpoint GraphQL
  • Criteri di autorizzazione - Sicurezza a livello di riga e controllo di accesso a livello di campo

4. Utilizzo del client con controllo dei tipi

Le API GraphQL sono disponibili per eseguire operazioni CRUD nel database. Rayfin SDK fornisce pronta all'uso un'operazione client per i dati per leggere, scrivere o eliminare dati.

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();

Informazioni di riferimento su Decorator

Rayfin SDK fornisce decoratori per schemi comuni di modellazione dei dati:

Decoratori di entità

Decoratore Purpose Example
@entity() Contrassegnare una classe come entità di database @entity() class Product

Decoratori di proprietà

Decoratore Tipo di database Tipo TypeScript
@uuid() UNIQUEIDENTIFIER string
@text() NVARCHAR string
@int() INT number
@decimal() DECIMALE number
@bool() BIT boolean
@date() DATETIME2 Date

Decoratori dei permessi

Decoratore Purpose
@role() Definire le autorizzazioni basate sui ruoli

Per informazioni dettagliate sull'autorizzazione, vedere Definire le autorizzazioni per i dati .

Flusso di lavoro per lo sviluppo

Un ciclo di sviluppo tipico segue questo modello:

  1. Definire o modificare i modelli di dati - Aggiungere o aggiornare classi TypeScript con elementi Decorator
  2. Esegui test in locale con backend remoto - Esegui npm run dev per testare le modifiche al codice frontend con il backend dell'app in Fabric.
  3. Distribuisci in Fabric - Esegui npx rayfin up per distribuire nel servizio Fabric gestito e applicare le modifiche allo schema.

Le modifiche apportate ai modelli TypeScript vengono propagate automaticamente nell'intero stack, dallo schema del database agli endpoint API ai tipi di client.

Authorization

Le autorizzazioni vengono definite insieme ai modelli di dati utilizzando il decoratore @role:

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

Questo approccio garantisce:

  • Le regole di sicurezza si trovano accanto ai dati che proteggono
  • Le espressioni di criteri con controllo dei tipi intercettano gli errori in fase di compilazione
  • Il refactoring dei campi dell'entità aggiorna automaticamente i controlli delle autorizzazioni

Contenuti correlati

  • Last updated on