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

Template default blankapp membuat ruang kerja Universal App dengan Data dinonaktifkan. Aktifkan ini dengan kemampuan pemodelan data milik template:

npm run pack:add -- data-modeling

Langkah ini menambahkan starter entity dan shared contract. Masukkan kelas entitas ke packages/data/src/, daftarkan mereka di packages/data/src/index.ts, dan pertahankan kontrak yang berhadapan langsung dengan klien di packages/shared/src/index.ts. Layanan data menggunakan services.data.path: packages/data dalam rayfin/rayfin.yml. Saat Anda mengonfigurasi Data secara manual untuk Fabric, juga atur enabled: true dan dialect: mssql.

Template datar sebaliknya dapat menyimpan entitas di dalam rayfin/data/ dan menggunakan rayfin/data/schema.ts. Ikuti jalur layanan yang telah dikonfigurasi daripada membuat folder data kedua. Lihat struktur proyek.

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({ max: 200 }) title!: string;
  @text({ optional: true, max: 2000 }) description?: string;
  @date() createdAt!: Date;
  @date() updatedAt!: Date;
}

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

Important

Berikan kolom teks yang disimpan panjang maksimum yang ditentukan secara eksplisit sesuai dengan data Anda. Di Microsoft SQL Server, teks tanpa max menghasilkan NVARCHAR(MAX), yang dapat mencegah pembuatan metadata GraphQL. Contoh-contoh tersebut menggunakan teks berpembatas, termasuk string owner dan foreign key. Lihat Pemecahan masalah model data.

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({ max: 200 }) title!: string;
  @text({ max: 4000 }) content!: string;
}

Jenis data yang didukung

Gunakan dekorator ini untuk menentukan jenis bidang:

Dekorator Tipe Deskripsi
@uuid() string Bidang pengidentifikasi unik.
@text({ max: n }) string Bidang teks dengan panjang maksimum eksplisit untuk kolom MSSQL yang dipertahankan.
@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({ max: 200 }) 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, max: 254 }) 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({ max: 200 }) name!: string;
  @date() createdAt!: Date;
  @many(() => Note) notes?: Note[];
}

@entity()
export class Note {
  @uuid() id!: string;
  @text({ max: 200 }) title!: string;
  @text({ max: 4000 }) content!: string;
  @date() createdAt!: Date;
  @text({ max: 36 }) 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({ max: 36 }) 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 masuk, tambahkan bidang teks terbatas user_id dan isi dari klaim autentikasi (biasanya claims.sub):

@entity()
export class Task {
  @uuid() id!: string;
  @text({ max: 200 }) title!: string;
  @text({ max: 255 }) 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

Di ruang kerja Universal App, daftarkan kelas entitas runtime di packages/data/src/index.ts:

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

export const schema = [Note, Notebook];

Jaga antarmuka record yang sesuai dan map UniversalAppSchema di packages/shared/src/index.ts agar selaras dengan entitas tersebut. Frontend mengimpor UniversalAppSchema dari @rayfin-app/shared; tidak mengimpor kelas runtime yang didekorasi. Tambahkan Product ke kedua registrasi jika Anda menggunakan contoh agregasi numerik di Read and write data.

Untuk alternatif template datar, petakan jenis entitas di rayfin/data/schema.ts:

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

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

Perbarui registrasi dan tipe skema untuk tata letak yang Anda pilih setiap kali Anda membuat entitas baru.

Menerapkan perubahan skema

Setelah mendefinisikan atau memodifikasi entitas, terapkan perubahan tersebut ke database. Untuk alur kerja lengkap penerapan dan verifikasi, lihat Terapkan dan verifikasi perubahan skema.

  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 tersebut terdaftar dalam paket data yang dikonfigurasi dan skema bersama Anda, atau di rayfin/data/schema.ts untuk template datar.

Konten terkait

  • Terakhir diperbarui pada