Přehled programovacího modelu

Rayfin SDK používá programovací model založený na dekorátorech, ve kterém stačí jednou definovat datové schéma v jazyce TypeScript a automaticky získáte produkčně připravená API, typově bezpečné klienty a infrastrukturu.

Klíčové koncepty

Sada Rayfin SDK kombinuje tři základní prvky:

  • Schéma řízené dekorátorem: K definování datových modelů, oprávnění a relací použijte dekorátory TypeScriptu.
  • Automatické generování rozhraní API: Upravené třídy se stanou koncovými body GraphQL bez psaní kódu kontroleru.
  • Typově bezpeční klienti: Vygenerovaní klienti v jazyce TypeScript poskytují ověřování při kompilaci pro dotazy a mutace.

Jak to funguje

Když vytvoříte Fabric aplikaci, kód prochází těmito fázemi:

# Stage Co se stane
1 Developer Aplikaci vytvoříte v libovolném editoru.
2 TypeScript Třídy entit píšete v TypeScriptu.
3 Decorators Třídy a pole můžete komentovat pomocí @entity, @uuid, @text, @role, a dalších dekorátorů.
4 Schema Rozhraní příkazového řádku zkompiluje upravené třídy do schématu databáze, zásad oprávnění a konfigurace rozhraní API.
5 APIs Schéma je publikováno jako endpointy GraphQL.
6 Client Vygenerovaný RayfinClient zpřístupňuje typově bezpečného klienta pro data a autentizaci nad těmito koncovými body.
7 Application Front-endová aplikace využívá klienta ke čtení a zápisu dat.

1. Definování datových modelů s dekorátory

Datovou strukturu definujete pomocí tříd TypeScriptu a dekorátorů 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. Generování schématu

Rayfin CLI (npx rayfin) analyzuje vaše zdobené třídy a generuje:

  • Schéma databáze – tabulky, sloupce, omezení a indexy
  • Konfigurace rozhraní API – definice koncových bodů GraphQL
  • Zásady oprávnění – zabezpečení na úrovni řádků a řízení přístupu na úrovni polí

4. Použití klienta bezpečného typu

Rozhraní GraphQL API jsou k dispozici pro provádění operací CRUD ve vaší databázi. Sada Rayfin SDK poskytuje operaci datového klienta za účelem čtení nebo zápisu nebo odstranění dat.

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

Reference dekorátorů

Sada Rayfin SDK poskytuje dekorátory pro běžné vzory modelování dat:

Dekorátory entit

Dekoratér Purpose Example
@entity() Označení třídy jako databázové entity @entity() class Product

Dekorátory vlastností

Dekoratér Typ databáze typ TypeScriptu
@uuid() UNIQUEIDENTIFIER string
@text() NVARCHAR string
@int() INT number
@decimal() DESETINNÉ ČÍSLO number
@bool() BIT boolean
@date() DATETIME2 Date

Dekorátory oprávnění

Dekoratér Purpose
@role() Definování oprávnění založených na rolích

Podrobnosti o autorizaci najdete v tématu Definování oprávnění k datům .

Functions

Vytvořte jednu UserDataFunctions instanci a zaregistrujte každou funkci voláním udf.func(name, handler, connections?).

Při definování funkce postupujte podle těchto pravidel:

  • Umístěte RayfinContext parametr kamkoli do podpisu handleru. Runtime jej identifikuje podle typu, vkládá a vylučuje z generovaných vstupů funkcí.
  • Deklarujte spojení pro každý delegovaný token, který funkce potřebuje. Vynechte pole spojení pro funkce, které přistupují pouze k datům aplikací nebo nepotřebují delegované tokeny.

Následující příklad registruje obyčejnou funkci a funkci, která využívá kontext vyvolá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';
  },
);

RayfinContext poskytuje služby modulu runtime pro funkci:

Člen Purpose
ctx.accessToken Poskytuje přihlášenému uživateli Rayfin JSON Web Token (JWT). Dekódujte atribut sub, abyste získali stabilní uživatelské ID.
ctx.Tokens.<Audience> Získá platformou poskytnutý token zdroje pro publikum deklarované v RayfinContext anotaci. Nasazené funkce využívají identitu aplikace a její oprávnění. Podrobnosti viz Připojit funkce k externím zdrojům.
ctx.getSecret('NAME') Získá tajemství pro aktuální invokaci. Vrací undefined, když tajný klíč není nastaven.
ctx.getDataClient() Získá API pro typovaná data pro vaše entity. Klient podporuje operace vytváření, findManyaktualizace, mazání a upsertování.
ctx.baseUrl Poskytuje Rayfin endpoint pro aktuální položku.
ctx.publishableKey Poskytuje publikovatelný klíč pro aktuální položku.

Pro pokyn k nastavení, lokálnímu ladění a nasazení viz Funkce použití ve Fabric Apps.

Pracovní postup vývoje

Typický vývojový cyklus se řídí tímto vzorem:

  1. Definování nebo úprava datových modelů – Přidání nebo aktualizace tříd TypeScriptu pomocí dekorátorů
  2. Testujte místně pomocí vzdáleného back-endu – Spuštěním příkazu npm run dev otestujte změny kódu front-endu v back-endu vaší aplikace v Fabric.
  3. Deploy to Fabric – Spusťte npx rayfin up, chcete-li nasadit do spravované služby Fabric a použít změny schématu.

Změny ve vašich modelech TypeScript se automaticky promítnou do celého stacku – od schématu databáze přes koncové body API až po klientské typy.

Authorization

Oprávnění se definují společně s datovými modely pomocí dekorátoru @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 přístup zajišťuje:

  • Bezpečnostní pravidla jsou přímo u dat, která chrání
  • Typově bezpečné výrazy zásad zachycují chyby při kompilaci.
  • Při refaktoringu polí v entitě se automaticky aktualizují kontroly oprávnění.

Související obsah

  • Poslední aktualizace v