Επισκόπηση μοντέλου προγραμματισμού

Το Rayfin SDK χρησιμοποιεί ένα μοντέλο προγραμματισμού που βασίζεται σε διακοσμητή, όπου ορίζετε το σχήμα δεδομένων σας μία φορά στο TypeScript και λαμβάνετε αυτόματα API έτοιμα για παραγωγή, πελάτες ασφαλείς για τύπο και υποδομή.

Βασικές έννοιες

Το Rayfin SDK συνδυάζει τρία βασικά στοιχεία:

• Σχήμα που βασίζεται σε διακοσμητή: Χρησιμοποιήστε διακοσμητές TypeScript για να ορίσετε μοντέλα δεδομένων, δικαιώματα και σχέσεις.
• Αυτόματη δημιουργία API: Οι διακοσμημένες τάξεις σας γίνονται τελικά σημεία GraphQL χωρίς να γράφετε κώδικα ελεγκτή.
• Υπολογιστές-πελάτες ασφαλείς τύπου: Οι πελάτες TypeScript που δημιουργούνται παρέχουν επικύρωση χρόνου μεταγλώττισης για ερωτήματα και μεταλλάξεις.

Πώς λειτουργεί

Όταν δημιουργείτε μια εφαρμογή Fabric, ο κώδικάς σας ρέει σε αυτά τα στάδια:

#	Στάδιο	Τι συμβαίνει
1	Προγραμματιστής	Συντάσσετε την εφαρμογή στο πρόγραμμα επεξεργασίας της επιλογής σας.
2	TypeScript	Μπορείτε να γράψετε κλάσεις οντοτήτων σε TypeScript.
3	Διακοσμητές	Σχολιάζετε τάξεις και πεδία με @entity, @uuid, @text, @role, και άλλους διακοσμητές.
4	Schema	Το CLI μεταγλωττίζει τις διακοσμημένες κλάσεις σε σχήμα βάσης δεδομένων, πολιτικές αδειών και διαμόρφωση API.
5	API	Το σχήμα δημοσιεύεται ως τελικά σημεία GraphQL.
6	Πρόγραμμα-πελάτης	Το παραγόμενο RayfinClient εκθέτει ένα πρόγραμμα-πελάτη δεδομένων και ελέγχου ταυτότητας με ασφάλεια τύπου σε αυτά τα τελικά σημεία.
7	Εφαρμογή	Η εφαρμογή frontend σας καταναλώνει τον πελάτη για ανάγνωση και εγγραφή δεδομένων.

1. Ορίστε μοντέλα δεδομένων με διακοσμητές

Ορίζετε τη δομή των δεδομένων σας χρησιμοποιώντας κλάσεις TypeScript και διακοσμητές από @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. Δημιουργία σχήματος

Το Rayfin CLI (npx rayfin) αναλύει τις διακοσμημένες τάξεις σας και δημιουργεί:

• Σχήμα βάσης δεδομένων - Πίνακες, στήλες, περιορισμοί και ευρετήρια
• Διαμόρφωση API - Ορισμοί τελικού σημείου GraphQL
• Πολιτικές δικαιωμάτων - Ασφάλεια σε επίπεδο γραμμών και έλεγχος πρόσβασης σε επίπεδο πεδίου

4. Ασφαλής χρήση υπολογιστή-πελάτη

Τα API GraphQL είναι διαθέσιμα για την εκτέλεση λειτουργιών CRUD στη βάση δεδομένων σας. Το Rayfin SDK παρέχει μια λειτουργία προγράμματος-πελάτη δεδομένων για ανάγνωση ή εγγραφή ή διαγραφή δεδομένων.

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

Αναφορά διακοσμητή

Το Rayfin SDK παρέχει διακοσμητές για κοινά μοτίβα μοντελοποίησης δεδομένων:

Διακοσμητές οντοτήτων

Διακοσμητής	Purpose	Παράδειγμα
@entity()	Σήμανση κλάσης ως οντότητας βάσης δεδομένων	@entity() class Product

Διακοσμητές ακινήτων

Διακοσμητής	Τύπος βάσης δεδομένων	Τύπος TypeScript
@uuid()	UNIQUEIDENTIFIER	string
@text()	NVARCHAR	string
@int()	ΙΝΤ	number
@decimal()	ΔΕΚΑΔΙΚΌΣ	number
@bool()	BIT	boolean
@date()	DATETIME2	Date

Διακοσμητές αδειών

Διακοσμητής	Purpose
@role()	Ορισμός δικαιωμάτων βάσει ρόλων

Δείτε την ενότητα Ορισμός δικαιωμάτων δεδομένων για λεπτομέρειες εξουσιοδότησης.

Συναρτήσεις

Δημιουργήστε ένα UserDataFunctions στιγμιότυπο και καταχωρήστε κάθε συνάρτηση καλώντας udf.func(name, handler, connections?).

Ακολουθήστε αυτούς τους κανόνες όταν ορίζετε μια συνάρτηση:

• Τοποθετήστε την RayfinContext παράμετρο οπουδήποτε στην υπογραφή του δείκτη χειρισμού. Ο χρόνος εκτέλεσης το προσδιορίζει ανά τύπο, το εισάγει και το αποκλείει από τις εισόδους της συνάρτησης που δημιουργούνται.
• Δηλώστε μια σύνδεση για κάθε διακριτικό που έχει ανατεθεί που χρειάζεται η συνάρτηση. Παραλείψτε τον πίνακα συνδέσεων για συναρτήσεις που έχουν πρόσβαση μόνο σε δεδομένα εφαρμογών ή δεν χρειάζονται εκχωρημένα διακριτικά.

Το παρακάτω παράδειγμα καταχωρεί μια απλή συνάρτηση και μια συνάρτηση που χρησιμοποιεί το περιβάλλον κλήσης:

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

Παρέχει RayfinContext τις υπηρεσίες χρόνου εκτέλεσης της συνάρτησης:

Μέλος	Purpose
ctx.accessToken	Παρέχει το Rayfin JSON Web Token (JWT) του συνδεδεμένου χρήστη. Αποκωδικοποιήστε την sub αξίωση για να λάβετε ένα σταθερό αναγνωριστικό χρήστη.
ctx.Tokens.<Audience>	Λαμβάνει ένα διακριτικό πόρου που παρέχεται από την πλατφόρμα για ένα κοινό που δηλώνεται στον RayfinContext σχολιασμό. Οι αναπτυγμένες λειτουργίες χρησιμοποιούν την ταυτότητα της εφαρμογής και τα δικαιώματά της. Για λεπτομέρειες, ανατρέξτε στην ενότητα Σύνδεση λειτουργιών με εξωτερικούς πόρους.
ctx.getSecret('NAME')	Παίρνει ένα μυστικό για την τρέχουσα επίκληση. Επιστρέφει undefined όταν δεν έχει οριστεί το μυστικό.
ctx.getDataClient()	Λαμβάνει το API πληκτρολογημένων δεδομένων για τις οντότητές σας. Ο υπολογιστής-πελάτης υποστηρίζει λειτουργίες δημιουργίας, findManyενημέρωσης, διαγραφής και αναβάθμισης.
ctx.baseUrl	Παρέχει το τελικό σημείο Rayfin για το τρέχον στοιχείο.
ctx.publishableKey	Παρέχει το κλειδί με δυνατότητα δημοσίευσης για το τρέχον στοιχείο.

Για οδηγίες εγκατάστασης, τοπικού εντοπισμού σφαλμάτων και ανάπτυξης, ανατρέξτε στο θέμα Χρήση συναρτήσεων σε εφαρμογές Fabric.

Ροή εργασιών ανάπτυξης

Ένας τυπικός κύκλος ανάπτυξης ακολουθεί αυτό το μοτίβο:

1. Ορισμός ή τροποποίηση μοντέλων δεδομένων - Προσθήκη ή ενημέρωση κλάσεων TypeScript με διακοσμητές
2. Δοκιμή τοπικά με απομακρυσμένο backend - Εκτελέστε το npm run dev για να δοκιμάσετε τις αλλαγές στον κώδικα του frontend σε σχέση με το backend της εφαρμογής σας στο Fabric.
3. Ανάπτυξη σε Fabric - Εκτελέστε npx rayfin up για ανάπτυξη στη διαχειριζόμενη υπηρεσία Fabric και εφαρμόστε τις αλλαγές σχήματος.

Οι αλλαγές στα μοντέλα TypeScript διαδίδονται αυτόματα σε ολόκληρη τη στοίβα — από το σχήμα βάσης δεδομένων έως τα τελικά σημεία API έως τους τύπους πελατών.

Authorization

Τα δικαιώματα ορίζονται παράλληλα με τα μοντέλα δεδομένων σας χρησιμοποιώντας τον @role διακοσμητή:

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

Η προσέγγιση αυτή διασφαλίζει:

• Οι κανόνες ασφαλείας ισχύουν δίπλα στα δεδομένα που προστατεύουν
• Οι εκφράσεις πολιτικής ασφαλούς τύπου εντοπίζουν σφάλματα κατά τη μεταγλώττιση
• Τα πεδία οντότητας ανακατασκευής ενημερώνουν αυτόματα τους ελέγχους δικαιωμάτων

Σχετικό περιεχόμενο

• Επισκόπηση μοντέλων δεδομένων
• Ορισμός δικαιωμάτων δεδομένων
• Αναζήτηση δεδομένων με το GraphQL
• Χρήση συναρτήσεων σε εφαρμογές Fabric
• Διαχείριση μυστικών λειτουργιών