مولد البنى من JSON إلى TypeScript / Go / Rust

يولّد أنواعًا اصطلاحية في لغتك المستهدفة بالاستدلال على المخطط من عينة JSON أو أكثر. تُستنتَج أنواع الحقول — تبقى السلاسل سلاسل، وتصبح الأرقام نوعًا رقميًا في اللغة، والبولين bool، والمصفوفات شرائح/قوائم/مصفوفات، والكائنات المتداخلة أنواعًا متداخلة. الحقول الاختيارية (تلك التي تكون أحيانًا null أو مفقودة عبر العينات) تُعلَّم في المخرج كقابلة للقيمة null. مدعوم بـ quicktype-core، نفس المحرّك خلف quicktype.io.

مثال

مدخل JSON:

{
  "name": "Ada",
  "age": 36,
  "active": true,
  "tags": ["math", "logic"]
}

مخرج TypeScript (الهدف = TypeScript، اسم النوع = User):

export interface User {
  name: string;
  age: number;
  active: boolean;
  tags: string[];
}

مزالق شائعة وكيفية التعامل معها

لاستنتاج الأنواع من JSON حدود جوهرية — لا يحمل JSON معلومات كافية لتقييد نظام أنواع كاملًا. تغطي الأنماط أدناه الحالات التي قد لا يتطابق فيها النوع المستنتَج مع ما تريد.

• الاختياري مقابل المطلوب من عينة واحدة. لا يستطيع كائن JSON واحد إخبار المولّد بأي الحقول اختيارية. وفّر عينات متعددة (الصق مصفوفة JSON من كائنات تمثيلية) كي يتمكّن المولّد من تعليم الحقول التي تنقص أحيانًا كاختيارية.
• مصفوفات فارغة. `{"items": []}` ينتج مصفوفة من `any` — لا يوجد عنصر للاستنتاج منه. أضف مثالًا واحدًا على الأقل ممتلئًا، أو صحّح النوع يدويًا بعد التوليد.
• عناصر مصفوفة غير متجانسة. مصفوفة JSON `[1, "two"]` تصبح نوع اتحاد — قد تكون النتيجة غير عملية في بعض اللغات المستهدفة (Go خاصة). إن كان من المفترض أن تكون متجانسة في بياناتك الفعلية فعدِّل العينة.
• سلاسل التواريخ. لا يحوي JSON نوع Date. تُستنتَج سلاسل ISO 8601 على أنها `string`. يستطيع quicktype أحيانًا اكتشافها بصفتها Date في مخرج TypeScript — اضبط يدويًا لتحقيق نَوع أقوى.
• معرّفات رقمية تفقد الدقة. الأرقام في JSON الأكبر من 2^53 (معرّفات 64 بت كبيرة) تفقد الدقة عند تحليلها بـ JavaScript. يستخدم نوع TypeScript المُولَّد `number` على أي حال. للحصول على دقة 64 بت استخدم `string` في JSON أو رقّ يدويًا إلى نوع `bigint`.
• حقول بشرطة سفلية مقابل camelCase. يحفظ المولّد أسماء حقول JSON كما هي. إذا كان JSON بصيغة snake_case والهدف يتوقّع camelCase، يخرج الناتج بحقول snake_case مع تعليقات serde/json حيثما أمكن. تخطَّ ذلك بمعالجة لاحقة أو باستخدام أعلام quicktype CLI.

لماذا التوليد الأول بطيء؟

حزمة محرّك quicktype حوالي 465 كيلوبايت بعد الضغط. تُحمَّل عند أول نقرة على «توليد» وتستغرق 2-3 ثوانٍ على 4G. بعدها تبقى الوحدة مخزَّنة في الذاكرة لباقي جلسة الصفحة، ويخزّنها المتصفح بين الزيارات، فتظل النقرات الأولى لاحقًا فورية ما لم تُمسَح ذاكرة التخزين المؤقت.

هل يمكنني التوليد من عدة عينات JSON؟

لُف عيناتك في مصفوفة JSON والصق المصفوفة. يستنتج المولّد اتحاد الحقول المرئية عبر العينات ويُعلِّم تلك المفقودة في عينة واحدة على الأقل بأنها اختيارية. هذه أفضل طريقة لضمان تحمّل أنواعك المُولَّدة لتغيّرات بياناتك الفعلية.

أي لغة أختار لكود الخادم؟

اختر ما يستخدمه مشروعك بالفعل. مخرج Go يستخدم وسوم البنى المعيارية لـ `encoding/json`. وRust يستخدم اشتقاقات serde. وKotlin يستخدم تعليقات kotlinx.serialization. وJava ينتج POJOs متوافقة مع Jackson. الاختيار وفق المشروع لا التفضيل.

هل تُحفَظ تعليقات الحقول؟

لا توجد صياغة تعليقات في JSON، فلا تعليقات في الإدخال لتنقل. قد يضيف quicktype في مخرج بعض اللغات تعليقات وثائقية تلقائية — وهي أوصاف مولَّدة لا محتوى المستخدم.

هل يُرفَع JSON الخاص بي؟

لا. كل شيء يعمل في متصفحك — يُعالَج مدخلك محليًا بوحدة JavaScript quicktype-core على هذه الصفحة. تُحمَّل quicktype-core ذاتها من نفس المصدر (مضيف الأصول الثابتة للموقع)؛ لا يرى أي خادم طرف ثالث بياناتك.

ما حجم عينة JSON التي يمكنني استخدامها؟

حتى نحو 5 ميغابايت من JSON قبل أن يبدأ المولّد في أخذ وقت ملحوظ. صُمِّم المولّد لعينات تمثيلية لا لمجموعات بيانات كاملة — عادةً ما تكفي حفنة من الكائنات لاستنتاج مخطط نظيف.