Menjana jenis TypeScript daripada Schema
Inti pati: json-schema-to-typescript dan quicktype menghasilkan .d.ts dengan satu arahan, tetapi ia ialah draf: pilihan, gabungan, additionalProperties dan tarikh memerlukan semakan manusia.
Pokoknya: jana dengan json-schema-to-typescript atau quicktype, kemudian betulkan secara manual pilihan, gabungan, additionalProperties dan tarikh; kekalkan Schema sebagai sumber dan jenis sebagai output, dikuatkuasakan oleh langkah types:check dalam CI.
Satu arahan memberi anda fail. Ia tidak memberi anda jenis yang betul.
Arahan satu baris
npx json-schema-to-typescript schema.json > src/types/order.d.ts
Ia mengendalikan $ref, allOf, oneOf, anyOf, dan menukar description menjadi JSDoc. Untuk penjanaan berkumpulan dengan sepanduk dan style pilihan, panggil Node API-nya daripada build-types.mjs yang kecil.
quicktype ialah alternatif, dan juga boleh menyimpulkan schema daripada contoh JSON:
npx quicktype -s schema schema.json -o order.ts --lang typescript
Empat perkara untuk dibetulkan selepas itu
Pilihan. Apa-apa yang tiada dalam required menjadi ?. Tetapi "sentiasa hadir, mungkin null" dan "mungkin tiada" ialah kontrak yang berbeza:
interface Order {
remark?: string | null; // mungkin tiada
status: string;
}
Jika backend sentiasa menghantar remark: null, buang ? dan hentikan pengguna daripada mengawal untuk undefined pada setiap penggunaan.
Gabungan tanpa pengecam. oneOf biasanya menjadi A | B, yang tidak dapat dipersempitkan oleh TypeScript tanpa medan literal. Tambah sifat type yang tetap pada setiap cabang dalam Schema.
additionalProperties. Ditinggalkan atau true kadangkala menghasilkan [k: string]: unknown, kadangkala any. Yang pertama selamat, yang kedua menyahdayakan semakan jenis untuk keseluruhan objek secara senyap.
Format tarikh. format: "date-time" ialah rentetan semasa pemindahan. Memetakannya kepada Date bermaksud anda juga mesti menyahserikan, atau nilai masa jalan kekal rentetan sementara jenis itu berbohong.
Kekalkan arah tetap
Schema ialah sumber, jenis ialah output. Menjana Schema daripada jenis tulisan tangan boleh diterima hanya jika penjanaan semula diwajibkan dan dikuatkuasakan dalam CI — jika tidak, kedua-dua belah menyimpang dan tiada siapa tahu yang mana berwibawa.
Letakkan dalam saluran paip
"types:gen": "json2ts -i schemas/ -o src/types/generated",
"types:check": "pnpm types:gen && git diff --exit-code src/types/generated"
types:check ialah bahagian yang penting: ubah Schema tanpa menjana semula dan CI gagal.
Soalan Lazim
Mengapa fail yang dijana mengandungi any?
Ia biasanya datang daripada additionalProperties yang true atau ditinggalkan, yang dipetakan oleh sesetengah penjana kepada [k: string]: any. Gantikannya dengan unknown atau medan eksplisit, kerana any menyahdayakan semakan jenis untuk keseluruhan objek.
Bagaimana saya harus membetulkan medan pilihan selepas penjanaan?
Apa-apa yang tiada dalam required menjadi ?, tetapi "sentiasa hadir, mungkin null" berbeza daripada "mungkin tiada". Jika backend sentiasa menghantar medan itu, buang ?.
Patutkah CI gagal apabila Schema dan jenis menyimpang?
Ya. Skrip types:check yang menjana semula dan menjalankan git diff --exit-code menggagalkan binaan sebaik sahaja Schema berubah tanpa penjanaan semula.