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

Oletusrunko blankapp ratkeaa Universal App -työtilaan. Ota data käyttöön , npm run pack:add -- data-modelingmäärittele entiteetit , packages/data/src/rekisteröi ajonaikaiset luokat , packages/data/src/index.tsja ylläpidä asiakaskohtaisia sopimuksia .packages/shared/src/index.ts Litteät mallipohjat voivat käyttää rayfin/data/ ja rayfin/data/schema.ts sen sijaan. Palvelureitit rayfin/rayfin.yml määrittävät, minkä pohjaratkaisun CLI rakentaa.

import { entity, uuid, text, int } from '@microsoft/rayfin-core';

@entity()
export class Product {
  @uuid() id!: string;
  @text({ max: 200 }) name!: string;
  @text({ optional: true, max: 2000 }) 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

3. 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';
import type { UniversalAppSchema } from '@rayfin-app/shared';

const client = new RayfinClient<UniversalAppSchema>({
  baseUrl: import.meta.env.VITE_RAYFIN_API_URL,
  publishableKey: import.meta.env.VITE_RAYFIN_PUBLISHABLE_KEY,
});

// Register Product in the data package and shared schema first.
const products = await client.data.Product
  .select(['id', 'name', 'price'])
  .execute();

// Compile-time error if field doesn't exist
const invalid = await client.data.Product
  .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({ max: n }) NVARCHAR(n) 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 ulkoiset resurssiyleisöt ja RayfinContext<Schema, Audiences> käytä sovelluksen identiteetin resurssitokeneita .ctx.Tokens Se on [] kolmas argumentti, udf.func() kun julistat nämä yleisöt. Katso Yhdistä funktiot ulkoisiin resursseihin.

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

import {
  UserDataFunctions,
  type RayfinContext,
} from '@microsoft/fabric-user-data-functions';

import type { UniversalAppSchema } from '@rayfin-app/shared';

const udf = new UserDataFunctions();

udf.func('greet', async (name: string): Promise<string> => {
  return `Hello, ${name}!`;
});

udf.func(
  'whoAmI',
  async (ctx: RayfinContext<UniversalAppSchema>): 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({ max: 255 }) userId!: string;
  @text({ max: 4000 }) 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