Menghasilkan tipe TypeScript dari Schema
Intinya: json-schema-to-typescript dan quicktype menghasilkan .d.ts dalam satu perintah, tetapi itu masih draf: opsionalitas, union, additionalProperties dan tanggal perlu sentuhan manusia.
Intinya: hasilkan dengan json-schema-to-typescript atau quicktype, lalu perbaiki manual opsionalitas, union, additionalProperties dan tanggal; jaga Schema sebagai sumber dan tipe sebagai output, ditegakkan oleh langkah types:check di CI.
Satu perintah memberi Anda sebuah file. Itu tidak memberi Anda tipe yang benar.
One-liner
npx json-schema-to-typescript schema.json > src/types/order.d.ts
Ia menangani $ref, allOf, oneOf, anyOf, dan mengubah description menjadi JSDoc. Untuk pembuatan batch dengan banner dan style pilihan, panggil Node API-nya dari build-types.mjs kecil.
quicktype adalah alternatifnya, dan juga bisa menyimpulkan schema dari contoh JSON:
npx quicktype -s schema schema.json -o order.ts --lang typescript
Empat hal yang harus diperbaiki setelahnya
Opsionalitas. Apa pun yang tidak ada di required menjadi ?. Tetapi "selalu ada, boleh null" dan "mungkin tidak ada" adalah kontrak yang berbeda:
interface Order {
remark?: string | null; // may be missing
status: string;
}
Jika backend selalu mengirim remark: null, hapus ? dan berhenti membuat setiap konsumen menjaga terhadap undefined.
Union tanpa discriminator. oneOf biasanya menjadi A | B, yang tidak bisa dipersempit TypeScript tanpa field literal. Tambahkan properti type tetap di setiap cabang pada Schema.
additionalProperties. Dihilangkan atau true kadang menghasilkan [k: string]: unknown, kadang any. Yang pertama aman, yang kedua secara senyap menonaktifkan pemeriksaan tipe untuk seluruh objek.
Format tanggal. format: "date-time" adalah string di wire. Memetakannya ke Date berarti Anda juga harus melakukan deserialisasi, atau nilai runtime tetap string sementara tipenya berbohong.
Jaga arah tetap
Schema adalah sumber, tipe adalah output. Menghasilkan Schema dari tipe yang ditulis tangan hanya dapat diterima jika regenerasi wajib dan ditegakkan di CI — jika tidak, kedua sisi melenceng dan tidak ada yang tahu mana yang otoritatif.
Masukkan ke pipeline
"types:gen": "json2ts -i schemas/ -o src/types/generated",
"types:check": "pnpm types:gen && git diff --exit-code src/types/generated"
types:check adalah bagian yang penting: ubah Schema tanpa regenerasi dan CI gagal.
FAQ
Mengapa file hasil generate mengandung any?
Biasanya berasal dari additionalProperties yang bernilai true atau dihilangkan, yang dipetakan sebagian generator ke [k: string]: any. Ganti dengan unknown atau field eksplisit, karena any menonaktifkan pemeriksaan tipe untuk seluruh objek.
Bagaimana cara memperbaiki field opsional setelah generate?
Apa pun di luar required menjadi ?, tetapi "selalu ada, boleh null" berbeda dari "mungkin tidak ada". Jika backend selalu mengirim field itu, hapus ?.
Haruskah CI gagal ketika Schema dan tipe melenceng?
Ya. Skrip types:check yang meregenerasi lalu menjalankan git diff --exit-code menggagalkan build begitu Schema berubah tanpa regenerasi.