Overzicht van programmeermodel

Rayfin SDK maakt gebruik van een decoratorgestuurd programmeermodel waarin u uw gegevensschema eenmaal in TypeScript definieert en automatisch api's ontvangt die gereed zijn voor productie, typeveilige clients en infrastructuur.

belangrijke concepten

Rayfin SDK combineert drie kernelementen:

  • Decoratorgestuurd schema: TypeScript-decorators gebruiken om gegevensmodellen, machtigingen en relaties te definiëren.
  • Automatische API-generatie: uw versierde klassen worden GraphQL-eindpunten zonder controllercode te schrijven.
  • Typeveilige clients: Gegenereerde TypeScript-clients bieden compileertijdvalidatie voor query's en mutaties.

Hoe werkt het?

Wanneer u een Fabric-app maakt, loopt uw code door deze fasen:

# Stage Wat gebeurt er?
1 Ontwikkelaar U ontwerpt de app in de gewenste editor.
2 TypeScript U schrijft entiteitsklassen in TypeScript.
3 Decorators U annoteert klassen en velden met @entity, @uuid, @text, @role en andere decorateurs.
4 Schema De CLI compileert de versierde klassen in een databaseschema, machtigingsbeleid en API-configuratie.
5 APIs Het schema wordt gepubliceerd als GraphQL-eindpunten.
6 Client De gegenereerde RayfinClient biedt een typeveilige data- en authenticatieclient voor die eindpunten.
7 Application Uw front-endtoepassing verbruikt de client om gegevens te lezen en te schrijven.

1. Gegevensmodellen definiëren met decorators

U definieert uw gegevensstructuur met behulp van TypeScript-klassen en decorators van @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. Schemageneratie

De Rayfin CLI (npx rayfin) analyseert uw gedecoreerde klassen en genereert:

  • Databaseschema - Tabellen, kolommen, beperkingen en indexen
  • API-configuratie - GraphQL-eindpuntdefinities
  • Machtigingsbeleid - Beveiliging op rijniveau en toegangsbeheer op veldniveau

4. Typeveilig clientgebruik

GraphQL-API's zijn beschikbaar voor het uitvoeren van CRUD-bewerkingen in uw database. Rayfin SDK biedt standaard een dataclientbewerking om gegevens te lezen, te schrijven of te verwijderen.

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

Naslaginformatie voor decorators

Rayfin SDK biedt decorators voor algemene patronen voor gegevensmodellering:

Entiteitsdecorateurs

Decorateur Purpose Example
@entity() Een klasse markeren als een database-entiteit @entity() class Product

Decorators voor eigenschappen

Decorateur Database-type TypeScript-type
@uuid() UNIQUEIDENTIFIER string
@text() NVARCHAR string
@int() INT number
@decimal() Decimaal number
@bool() BIT boolean
@date() DATETIME2 Date

Machtigingsinrichtingen

Decorateur Purpose
@role() Machtigingen op basis van rollen definiëren

Zie Gegevensmachtigingen definiëren voor autorisatiedetails.

Functions

Maak één UserDataFunctions instantie aan en registreer elke functie door aan te roepen udf.func(name, handler, connections?).

Volg deze regels wanneer je een functie definieert:

  • Plaats de RayfinContext parameter ergens in de handlerhandtekening. De runtime identificeert het op type, injecteert het en sluit het uit van de gegenereerde functie-invoer.
  • Verklaar een verbinding voor elk gedelegeerd token dat de functie nodig heeft. Laat de verbindingsarray weg voor functies die alleen app-data benaderen of geen gedelegeerde tokens nodig hebben.

Het volgende voorbeeld registreert een gewone functie en een functie die de aanroepcontext gebruikt:

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

De RayfinContext levert de runtime-diensten van de functie:

Lid Purpose
ctx.accessToken Biedt de Rayfin JSON Web Token (JWT) van de ingelogde gebruiker. Decodeer de sub claim om een stabiele gebruikers-ID te krijgen.
ctx.Tokens.<Audience> Krijgt een door het platform verstrekte resourcetoken voor een publiek dat in de RayfinContext annotatie is opgegeven. Uitgerolde functies gebruiken de app-identiteit en de bijbehorende permissies. Voor details, zie Verbind functies met externe bronnen.
ctx.getSecret('NAME') Haalt een geheim op voor de huidige aanroep. Geeft undefined terug als het geheim niet is ingesteld.
ctx.getDataClient() Hiermee krijgt u de API voor getypeerde gegevens voor uw entiteiten. De client ondersteunt bewerkingen voor aanmaken, findManybijwerken, verwijderen en upserten.
ctx.baseUrl Geeft het Rayfin-eindpunt voor het huidige item.
ctx.publishableKey Biedt de publiceerbare sleutel voor het huidige item.

Voor setup-, lokale debugging- en deployment-instructies, zie Use Functions in Fabric Apps.

Ontwikkelwerkstroom

Een typische ontwikkelingscyclus volgt dit patroon:

  1. Gegevensmodellen definiëren of wijzigen - TypeScript-klassen toevoegen of bijwerken met decorators
  2. Test lokaal met externe back-end - voer npm run dev uit om de wijzigingen in de front-endcode te testen op uw app-back-end in Fabric.
  3. Implementeren naar Fabric - voer npx rayfin up uit om te implementeren naar de beheerde Fabric-service en uw schemawijzigingen toe te passen.

Wijzigingen in uw TypeScript-modellen worden automatisch doorgegeven via de hele stack, van databaseschema naar API-eindpunten tot clienttypen.

Authorization

Machtigingen worden naast uw gegevensmodellen gedefinieerd met behulp van de @role decorator:

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

Deze aanpak zorgt voor het volgende:

  • Beveiligingsregels leven naast de gegevens die ze beveiligen
  • Typeveilige beleidsexpressies vangen fouten op tijdens het compileren
  • Bij het herstructureren van entiteitsvelden worden machtigingscontroles automatisch bijgewerkt

Verwante inhoud

  • Laatst bijgewerkt om