Menentukan model data untuk aplikasi Fabric

Fabric Apps menggunakan dekorator TypeScript untuk menentukan model data yang menghasilkan tabel database dan API. Anda menentukan setiap entitas sebagai kelas yang dihiasi dengan @entity(), tambahkan dekorator bidang untuk jenis data, dan memetakan hubungan antar entitas.

Untuk panduan otorisasi dan kontrol akses, lihat Menentukan izin data.

Prasyarat

  • Proyek Fabric Apps yang dibuat dengan npm create @microsoft/rayfin@latest atau diinisialisasi dengan npx rayfin init.
  • Pemahaman dasar tentang kelas dan dekorator TypeScript.

Menentukan entitas

Untuk membuat model data, tambahkan @entity() dekorator ke kelas TypeScript. Kemudian impor dekorator yang diperlukan dari @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;
}

Entitas ini menghasilkan Todo tabel dengan kolom untuk id, , title, descriptioncreatedAt, dan updatedAt.

Kunci primer

Setiap entitas menggunakan bidang UUID string bernama id sebagai kunci utamanya. Jika Anda tidak mendeklarasikan id secara eksplisit, Fabric Apps menambahkannya ke skema secara otomatis.

  • Bidang id bersifat opsional selama operasi pembuatan—server menghasilkan UUID jika Anda menghilangkannya.
  • Anda dapat menyediakan UUID Anda sendiri pada waktu pembuatan jika Anda lebih suka pengidentifikasi yang dihasilkan klien.
  • Kunci primer komposit dan nama kunci kustom tidak didukung.
@entity()
export class Note {
  @uuid() id!: string;  // UUID primary key, auto-generated when omitted
  @text() title!: string;
  @text() content!: string;
}

Jenis data yang didukung

Gunakan dekorator ini untuk menentukan jenis bidang:

Dekorator Tipe Deskripsi
@uuid() string Bidang pengidentifikasi unik.
@text() string Bidang teks dengan batasan panjang opsional.
@int() number Bidang bilangan bulat.
@decimal() number Bidang desimal atau numerik.
@boolean() Boolean Bidang benar atau salah.
@date() Date Bidang tanggal dan waktu, diserialisasi dari string ISO atau objek Date.
@email() string Bidang teks dengan validasi email.
@set() string Sekumpulan literal string yang dijumlahkan.

Contoh dengan beberapa jenis

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

Modifier tipe

Tambahkan pengubah ke dekorator bidang untuk mengonfigurasi validasi dan batasan:

Pengubah Deskripsi
{ optional: true } Perbolehkan nilai NULL. Kolom wajib diisi secara bawaan.
{ unique: true } Tambahkan batasan unik.
{ default: value } Atur ekspresi nilai default.
{ max: n }, { min: n } Batasan panjang string (jumlah karakter maksimum dan minimum).
{ min: n }, { max: n } Batasan nilai numerik.

Nota

Penanda opsional TypeScript (? setelah nama properti) hanya memengaruhi jenis TypeScript statis. Ini tidak menjadikan kolom basis data dapat bernilai null. Untuk membuat kolom dapat bernilai null, tambahkan { optional: true } ke dekorator. Gunakan ! untuk menegaskan bahwa bidang yang diperlukan diinisialisasi oleh kerangka kerja.

Contoh dengan pengubah

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

Menentukan hubungan

Gunakan @one() dan @many() dekorator untuk menentukan properti navigasi antar entitas. Fabric Apps secara otomatis menghasilkan kolom kunci asing saat Anda menentukan hubungan.

  • Satu-ke-banyak - Gunakan @many() pada induk dan @one() pada anak.
  • Banyak-ke-satu – Gunakan @one() pada anak untuk merujuk ke induk.
  • Relasi banyak-ke-banyak tidak didukung—gunakan entitas penghubung eksplisit sebagai gantinya.

Contoh dengan relasi satu-ke-banyak

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

Saat Anda menentukan @one(() => Notebook) pada entitas Note, aplikasi Fabric secara otomatis membuat kolom kunci asing notebook_id. Nyatakan bidang kunci asing secara eksplisit hanya jika Anda berencana untuk membaca atau mengaturnya dalam kode aplikasi.

Konvensi penamaan kunci asing

Saat Anda menentukan bidang kunci asing, gunakan {property}_id konvensi penamaan:

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

Nama kunci asing kustom (foreignKey, targetKey opsi) tidak didukung.

Entitas sistem referensi

Fabric Apps tidak mendukung hubungan @one() yang menunjuk ke entitas sistem seperti entitas USER bawaan. Untuk mengaitkan baris dengan pengguna yang sedang masuk, tambahkan field user_id biasa bertipe @text() dan isi nilainya dari klaim autentikasi (biasanya claims.sub):

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

Saring baris berdasarkan user_id dalam kebijakan peran Anda untuk menerapkan kontrol akses per pengguna.

Mendaftarkan entitas dalam skema

Tambahkan semua kelas entitas ke rayfin/data/schema.ts agar klien dapat menghasilkan proksi GraphQL:

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

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

Perbarui jenis ini setiap kali Anda membuat entitas baru.

Menerapkan perubahan skema

Setelah menentukan atau memodifikasi entitas, terapkan perubahan ke database:

  1. Sebarkan skema yang diperbarui ke Fabric:

    npx rayfin up db apply

  2. Jika perubahan skema mencakup operasi destruktif (menghilangkan kolom, mengganti nama tabel), CLI memperingatkan Anda dan menolak untuk melanjutkan. Gunakan --force untuk mengambil alih pemeriksaan keamanan:

    npx rayfin up db apply --force

Nota

Menggunakan --force dapat menyebabkan kehilangan data. Tinjau operasi yang tercantum dengan hati-hati sebelum melanjutkan.

Praktik terbaik

  • Tentukan bidang kunci asing hanya saat Anda perlu membaca atau mengaturnya dalam kode—Fabric Apps menghasilkannya secara otomatis dari dekorator navigasi.
  • Gunakan impor relatif dengan ekstensi .js pada file entitas agar JavaScript ESM yang dihasilkan dapat diurai dengan benar.
  • Untuk pola otorisasi dan akses berbasis peran, lihat Menentukan izin data.

Troubleshooting

Relasi yang hilang

Jika hubungan tidak muncul di API, verifikasi bahwa:

  • Dekorator navigasi (@one() atau @many()) ada.
  • Entitas terdaftar di rayfin/data/schema.ts.

Konten terkait

  • Last updated on