پرش به محتوای اصلی

راهنمای تبدیل JSON به TypeScript، Zod و JSON Schema

زمان مطالعه: ۲ دقیقه

این ابزار چیست؟

وقتی با یک API تازه کار می‌کنید، معمولاً اول یک نمونه پاسخ JSON دارید و باید برایش تایپ TypeScript بنویسید یا اعتبارسنجی Zod بسازید. نوشتن دستی این‌ها برای پاسخ‌های بزرگ و تودرتو وقت‌گیر است و با یک غلط تایپی خراب می‌شود. این ابزار از همان نمونه، رابط‌های TypeScript، اسکیمای Zod یا JSON Schema نسخه‌ی 2020-12 می‌سازد.

شیءهای تودرتو نوع نام‌دار جدا می‌گیرند، عدد صحیح از اعشاری جدا می‌شود و گزینه‌هایی برای فقط‌خواندنی، type به‌جای interface، اختیاری با undefined و تبدیل مقدارهای محدود به enum دارید. پردازش در مرورگر شما انجام می‌شود.

گام‌به‌گام

  1. نمونه‌ی JSON را بچسبانید

    یک پاسخ واقعی یا نمونه‌ی کامل را در «نمونه‌ی JSON» بگذارید؛ حجم تا ۲ مگابایت است.

  2. نوع خروجی را انتخاب کنید

    TypeScript، Zod یا JSON Schema را بردارید.

  3. نام و گزینه‌ها را تنظیم کنید

    در «نام نوع اصلی» نامی مثل User بنویسید و گزینه‌های «فقط‌خواندنی»، «استفاده از type» و «اختیاری با undefined» را مطابق سبک پروژه انتخاب کنید.

  4. خروجی را بردارید

    کد ساخته‌شده را کپی کنید و پیش از استفاده با چشم مرور کنید؛ آنچه در نمونه نبوده، در تایپ هم نیست.

نمونه‌های کاربردی

  • پاسخ 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 ساخته می‌شود.

ابزارهای مرتبط