Übersicht über das Programmiermodell

Rayfin SDK verwendet ein dekoratorgesteuertes Programmiermodell, bei dem Sie Ihr Datenschema einmal in TypeScript definieren und automatisch produktionsreife APIs, typsichere Clients und Infrastruktur erhalten.

Wichtige Begriffe

Rayfin SDK kombiniert drei Kernelemente:

  • Dekoriergesteuertes Schema: Verwenden Sie TypeScript-Dekoratoren, um Datenmodelle, Berechtigungen und Beziehungen zu definieren.
  • Automatische API-Generierung: Ihre dekorierten Klassen werden automatisch zu GraphQL-Endpunkten, ohne Controller-Code schreiben zu müssen.
  • Typsichere Clients: Generierte TypeScript-Clients bieten eine Kompilierungszeitüberprüfung für Abfragen und Mutationen.

So funktioniert es

Wenn Sie eine Fabric-App erstellen, fließt Ihr Code durch die folgenden Phasen:

# Stage Was ist los
1 Developer Sie erstellen die App in Ihrem Editor der Wahl.
2 Typescript Sie schreiben Entitätsklassen in TypeScript.
3 Decorators Sie annotieren Klassen und Felder mit @entity, @uuid, @text, @role und anderen Dekoratoren.
4 Schema Die CLI kompiliert die dekorierten Klassen zu einem Datenbankschema, Berechtigungsrichtlinien und einer API-Konfiguration.
5 APIs Das Schema wird als GraphQL-Endpunkte veröffentlicht.
6 Client Die generierte RayfinClient stellt einen typsicheren Daten- und Authentifizierungsclient für diese Endpunkte bereit.
7 Application Ihre Frontend-Anwendung verwendet den Client zum Lesen und Schreiben von Daten.

1. Definieren Sie Datenmodelle mit Dekoratoren

Sie definieren Ihre Datenstruktur mithilfe von TypeScript-Klassen und Dekoratoren aus @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. Schemagenerierung

Die Rayfin CLI (npx rayfin) analysiert Ihre eingerichteten Kurse und generiert:

  • Datenbankschema – Tabellen, Spalten, Einschränkungen und Indizes
  • API-Konfiguration – GraphQL-Endpunktdefinitionen
  • Berechtigungsrichtlinien – Sicherheits- und Zugriffssteuerung auf Feldebene

4. Typsichere Verwendung des Clients

GraphQL-APIs stehen zur Verfügung, um CRUD-Vorgänge in Ihrer Datenbank auszuführen. Das Rayfin SDK stellt standardmäßig eine Datenclient-Operation zum Lesen, Schreiben oder Löschen von Daten bereit.

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

Dekorateurreferenz

Rayfin SDK bietet Dekoratoren für allgemeine Datenmodellierungsmuster:

Entitätsdekoratoren

Dekorateur Purpose Example
@entity() Kennzeichnen einer Klasse als Datenbankentität @entity() class Product

Eigenschaftsdekoratoren

Dekorateur Datenbanktyp TypeScript-Typ
@uuid() UNIQUEIDENTIFIER string
@text() NVARCHAR string
@int() INT number
@decimal() DEZIMAL number
@bool() BIT boolean
@date() DATETIME2 Date

Berechtigungsdekoratoren

Dekorateur Purpose
@role() Definieren rollenbasierter Berechtigungen

Siehe Definieren von Datenberechtigungen für Autorisierungsdetails.

Functions

Erstellen Sie eine Instanz UserDataFunctions und registrieren Sie jede Funktion, indem Sie . aufrufen udf.func(name, handler, connections?).

Befolgen Sie diese Regeln, wenn Sie eine Funktion definieren:

  • Platziere den Parameter RayfinContext irgendwo in der Handler-Signatur. Die Laufzeit identifiziert es nach Typ, injiziert es und schließt es aus den generierten Funktionseingaben aus.
  • Deklarieren Sie für jedes delegierte Token, das die Funktion benötigt, eine Verbindung. Lass das Connections-Array für Funktionen weg, die nur auf App-Daten zugreifen oder keine delegierten Tokens benötigen.

Das folgende Beispiel registriert eine einfache Funktion und eine Funktion, die den Aufrufkontext verwendet:

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

Der RayfinContext stellt die Laufzeitdienste der Funktion bereit:

Mitglied Purpose
ctx.accessToken Stellt das Rayfin JSON Web Token (JWT) des angemeldeten Benutzers zur Verfügung. Dekodieren Sie den sub Claim, um eine stabile Benutzer-ID zu erhalten.
ctx.Tokens.<Audience> Erhält ein von der Plattform bereitgestelltes Ressourcentoken für ein in der RayfinContext Annotation deklariertes Publikum. Bereitgestellte Funktionen verwenden die App-Identität und deren Berechtigungen. Details finden Sie unter Funktionen mit externen Ressourcen verbinden.
ctx.getSecret('NAME') Bekommt ein Geheimnis für die aktuelle Beschwörung. Gibt undefined zurück, wenn das Geheimnis nicht gesetzt ist.
ctx.getDataClient() Ruft die API für typisierte Daten für Ihre Entitäten ab. Der Client unterstützt Erstellen, findMany, Aktualisieren, Löschen und Upsert-Operationen.
ctx.baseUrl Stellt den Rayfin-Endpunkt für das aktuelle Element bereit.
ctx.publishableKey Stellt den veröffentlichungsfähigen Schlüssel für das aktuelle Element bereit.

Für Einrichtung, lokales Debugging und Bereitstellungsanweisungen siehe Use Functions in Fabric Apps.

Entwicklungsworkflow

Ein typischer Entwicklungszyklus folgt diesem Muster:

  1. Definieren oder Ändern von Datenmodellen – Hinzufügen oder Aktualisieren von TypeScript-Klassen mit Dekoratoren
  2. Test lokal mit Remote-Back-End – Führen Sie npm run dev aus, um Ihre Frontend-Codeänderungen mit Ihrem App-Back-End in Fabric zu testen.
  3. Deploy to Fabric - Führen Sie npx rayfin up aus, um für den verwalteten Fabric-Dienst bereitzustellen und Ihre Schemaänderungen anzuwenden.

Änderungen an Ihren TypeScript-Modellen werden automatisch über den gesamten Stapel verteilt – von Datenbankschema zu API-Endpunkten bis hin zu Clienttypen.

Authorization

Berechtigungen werden zusammen mit Ihren Datenmodellen mithilfe des @role Dekorators definiert:

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

Dieser Ansatz stellt Folgendes sicher:

  • Sicherheitsregeln leben neben den daten, die sie schützen
  • Typensichere Richtlinienausdrücke erkennen Fehler bereits beim Kompilieren
  • Umgestalten von Entitätsfeldern aktualisiert automatisch Berechtigungsprüfungen

Verwandte Inhalte

  • Zuletzt aktualisiert um