Gambaran umum model pemrograman

Rayfin SDK menggunakan model pemrograman berbasis dekorator di mana Anda cukup satu kali menentukan skema data di TypeScript dan secara otomatis mendapatkan API siap produksi, klien yang aman secara tipe, serta infrastruktur.

Konsep Utama

Rayfin SDK menggabungkan tiga elemen inti:

  • Skema berbasis dekorator: Gunakan dekorator TypeScript untuk menentukan model data, izin, dan hubungan.
  • Pembuatan API otomatis: Kelas yang didekorasi menjadi titik akhir GraphQL tanpa menulis kode pengontrol.
  • Klien yang aman terhadap tipe: Klien TypeScript yang dihasilkan menyediakan validasi pada waktu kompilasi untuk kueri dan mutasi.

Cara kerjanya

Saat Anda membuat aplikasi Fabric, kode Anda mengalir melalui tahap ini:

# Stage Apa yang terjadi
1 Pengembang Anda menulis aplikasi di editor pilihan Anda.
2 TypeScript Anda menulis kelas entitas di TypeScript.
3 Decorators Anda membuat anotasi kelas dan kolom dengan @entity, @uuid, @text, @role, dan dekorator lainnya.
4 Schema CLI mengkompilasi kelas yang didekorasi ke dalam skema database, kebijakan izin, dan konfigurasi API.
5 Antarmuka Pemrograman Aplikasi (API) Skema diterbitkan sebagai titik akhir GraphQL.
6 Client RayfinClient yang dihasilkan menyediakan klien data dan autentikasi yang aman secara tipe melalui endpoint tersebut.
7 Application Aplikasi frontend Anda menggunakan klien untuk membaca dan menulis data.

1. Definisikan model data dengan dekorator

Anda menentukan struktur data anda menggunakan kelas TypeScript dan dekorator dari @microsoft/rayfin-core:

scaffold default blankapp mengarah ke ruang kerja Universal App. Aktifkan Data dengan npm run pack:add -- data-modeling, definisikan entitas di packages/data/src/, daftarkan kelas runtime di packages/data/src/index.ts, dan pertahankan kontrak yang berhadapan langsung dengan klien di packages/shared/src/index.ts. Template flat dapat menggunakan rayfin/data/ dan rayfin/data/schema.ts sebagai gantinya. Path layanan dalam rayfin/rayfin.yml menentukan tata letak mana yang dibangun oleh CLI.

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. Pembuatan skema

Rayfin CLI (npx rayfin) menganalisis kelas yang Anda dekorasi dan menghasilkan:

  • Skema database - Tabel, kolom, batasan, dan indeks
  • Konfigurasi API - Definisi titik akhir GraphQL
  • Kebijakan izin - Keamanan tingkat baris dan kontrol akses tingkat bidang

3. Penggunaan klien yang aman secara tipe

API GraphQL tersedia untuk melakukan operasi CRUD pada database Anda. Rayfin SDK menyediakan operasi klien data di luar kotak untuk membaca atau menulis atau menghapus data.

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

Referensi dekorator

Rayfin SDK menyediakan dekorator untuk pola pemodelan data umum:

Dekorator Entitas

Dekorator Kegunaan Example
@entity() Menandai kelas sebagai entitas database @entity() class Product

Dekorator properti

Dekorator Jenis database Jenis TypeScript
@uuid() UNIQUEIDENTIFIER string
@text({ max: n }) NVARCHAR(n) string
@int() INT number
@decimal() DECIMAL number
@bool() BIT boolean
@date() DATETIME2 Date

Dekorator izin

Dekorator Kegunaan
@role() Menentukan izin berbasis peran

Lihat Menentukan izin data untuk detail otorisasi.

Functions

Buat satu UserDataFunctions instance, dan daftarkan setiap fungsi dengan memanggil udf.func(name, handler, connections?).

Ikuti aturan berikut saat Anda mendefinisikan sebuah fungsi:

  • Tempatkan parameter RayfinContext di mana saja dalam signature handler. Runtime mengidentifikasinya berdasarkan tipe, menyuntikkannya, dan mengecualikannya dari input fungsi yang dihasilkan.
  • Deklarasikan audiens resource eksternal di RayfinContext<Schema, Audiences> dan gunakan token resource milik identitas aplikasi melalui ctx.Tokens. Teruskan [] sebagai argumen ketiga saat mendeklarasikan audiens tersebut dengan udf.func(). Lihat Hubungkan Fungsi ke sumber daya eksternal.

Contoh berikut mendaftarkan fungsi biasa dan fungsi yang menggunakan konteks pemanggilan:

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

RayfinContext menyediakan layanan runtime fungsi:

Anggota Kegunaan
ctx.accessToken Menyediakan Rayfin JSON Web Token (JWT) milik pengguna yang masuk. Pecahkan sub klaim untuk mendapatkan ID pengguna yang stabil.
ctx.Tokens.<Audience> Mendapatkan token sumber daya yang disediakan platform untuk audiens yang dideklarasikan dalam anotasi RayfinContext. Fungsi yang Terdeploy menggunakan identitas aplikasi dan izinnya. Untuk detail, lihat Hubungkan Fungsi ke sumber daya eksternal.
ctx.getSecret('NAME') Mendapatkan rahasia untuk invokasi saat ini. Mengembalikan undefined jika rahasia tidak ditetapkan.
ctx.getDataClient() Mendapatkan API data yang diketik untuk entitas Anda. Klien mendukung operasi buat, findMany, perbarui, hapus, dan upsert.
ctx.baseUrl Menyediakan endpoint Rayfin untuk item saat ini.
ctx.publishableKey Menyediakan kunci yang dapat dipublikasikan untuk item saat ini.

Untuk petunjuk tentang penyiapan, debugging secara lokal, dan penyebaran, lihat Menggunakan Fungsi di Fabric Apps.

Alur kerja pengembangan

Siklus pengembangan yang khas mengikuti pola ini:

  1. Menentukan atau memodifikasi model data - Menambahkan atau memperbarui kelas TypeScript dengan dekorator
  2. Test secara lokal dengan backend jarak jauh - Jalankan npm run dev untuk menguji perubahan kode frontend Anda terhadap backend Aplikasi Anda di Fabric.
  3. Deploy ke Fabric - Jalankan npx rayfin up untuk melakukan deployment ke layanan Fabric yang dikelola dan menerapkan perubahan skema Anda.

Perubahan pada model TypeScript Anda secara otomatis disebarluaskan melalui seluruh tumpukan — dari skema database ke titik akhir API ke jenis klien.

Authorization

Izin didefinisikan bersama model data Anda menggunakan dekorator @role:

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

Pendekatan ini memastikan:

  • Aturan keamanan berada di samping data yang mereka lindungi
  • Ekspresi kebijakan yang aman terhadap tipe mendeteksi kesalahan saat kompilasi
  • Pemfaktoran ulang kolom entitas secara otomatis memperbarui pemeriksaan hak akses

Konten terkait

  • Terakhir diperbarui pada