تولید نوع‌های TypeScript از یک Schema

جمع‌بندی: با json-schema-to-typescript یا quicktype تولید کنید، سپس اختیاری بودن، unionها، additionalProperties و تاریخ‌ها را دستی اصلاح کنید؛ Schema را منبع و نوع‌ها را خروجی نگه دارید و با گام types:check در CI اعمالش کنید.

یک فرمان فایل می‌دهد. نوع درست نمی‌دهد.

یک‌خطی

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

از $ref، allOf، oneOf، anyOf پشتیبانی می‌کند و description را به JSDoc تبدیل می‌کند. برای تولید دسته‌ای با بنر و style انتخابی، API Node آن را از یک build-types.mjs کوچک صدا بزنید.

quicktype جایگزین است و همچنین می‌تواند از JSON نمونه schema استنتاج کند:

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

چهار چیزی که بعدش باید اصلاح کنید

اختیاری بودن. هر چیزی که در required نیست ? می‌شود. اما «همیشه حاضر، ممکن است null باشد» و «ممکن است غایب باشد» قراردادهای متفاوتی‌اند:

复制interface Order {
  remark?: string | null;   // may be missing
  status: string;
}

اگر بک‌اند همیشه remark: null می‌فرستد، ? را بردارید و بس کنید هر مصرف‌کننده برای undefined محافظت بنویسد.

unionهای بدون discriminant. oneOf معمولاً A | B می‌شود که TypeScript بدون یک فیلد literal نمی‌تواند محدودش کند. به هر شاخه در Schema ویژگی ثابت type اضافه کنید.

additionalProperties. حذف‌شده یا true گاهی [k: string]: unknown می‌دهد، گاهی any. اولی امن است، دومی بررسی نوع کل شیء را بی‌صدا غیرفعال می‌کند.

قالب تاریخ. format: "date-time" روی سیم یک رشته است. نگاشتش به Date یعنی باید deserialization هم انجام دهید، وگرنه مقدار زمان اجرا رشته می‌ماند در حالی که نوع دروغ می‌گوید.

جهت را ثابت نگه دارید

Schema منبع است، نوع‌ها خروجی. تولید Schema از نوع‌های دست‌نویس فقط اگر بازتولید اجباری و در CI اعمال شود قابل قبول است — وگرنه هر دو طرف منحرف می‌شوند و هیچ‌کس نمی‌داند کدام مرجع است.

در خط لوله بگذاریدش

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

types:check بخش مهم است: Schema را بدون بازتولید تغییر دهید و CI شکست می‌خورد.

پرسش‌های متداول

چرا فایل تولیدشده any دارد؟

معمولاً از additionalProperties برابر true یا حذف‌شده می‌آید که برخی تولیدکننده‌ها به [k: string]: any نگاشت می‌کنند. با unknown یا فیلدهای صریح جایگزینش کنید، چون any بررسی نوع کل شیء را غیرفعال می‌کند.

چگونه بعد از تولید فیلدهای اختیاری را اصلاح کنم؟

هر چیزی بیرون از required به ? تبدیل می‌شود، اما «همیشه حاضر، ممکن است null باشد» با «ممکن است غایب باشد» متفاوت است. اگر بک‌اند همیشه فیلد را می‌فرستد، ? را بردارید.

آیا CI باید وقتی Schema و نوع‌ها منحرف می‌شوند شکست بخورد؟

بله. اسکریپت types:check که بازتولید می‌کند و git diff --exit-code اجرا می‌کند، به‌محض تغییر Schema بدون بازتولید ساخت را شکست می‌دهد.

مطالعه بیشتر

• هم‌گام نگه داشتن Schema و نوع‌های TypeScript
• چرا Schemaهای تولیدشده داده واقعی را رد می‌کنند