Ορισμός μοντέλων δεδομένων για εφαρμογές Fabric

Το Fabric Apps χρησιμοποιεί διακοσμητές TypeScript για να ορίσει μοντέλα δεδομένων που δημιουργούν πίνακες βάσης δεδομένων και API. Ορίζετε κάθε οντότητα ως κλάση διακοσμημένη με @entity(), προσθέτετε διακοσμητές πεδίων για τύπους δεδομένων και αντιστοιχίζετε σχέσεις μεταξύ οντοτήτων.

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

Προϋποθέσεις

  • Ένα έργο Fabric Apps που δημιουργήθηκε με npm create @microsoft/rayfin@latest ή αρχικοποιήθηκε με npx rayfin init.
  • Βασική κατανόηση κλάσεων και διακοσμητών TypeScript.

Ορισμός οντότητας

Για να δημιουργήσετε ένα μοντέλο δεδομένων, προσθέστε τον @entity() διακοσμητή σε μια κλάση TypeScript. Στη συνέχεια, εισάγετε τους απαιτούμενους διακοσμητές από @microsoft/rayfin-core:

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

@entity()
export class Todo {
  @uuid() id!: string;
  @text() title!: string;
  @text({ optional: true }) description?: string;
  @date() createdAt!: Date;
  @date() updatedAt!: Date;
}

Αυτή η οντότητα δημιουργεί έναν Todo πίνακα με στήλες για id, title, description, createdAtκαι updatedAt.

Πρωτεύοντα κλειδιά

Κάθε οντότητα χρησιμοποιεί ένα πεδίο UUID string που ονομάζεται id πρωτεύον κλειδί της. Εάν δεν δηλώσετε ρητά το id, το Fabric Apps το προσθέτει αυτόματα στο σχήμα.

  • Το id πεδίο είναι προαιρετικό κατά τη διάρκεια των λειτουργιών δημιουργίας—ο διακομιστής δημιουργεί ένα UUID εάν το παραλείψετε.
  • Μπορείτε να παρέχετε το δικό σας UUID κατά τη δημιουργία, εάν προτιμάτε αναγνωριστικά που δημιουργούνται από τον πελάτη.
  • Τα σύνθετα πρωτεύοντα κλειδιά και τα προσαρμοσμένα ονόματα κλειδιών δεν υποστηρίζονται.
@entity()
export class Note {
  @uuid() id!: string;  // UUID primary key, auto-generated when omitted
  @text() title!: string;
  @text() content!: string;
}

Υποστηριζόμενοι τύποι δεδομένων

Χρησιμοποιήστε αυτούς τους διακοσμητές για να ορίσετε τύπους πεδίων:

Διακοσμητής Δακτυλογραφώ Περιγραφή
@uuid() string Πεδίο μοναδικού αναγνωριστικού κωδικού.
@text() string Πεδίο κειμένου με προαιρετικούς περιορισμούς μήκους.
@int() Αριθμός Ακέραιο πεδίο.
@decimal() Αριθμός Δεκαδικό ή αριθμητικό πεδίο.
@boolean() δυαδική τιμή Σωστό ή ψευδές πεδίο.
@date() Ημερομηνία Πεδίο ημερομηνίας και ώρας, σειριοποιεί από συμβολοσειρές ή Date αντικείμενα ISO.
@email() string Πεδίο κειμένου με επικύρωση email.
@set() string Απαριθμημένο σύνολο σταθερών συμβολοσειρών.

Παράδειγμα με πολλούς τύπους

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

@entity()
export class Product {
  @uuid() id!: string;
  @text() name!: string;
  @decimal() price!: number;
  @int() stockQuantity!: number;
  @boolean() isAvailable!: boolean;
  @date() createdAt!: Date;
  @set('draft', 'published', 'archived') status!: 'draft' | 'published' | 'archived';
}

Τροποποιητές κειμένου

Προσθέστε τροποποιητές σε διακοσμητές πεδίων για να διαμορφώσετε την επικύρωση και τους περιορισμούς:

Τροποποιητής Περιγραφή
{ optional: true } Να επιτρέπονται τιμές NULL. Τα πεδία είναι υποχρεωτικά από προεπιλογή.
{ unique: true } Προσθέστε έναν μοναδικό περιορισμό.
{ default: value } Ορίστε μια παράσταση προεπιλεγμένης τιμής.
{ max: n }, { min: n } Περιορισμοί μήκους συμβολοσειράς (μέγιστος και ελάχιστος αριθμός χαρακτήρων).
{ min: n }, { max: n } Περιορισμοί αριθμητικών τιμών.

Σημείωση

Ο προαιρετικός δείκτης TypeScript (? μετά από ένα όνομα ιδιότητας) επηρεάζει μόνο τον στατικό τύπο TypeScript. Δεν καθιστά τη στήλη της βάσης δεδομένων nullable. Για να κάνετε ένα πεδίο nullable, προσθέστε { optional: true } στον διακοσμητή. Χρησιμοποιήστε το ! για να επιβεβαιώσετε ότι ένα απαιτούμενο πεδίο προετοιμάζεται από το πλαίσιο.

Παράδειγμα με τροποποιητές

@entity()
export class User {
  @uuid() id!: string;
  @email({ unique: true }) email!: string;
  @text({ min: 3, max: 50 }) username!: string;
  @text({ optional: true, max: 500 }) bio?: string;
  @int({ min: 0, max: 150 }) age!: number;
  @boolean({ default: false }) isVerified!: boolean;
}

Ορισμός σχέσεων

Χρησιμοποιήστε @one() και @many() διακοσμητές για να ορίσετε ιδιότητες περιήγησης μεταξύ οντοτήτων. Το Fabric Apps δημιουργεί αυτόματα στήλες ξένων κλειδιών όταν ορίζετε σχέσεις.

  • Ένα προς πολλά – Χρήση @many() στον γονέα και @one() στο παιδί.
  • Πολλά προς ένα – Χρησιμοποιήστε @one() το στο παιδί για να αναφέρετε τον γονέα.
  • Οι σχέσεις πολλά-προς-πολλά δεν υποστηρίζονται—χρησιμοποιήστε μια ρητή οντότητα συμμετοχής.

Παράδειγμα με σχέση ένα-προς-πολλά

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

@entity()
export class Notebook {
  @uuid() id!: string;
  @text() name!: string;
  @date() createdAt!: Date;
  @many(() => Note) notes?: Note[];
}

@entity()
export class Note {
  @uuid() id!: string;
  @text() title!: string;
  @text() content!: string;
  @date() createdAt!: Date;
  @text() notebook_id!: string;
  @one(() => Notebook) notebook?: Notebook;
}

Όταν ορίζετε @one(() => Notebook) στην οντότητα Note, το Fabric Apps δημιουργεί αυτόματα μια στήλη εξωτερικού κλειδιού notebook_id. Δηλώστε ρητά το πεδίο εξωτερικού κλειδιού μόνο εάν σκοπεύετε να το διαβάσετε ή να το ορίσετε στον κώδικα εφαρμογής.

Σύμβαση ονομασίας ξένων κλειδιών

Όταν ορίζετε ένα πεδίο εξωτερικού κλειδιού, χρησιμοποιήστε τη {property}_id σύμβαση ονομασίας:

@entity()
export class Note {
  @uuid() id!: string;
  @text() notebook_id!: string;      // Foreign key field
  @one(() => Notebook) notebook?: Notebook;  // Navigation property
}

Τα προσαρμοσμένα ονόματα ξένων κλειδιών (foreignKey, targetKey επιλογές) δεν υποστηρίζονται.

Οντότητες συστημάτων αναφοράς

Το Fabric Apps δεν υποστηρίζει σχέσεις @one() που παραπέμπουν σε οντότητες συστήματος, όπως η ενσωματωμένη οντότητα USER. Για να συσχετίσετε μια γραμμή με τον συνδεδεμένο χρήστη, προσθέστε ένα απλό user_id πεδίο τύπου @text() και συμπληρώστε το από τους ισχυρισμούς ελέγχου ταυτότητας (συνήθως claims.sub):

@entity()
export class Task {
  @uuid() id!: string;
  @text() title!: string;
  @text() user_id!: string;  // System user ID from claims.sub
}

Φιλτράρετε τις γραμμές με βάση user_id τις πολιτικές ρόλων σας για να επιβάλετε πρόσβαση ανά χρήστη.

Καταχωρήστε οντότητες στο σχήμα

Προσθέστε όλες τις κλάσεις οντοτήτων, ώστε ο πελάτης να μπορεί να rayfin/data/schema.ts δημιουργήσει διακομιστές μεσολάβησης GraphQL:

import type { Note } from './Note.js';
import type { Notebook } from './Notebook.js';

export type NotesAppSchema = {
  Note: Note;
  Notebook: Notebook;
};

Ενημερώστε αυτόν τον τύπο κάθε φορά που δημιουργείτε μια νέα οντότητα.

Εφαρμογή αλλαγών σχήματος

Αφού ορίσετε ή τροποποιήσετε οντότητες, εφαρμόστε τις αλλαγές στη βάση δεδομένων:

  1. Αναπτύξτε το ενημερωμένο σχήμα στο Fabric:

    npx rayfin up db apply

  2. Εάν η αλλαγή σχήματος περιλαμβάνει καταστροφικές λειτουργίες (απόθεση στηλών, μετονομασία πινάκων), το CLI σας προειδοποιεί και αρνείται να προχωρήσει. Χρησιμοποιήστε το --force για να παρακάμψετε τον έλεγχο ασφαλείας:

    npx rayfin up db apply --force

Σημείωση

Η χρήση --force μπορεί να προκαλέσει απώλεια δεδομένων. Ελέγξτε προσεκτικά τις αναφερόμενες λειτουργίες πριν συνεχίσετε.

Βέλτιστες πρακτικές

  • Ορίστε πεδία εξωτερικού κλειδιού μόνο όταν χρειάζεται να τα διαβάσετε ή να τα ορίσετε σε κώδικα—Το Fabric Apps τα δημιουργεί αυτόματα από διακοσμητές περιήγησης.
  • Χρησιμοποιήστε σχετικές εισαγωγές με .js επεκτάσεις σε αρχεία οντότητας, ώστε η εκπεμπόμενη JavaScript του ESM να επιλύεται σωστά.
  • Για μοτίβα εξουσιοδότησης και πρόσβαση βάσει ρόλων, ανατρέξτε στην ενότητα Ορισμός δικαιωμάτων δεδομένων.

Αντιμετώπιση προβλημάτων

Σχέσεις που λείπουν

Εάν οι σχέσεις δεν εμφανίζονται στο API, επαληθεύστε ότι:

  • Ο διακοσμητής πλοήγησης (@one() ή @many()) είναι παρών.
  • Η οντότητα είναι εγγεγραμμένη στο rayfin/data/schema.ts.

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

  • Last updated on