Generování typů TypeScript ze Schema

Stručně: generujte pomocí json-schema-to-typescript nebo quicktype, poté ručně opravte volitelnost, sjednocení, additionalProperties a data; držte Schema jako zdroj a typy jako výstup, vynucené krokem types:check v CI.

Jeden příkaz vám dá soubor. Nedá vám správné typy.

Jednořádkový příkaz

复制npx json-schema-to-typescript schema.json > src/types/order.d.ts

Zvládne $ref, allOf, oneOf, anyOf a převede description do JSDoc. Pro dávkové generování s bannerem a zvoleným style zavolejte jeho Node API z malého build-types.mjs.

quicktype je alternativa a umí také odvodit schéma ze vzorku JSON:

复制npx quicktype -s schema schema.json -o order.ts --lang typescript

Čtyři věci k následné opravě

Volitelnost. Cokoli není v required, se stane ?. Ale „vždy přítomné, může být null“ a „může chybět“ jsou odlišné smlouvy:

复制interface Order {
  remark?: string | null;   // může chybět
  status: string;
}

Pokud backend vždy posílá remark: null, odstraňte ? a přestaňte nutit každého konzumenta hlídat undefined.

Nerozlišená sjednocení. oneOf se obvykle stane A | B, což TypeScript bez literálního pole nedokáže zúžit. Přidejte do každé větve ve Schema pevnou vlastnost type.

additionalProperties. Vynechané nebo true někdy vydá [k: string]: unknown, někdy any. První je bezpečné, druhé tiše vypíná typovou kontrolu pro celý objekt.

Formáty dat. format: "date-time" je na drátě řetězec. Mapování na Date znamená, že musíte také deserializovat, jinak hodnota za běhu zůstane řetězec, zatímco typ lže.

Držte směr pevně

Schema je zdroj, typy jsou výstup. Generování Schema z ručně psaných typů je přijatelné jen tehdy, když je regenerace povinná a vynucená v CI – jinak obě strany driftují a nikdo neví, která je autoritativní.

Zařaďte to do pipeline

复制"types:gen": "json2ts -i schemas/ -o src/types/generated",
"types:check": "pnpm types:gen && git diff --exit-code src/types/generated"

types:check je ta podstatná část: změňte Schema bez regenerace a CI selže.

Časté dotazy

Proč vygenerený soubor obsahuje any?

Obvykle to pochází z additionalProperties nastaveného na true nebo vynechaného, což někteří generátoři mapují na [k: string]: any. Nahraďte to unknown nebo explicitními poli, protože any vypíná typovou kontrolu pro celý objekt.

Jak po generování opravit volitelná pole?

Cokoli mimo required se stane ?, ale „vždy přítomné, může být null“ se liší od „může chybět“. Pokud backend pole vždy posílá, odstraňte ?.

Má CI selhat, když se Schema a typy rozcházejí?

Ano. Skript types:check, který regeneruje a spustí git diff --exit-code, selže v sestavení ve chvíli, kdy se Schema změní bez regenerace.

Další čtení

• Udržování souladu Schema a typů TypeScript
• Proč vygenerovaná Schema odmítají skutečná data