راهنمای تبدیل JSON به TypeScript، Zod و JSON Schema
زمان مطالعه: ۲ دقیقه
این ابزار چیست؟
وقتی با یک API تازه کار میکنید، معمولاً اول یک نمونه پاسخ JSON دارید و باید برایش تایپ TypeScript بنویسید یا اعتبارسنجی Zod بسازید. نوشتن دستی اینها برای پاسخهای بزرگ و تودرتو وقتگیر است و با یک غلط تایپی خراب میشود. این ابزار از همان نمونه، رابطهای TypeScript، اسکیمای Zod یا JSON Schema نسخهی 2020-12 میسازد.
شیءهای تودرتو نوع نامدار جدا میگیرند، عدد صحیح از اعشاری جدا میشود و گزینههایی برای فقطخواندنی، type بهجای interface، اختیاری با undefined و تبدیل مقدارهای محدود به enum دارید. پردازش در مرورگر شما انجام میشود.
گامبهگام
نمونهی JSON را بچسبانید
یک پاسخ واقعی یا نمونهی کامل را در «نمونهی JSON» بگذارید؛ حجم تا ۲ مگابایت است.
نوع خروجی را انتخاب کنید
TypeScript، Zod یا JSON Schema را بردارید.
نام و گزینهها را تنظیم کنید
در «نام نوع اصلی» نامی مثل User بنویسید و گزینههای «فقطخواندنی»، «استفاده از type» و «اختیاری با undefined» را مطابق سبک پروژه انتخاب کنید.
خروجی را بردارید
کد ساختهشده را کپی کنید و پیش از استفاده با چشم مرور کنید؛ آنچه در نمونه نبوده، در تایپ هم نیست.
نمونههای کاربردی
پاسخ API به TypeScript
شیء داخلی address رابط جدا با نام Address میگیرد.
{"id":1,"name":"علی","tags":["a"],"address":{"city":"تهران"}}نتیجه: export interface Root { id: number; name: string; tags: string[]; address: Address; } export interface Address { city: string; }
همان نمونه به Zod
در Zod عدد صحیح با int() مشخص میشود و نوع TypeScript از خود اسکیما به دست میآید.
{"id":1,"name":"علی","tags":["a"],"address":{"city":"تهران"}}نتیجه: import { z } from "zod"; export const RootSchema = z.object({ id: z.number().int(), name: z.string(), tags: z.array(z.string()), address: z.object({ city: z.string(), }), }); export type Root = z.infer<typeof RootSchema>;
اشتباههای رایج
- ساختن تایپ از یک نمونهی ناقص: اگر فیلدی در نمونه نیامده یا همیشه پر بوده، تایپ آن را اجباری یا ناموجود میداند. چند پاسخ مختلف را در یک آرایه بگذارید تا فیلدهای اختیاری تشخیص داده شوند.
- آرایهی خالی در نمونه: از [] نمیتوان فهمید عنصرها چه نوعی دارند. نمونهای با دستکم یک عنصر بدهید.
- نتیجه گرفتن enum از نمونهی کوچک: اگر سه پاسخ فقط دو وضعیت داشته باشند، enum ساختهشده مقدارهای واقعی دیگر را رد میکند. حد enum را با احتیاط بالا ببرید.
- اعتماد به تایپ TypeScript برای دادهی بیرونی: تایپ در زمان اجرا چیزی را بررسی نمیکند. برای ورودی API از خروجی Zod یا JSON Schema استفاده کنید.
تایپ یا اعتبارسنجی؟
رابط TypeScript فقط هنگام نوشتن کد کمک میکند و پس از کامپایل حذف میشود؛ اگر سرور دادهی دیگری بفرستد، برنامه متوجه نمیشود. اسکیمای Zod در زمان اجرا داده را بررسی میکند و همان تایپ را هم با z.infer میدهد، پس یک منبع حقیقت دارید.
JSON Schema قالب مستقل از زبان است و برای مستندسازی API، اعتبارسنجی در زبانهای دیگر و ابزارهایی مثل OpenAPI به کار میرود.
پرسشهای متداول
- فیلدهای اختیاری چطور تشخیص داده میشوند؟
- اگر در آرایهای از شیءها، فیلدی در بعضی عنصرها نباشد اختیاری (?) میشود. اگر نوع فیلد در عنصرها فرق کند، اتحاد نوعها (مثلاً number | string) ساخته میشود و null به صورت | null میآید.
- خروجی چقدر دقیق است؟
- تایپها فقط از نمونهی شما حدس زده میشوند. اگر نمونه همهی حالتها را نداشته باشد (مثلاً آرایهی خالی)، نوع unknown میآید و باید آن را دستی اصلاح کنید.
- کلیدهای فارسی یا کلیدهایی مثل my-key چه میشوند؟
- کلیدهایی که شناسهی معتبر جاوااسکریپت نیستند داخل نقلقول نوشته میشوند؛ نام interface از روی کلید و بهصورت PascalCase ساخته میشود.