Prehľad programovacieho modelu

Rayfin SDK používa programovací model riadený dekorátormi, kde definujete dátovú schému raz v TypeScripte a automaticky prijímate produkčne pripravené API, typovo bezpečné klienty a infraštruktúru.

Kľúčové pojmy

Rayfin SDK kombinuje tri základné prvky:

  • Schéma riadená dekorátormi: Použite dekorátorov TypeScript na definovanie dátových modelov, povolení a vzťahov.
  • Automatická generácia API: Vaše ozdobené triedy sa stanú endpointmi GraphQL bez písania controller kódu.
  • Type-safe klienti: Generovaní TypeScript klienti poskytujú validáciu v čase kompilácie pre dotazy a mutácie.

Ako to funguje

Keď vytvoríte Fabric aplikáciu, váš kód prechádza týmito fázami:

# Fáza Čo sa stane
1 Vývojár Aplikáciu vytvárate vo svojom vybranom editore.
2 TypeScript Triedy entít píšete v TypeScripte.
3 Dekoratéri Triedy a polia anotujete pomocou @entity, @uuid, @text, @role, a ďalších dekoratérov.
4 Schema CLI kompiluje ozdobené triedy do databázovej schémy, povolovacích politík a konfigurácie API.
5 Rozhrania API Schéma je publikovaná ako GraphQL endpointy.
6 Klient Generovaný RayfinClient model vystavuje typovo bezpečného klienta dát a autentifikácie nad týmito koncovými bodmi.
7 Aplikácia Vaša frontendová aplikácia spotrebúva klienta na čítanie a zápis dát.

1. Definujte dátové modely pomocou dekorátorov

Svoju dátovú štruktúru definujete pomocou tried TypeScript a dekorátorov z @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. Generovanie schémy

Rayfin CLI (npx rayfin) analyzuje vaše dekorované triedy a generuje:

  • Schéma databázy - Tabuľky, stĺpce, obmedzenia a indexy
  • Konfigurácia API - Definície koncových bodov GraphQL
  • Politiky povolení - Bezpečnosť na úrovni riadkov a riadenie prístupu na úrovni poľa

4. Typovo bezpečné používanie klientov

GraphQL API sú dostupné na vykonávanie CRUD operácií vo vašej databáze. Rayfin SDK poskytuje dátovú klientskú operáciu hneď po inštalácii na čítanie, zápis alebo mazanie dát.

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 dekoratéra

Rayfin SDK poskytuje dekorátorov pre bežné vzory modelovania dát:

Dekoratéri entít

Dekoratér Purpose Príklad
@entity() Označte triedu ako databázovú entitu @entity() class Product

Dekoratéri nehnuteľností

Dekoratér Typ databázy TypeScript typ
@uuid() UNIQUEIDENTIFIER string
@text() NVARCHAR string
@int() INT number
@decimal() DESATINNÝ number
@bool() BIT boolean
@date() DATETIME2 Date

Dekoratéri povolení

Dekoratér Purpose
@role() Definujte oprávnenia založené na rolách

Pozri Definuj dátové oprávnenia pre podrobnosti o autorizácii.

Funkcie

Vytvor jednu UserDataFunctions inštanciu a zaregistruj každú funkciu volaním udf.func(name, handler, connections?).

Pri definovaní funkcie postupujte podľa týchto pravidiel:

  • Umiestnite RayfinContext parameter kdekoľvek do podpisu handlera. Runtime ho identifikuje podľa typu, vstrekuje a vylučuje z generovaných vstupov funkcií.
  • Deklarujte spojenie pre každý delegovaný token, ktorý funkcia potrebuje. Vynechajte pole spojení pre funkcie, ktoré pristupujú len k dátam aplikácie alebo nepotrebujú delegované tokeny.

Nasledujúci príklad registruje obyčajnú funkciu a funkciu, ktorá používa kontext vyvolávania:

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

Poskytuje RayfinContext runtime služby funkcie:

Člen Purpose
ctx.accessToken Poskytuje prihlásenému používateľovi Rayfin JSON Web Token (JWT). Rozlúšte tvrdenie, sub aby ste získali stabilné používateľské ID.
ctx.Tokens.<Audience> Získa platformou poskytnutý token zdroja pre publikum deklarované v anotácii RayfinContext . Nasadené funkcie používajú identitu aplikácie a jej oprávnenia. Podrobnosti nájdete v článku Pripojiť funkcie k externým zdrojom.
ctx.getSecret('NAME') Získa tajomstvo pre aktuálnu invokáciu. Vracia sa undefined , keď tajomstvo nie je jasné.
ctx.getDataClient() Získa API pre typované dáta pre vaše entity. Klient podporuje operácie vytvárania, findManyaktualizácie, mazania a upsertovania.
ctx.baseUrl Poskytuje Rayfin endpoint pre aktuálnu položku.
ctx.publishableKey Poskytuje publikovateľný kľúč pre aktuálnu položku.

Pre pokyny na nastavenie, lokálne ladenie a nasadenie pozri Funkcie použitia v Fabric Apps.

Vývojový pracovný postup

Typický vývojový cyklus nasleduje tento vzorec:

  1. Definujte alebo upravujte dátové modely - Pridajte alebo aktualizujte triedy TypeScript pomocou dekorátorov
  2. Otestujte lokálne s remote backendom - Spustite npm run dev na testovanie zmien frontendového kódu na backende aplikácie v Fabric.
  3. Nasadiť do Fabric - Spustiť npx rayfin up na nasadenie do spravovanej Fabric služby a aplikovať zmeny schémy.

Zmeny vo vašich TypeScript modeloch sa automaticky šíria cez celý stack — od databázovej schémy cez API endpointy až po typy klientov.

Authorization

Povolenia sú definované spolu s vašimi dátovými modelmi pomocou dekorátora @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;
}

Tento prístup zabezpečuje:

  • Bezpečnostné pravidlá platia vedľa dát, ktoré chránia
  • Typovo bezpečné politické výrazy zachytávajú chyby pri kompilácii
  • Refaktorovacie polia entít automaticky aktualizujú kontroly oprávnení

Súvisiaci obsah

  • Naposledy aktualizované: