Ohjelmointimallin yleiskatsaus

Rayfin SDK käyttää sisustajavetoista ohjelmointimallia, jossa määrittelet dataskeeman kerran TypeScriptissä ja saat automaattisesti tuotantovalmiit rajapinnat, tyyppiturvalliset asiakkaat ja infrastruktuurin.

Avainkäsitteet

Rayfin SDK yhdistää kolme ydinelementtiä:

  • Sisustajapohjainen skeema: Käytä TypeScript-koristelijoita määrittelemään tietomalleja, käyttöoikeuksia ja suhteita.
  • Automaattinen API:n generointi: Koristellut luokkasi muuttuvat GraphQL-päätepisteiksi ilman ohjauskoodin kirjoittamista.
  • Tyyppiturvalliset asiakkaat: Generoidut TypeScript-asiakkaat tarjoavat käännösaikaisen validoinnin kyselyille ja mutaatioille.

Näin se toimii

Kun luot Fabric-sovelluksen, koodisi kulkee näiden vaiheiden läpi:

# Näyttämö Mitä tapahtuu
1 Kehittäjä Kirjoitat sovelluksen valitsemassasi editorissa.
2 TypeScript Kirjoitat entiteettiluokkia TypeScriptissä.
3 Koristus Merkitset luokat ja kentät , @entity@uuid@text@roleja muilla sisustajilla.
4 Schema Komentojärjestelmä kääntää koristellut luokat tietokantaskeemaan, käyttöoikeuskäytäntöihin ja API-konfiguraatioon.
5 Ohjelmointirajapinnat Skeema julkaistaan GraphQL-päätepisteinä.
6 Asiakas Luotu RayfinClient avaa tyyppiturvallisen datan ja autentiusasiakkaan näiden päätepisteiden yli.
7 Sovellus Frontend-sovelluksesi käyttää asiakasta datan lukemiseen ja kirjoittamiseen.

1. Määrittele tietomalleja sisustajien avulla

Määrittelet tietorakenteesi TypeScript-luokkien ja koristelijoiden avulla:@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. Skeeman generointi

Rayfin CLI (npx rayfin) analysoi palkitut luokkasi ja luo:

  • Tietokantaskeema – Taulukot, sarakkeet, rajoitteet ja indeksit
  • API-konfiguraatio - GraphQL-päätepisteiden määritelmät
  • Käyttöoikeuskäytännöt - Rivitason turvallisuus ja kenttätason käyttöoikeuksien hallinta

4. Tyyppiturvallinen asiakaskäyttö

GraphQL-rajapinnat ovat saatavilla CRUD-toimintojen suorittamiseen tietokannassasi. Rayfin SDK tarjoaa dataasiakastoiminnon suoraan datan lukemiseen, kirjoittamiseen tai poistamiseen.

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

Sisustusviite

Rayfin SDK tarjoaa koristelijoita yleisille datamallinnusmalleille:

Sisustajat

Sisustaja Käyttötarkoitus Esimerkki
@entity() Merkitse luokka tietokanta-entiteetiksi @entity() class Product

Kiinteistön sisustajat

Sisustaja Tietokantatyyppi TypeScript-tyyppi
@uuid() YKSILÖLLINEN TUNNUS string
@text() NVARCHAR string
@int() INT number
@decimal() DESIMAALI number
@bool() BITTI boolean
@date() DATETIME2 Date

Luvan sisustajat

Sisustaja Käyttötarkoitus
@role() Määrittele roolipohjaiset oikeudet

Katso Määrittele tietojen käyttöoikeudet valtuutustietojen yksityiskohtia varten.

Funktiot

Luo yksi UserDataFunctions instanssi ja rekisteröi jokainen funktio kutsumalla udf.func(name, handler, connections?).

Noudata näitä sääntöjä määritellessäsi funktiota:

  • Aseta RayfinContext parametri mihin tahansa käsittelijän allekirjoitukseen. Ajonaika tunnistaa sen tyypin mukaan, injektoi sen ja sulkee sen pois generoiduista funktioiden syötteistä.
  • Ilmoita yhteys jokaiselle delegoidulle tokenille, jota funktio tarvitsee. Jätä connections array pois funktioille, jotka käyttävät vain sovellusdataa tai eivät tarvitse delegoituja tokeneita.

Seuraava esimerkki rekisteröi yksinkertaisen funktion ja funktion, joka käyttää kutsukontekstia:

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

Se RayfinContext tarjoaa funktion ajonaikaiset palvelut:

Jäsen Käyttötarkoitus
ctx.accessToken Tarjoaa kirjautuneelle käyttäjälle Rayfin JSON Web Token (JWT). Purkaa sub vaatimus saadaksesi vakaan käyttäjätunnuksen.
ctx.Tokens.<Audience> Saa alustan tarjoaman resurssitokenin annotaatiossa ilmoitetulle yleisölle RayfinContext . Käyttöönotetut funktiot käyttävät sovelluksen identiteettiä ja sen käyttöoikeuksia. Lisätietoja löytyy kohdasta Yhdistä funktiot ulkoisiin resursseihin.
ctx.getSecret('NAME') Saa salaisuuden nykyiselle kutsulle. Palaa undefined , kun salaisuus ei ole selvillä.
ctx.getDataClient() Saa tyypitetyn datan API:n yksiköillesi. Asiakasohjelma tukee luomis-, findManypäivitys-, poisto- ja lisätoimintoja.
ctx.baseUrl Tarjoaa Rayfin-päätepisteen nykyiselle tuotteelle.
ctx.publishableKey Tarjoaa julkaistavan avaimen nykyiselle tuotteelle.

Asennuksen, paikallisen virheenkorjauksen ja käyttöönotto-ohjeiden osalta Katso Use Functions in Fabric Apps.

Kehitystyönkulku

Tyypillinen kehityssykli noudattaa tätä kaavaa:

  1. Määrittele tai muokkaa tietomalleja - Lisää tai päivitä TypeScript-luokkia koristelujen avulla
  2. testaa paikallisesti etäbackendillä - Suorita npm run dev testataksesi frontend-koodin muutoksia sovelluksen taustalla Fabric.
  3. Deploy to Fabric - Suorita npx rayfin up käyttöönoton hallitulla Fabric-palvelulla ja skeemamuutokset toteutetaan.

Muutokset TypeScript-malleihisi etenevät automaattisesti koko pinossa — tietokantaskeemasta API-päätepisteisiin ja asiakastyyppeihin.

Authorization

Käyttöoikeudet määritellään yhdessä tietomalliesi kanssa koristelijan @role avulla:

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

Tämä lähestymistapa takaa:

  • Turvallisuussäännöt elävät niiden suojaamien tietojen rinnalla
  • Tyypin turvalliset politiikkalausekkeet havaitsevat virheitä käännösvaiheessa
  • Entiteettikenttien refaktorointi päivittää automaattisesti käyttöoikeustarkistukset

Liittyvä sisältö

  • Viimeksi päivitetty