مولّد كود من JSON

ما هو مولّد كود من JSON؟#

يقرأ مولّد الكود من JSON عيّنة مستند JSON، ويستنتج شكل البيانات — أي الحقول سلاسل، وأيها أرقام، وأيها كائنات متداخلة، وأيها مصفوفات مِن أي شيء — ويكتب أنواع الكيانات التي يستخدمها برنامج حقيقي لحمل تلك البيانات. فبدلًا من كتابة واجهة TypeScript، أو صنف Java، أو بنية Go، أو صنف C# يدويًا لمطابقة استجابة واجهة برمجية، تلصق استجابة مثال واحدة وتحصل على الأنواع جاهزة للإسقاط في مشروعك.

تحت الغلاف يجول القيمة المُحلَّلة ويستنتج مخططًا. تصير الكائنات المتداخلة نوعًا مسمًّى خاصًا بها؛ ونوع عنصر المصفوفة هو اتحاد شكل كل عنصر (فقائمة كائنات لا تحجم جميعها المفاتيح نفسها تُنتج أيضًا نوعًا واحدًا باتحاد الحقول). المفاتيح التي ليست معرّفات صالحة — مفتاح بواصلة مثل first-name، أو آخر يبدأ برقم — تُطهَّر إلى معرّف قانوني ويُحفظ المفتاح الأصلي كتعليق تسلسل، فيظل الذهاب والإياب يعمل.

المخرجات كود مصدر نصي عادي بلا اعتماد تشغيلي على هذه الصفحة. انسخه، الصقه في قاعدة شفرتك، اضبط أسماء الأنواع، فتحصل على نقطة بداية — لا نموذجًا منتهيًا، لكن الهيكل العظمي المُمل قد كُتب نيابةً عنك.

كيفية الاستخدام#

1. اختر الهدف من القائمة المنسدلة اللغة: TypeScript، أو Java، أو Go، أو C#.
2. اضبط الاسم الجذري (الافتراضي Root). يصير هذا اسم النوع الأكثر خروجًا — مثلًا User، Order، Response.
3. الصق JSON في اللوحة اليسرى. يظهر الكود المُولَّد حيًّا على اليمين؛ يُذكِر سطر الحالة بالأخطاء (JSON غير صالح، إدخال فارغ).
4. انقر نسخ لأخذ الكود إلى الحافظة.
5. يحمِّل مثال كائنًا متداخلًا بكائن فرعي ومصفوفة؛ ويعيد مسح ضبط اللوحتين.

الميزات الرئيسية#

• أربع لغات هدف. واجهات TypeScript، وأصناف Java، وبُنى Go، وأصناف C# — إدخال واحد، أربع مخرجات، تُبدَّل بقائمة منسدلة.
• استنتاج مخطط، لا كتابة أنواع حرفية. تصير الكائنات المتداخلة أنواعًا مسمّاة؛ وتُنتج مصفوفات الكائنات نوع عنصر مسمًّى بدلًا من قائمة any معتمة.
• دمج المصفوفات غير المتجانسة. حين تختلف حقول عناصر المصفوفة، يكون النوع المستنتَج هو الاتحاد — مفيد للاستجابات الواقعية الفوضوية حيث ليس كل عنصر يحوز كل مفتاح.
• آمن للمعرّف، وفيٌّ للمفتاح. تُطهَّر المفاتيح غير الصالحة كمعرّفات، ويُحفظ المفتاح الأصلي كتعليق تسلسل (@JsonProperty، وسم Go json:، JsonPropertyName)، فلا يزال JSON الأصلي يُفكّ تسلسله صحيحًا.
• حي ومحلي. يجري التوليد في متصفحك أثناء الكتابة أو تبديل الخيارات؛ لا تغادر البيانات الصفحة.

مثال عملي#

حمِّل مثال مع ضبط اللغة على TypeScript والاسم الجذري Root، فتكون المدخلات:

{
  "id": 1,
  "name": "Ada",
  "active": true,
  "address": { "city": "London", "zip": "NW1" },
  "tags": ["math", "logic"]
}

يُصدر المولّد واجهتَين — الجذر، ونوع Address مسمًّى للكائن المتداخل:

export interface Root {
  id: number;
  name: string;
  active: boolean;
  address: Address;
  tags: Array<string>;
}

export interface Address {
  city: string;
  zip: string;
}

بدِّل اللغة إلى Go فتصير المدخلات نفسها بُنى مع وسوم json: تحفظ المفاتيح الأصلية:

package model

type Root struct {
  Id       float64   `json:"id"`
  Name     string    `json:"name"`
  Active   bool      `json:"active"`
  Address  Address   `json:"address"`
  Tags     []string  `json:"tags"`
}

type Address struct {
  City  string  `json:"city"`
  Zip   string  `json:"zip"`
}

لاحظ كيف يهبط id، رقم JSON، كـ number في TypeScript وfloat64 في Go — لا يخمّن المولّد عددًا صحيحًا مقابل فاصلة عائمة، لأن JSON نفسها لا تميّز بينهما.

الأسئلة الشائعة#

لماذا حقل عددي الصحيح مُعطى كـ float64 / Double / double؟#

لأن لـ JSON نوع أرقام واحد ولا وسيلة للتمييز بين 5 و5.0. يربط المولّد كل رقم JSON بالنوع العددي العام للغة الهدف — number في TypeScript، وDouble في Java، وfloat64 في Go، وdouble في C# — فيكون النوع عريضًا كفايةً دائمًا لحمل أي قيمة. إن كنت تعرف أن حقلًا عدد صحيح دائمًا، فضيّقه يدويًّا إلى int / Long / int64 بعد ذلك.

ماذا يحدث حين لا تحجم كائنات مصفوفتي الحقول نفسها؟#

تُدمج أشكالها. مصفوفة مثل [{ "a": 1 }, { "a": 2, "b": "x" }] تُنتج نوع عنصر واحدًا يحوي a وb معًا، فيغطي نوع واحد كل عنصر. إن اختلف عنصران على نوع حقل بطريقة غير متوافقة (رقم هنا، سلسلة هناك)، يتحلل ذلك الحقل إلى any / Object بدلًا من اختيار جانب والخطأ في الآخر.

حقل في JSON يحوي واصلة، مثل first-name. هل سيفسد ذلك؟#

لا. يحوّل المولّد first-name إلى معرّف قانوني (firstName) لاسم الحقل ويُصدر تعليق تسلسل يسجّل المفتاح الأصلي — @JsonProperty("first-name") في Java، وسم json:"first-name" في Go، و[JsonPropertyName("first-name")] في C#، ومفتاح "first-name" بموجدات في TypeScript. لذا يُفكّ الكود المُولَّد تسلسل JSON الأصلي دون تغيير.

ماذا يفعل بقيمة null؟#

الحقل الذي قيمته null يُعامل كنوع مجهول. في TypeScript يصير any اختياريًّا (field?: any;)؛ وفي Java وC# يصير Object / object؛ وفي Go interface{}. هذه إشارة متعمَّدة — فـ null لا يخبرك شيئًا عمّا يحوزه الحقل حين يكون حاضرًا، فيرفض المولّد التخمين ويتركه لك لتملأه.