حوّل هياكل Go إلى JSON!

أدخل هياكل Go لإنشاء JSON تجريبي وفق وسوم json الخاصة بها! يدعم Go (Golang) struct, json tags. مفيد لتوثيق واجهات API وأجسام الطلبات التجريبية (mock request body).
Go struct
النتيجة
 

حوّل هياكل Go إلى JSON!

الصق تعريفات struct في Go لتحصل على مستند JSON نموذجي مبني بالقواعد نفسها التي يطبّقها encoding/json عند الـ marshaling: أسماء الوسوم json:"..."، والحقول المخفية بـ -، والخيار ,string، والحقول غير المُصدَّرة ذات الأحرف الصغيرة، والـ structs المضمَّنة التي تُسطَّح.

يفيد في إنتاج جسم طلب لـ curl من struct طلب في Gin أو Echo أو net/http، وتجهيز عيّنات لـ gRPC-Gateway أو لوثائق REST، واكتشاف الحقول التي لا تُنتج وسومها المفتاح الذي توقعته.

طريقة الاستخدام

  1. الصق تعريفات type Xxx struct { ... }. كتل type ( ... ) المجمّعة وعدة structs معًا لا مشكلة فيها.
  2. إذا استخدم حقلٌ struct آخر، فضمّن تعريفه أيضًا. أنواع الحزم الخارجية غير الموجودة في الإدخال (مثل decimal.Decimal) تصبح null.
  3. لا توجد خيارات: أول struct لا يشير إليه نوع آخر هو JSON على المستوى الأعلى، لذا ضع الذي تريده أولًا أو احذف الـ structs غير المرتبطة.
  4. انسخ النتيجة إلى curl -d أو جسم طلب في Postman أو اختبار handler مبني على httptest.

مثال

المدخلات (Go struct)
type Base struct {
	ID        string    `json:"id"`
	CreatedAt time.Time `json:"created_at"`
}

type Job struct {
	Base
	Queue      string            `json:"queue"`
	Attempts   int               `json:"attempts,string"`
	Labels     map[string]string `json:"labels,omitempty"`
	TimeoutSec *int              `json:"timeout_sec,omitempty"`
	Token      string            `json:"-"`
	Done       bool
	lastErr    error
}
المخرجات (JSON)
{
  "id": "",
  "created_at": "0001-01-01T00:00:00Z",
  "queue": "",
  "attempts": "0",
  "labels": {
    "key": ""
  },
  "timeout_sec": 0,
  "Done": false
}

يضيف Base المضمَّن الحقلين id وcreated_at مباشرة إلى Job، ويصبح Attempts الموسوم بـ ,string السلسلة النصية "0" بدلًا من رقم. يُحذف Token (الوسم -) والحقل غير المُصدَّر lastErr، بينما يحتفظ Done غير الموسوم باسم حقله في Go مفتاحًا. ويُظهر time.Time القيمة الصفرية في Go، 0001-01-01T00:00:00Z.

الميزات المدعومة

  • يستخدم الوسم json:"name" مفتاحًا، ويعود إلى اسم الحقل كما هو تمامًا عند غياب الوسم.
  • يتخطى حقول json:"-" والحقول غير المُصدَّرة ذات الأحرف الصغيرة؛ أما json:"-," فيُبقي الحقل تحت المفتاح الحرفي -.
  • مع ,string تُغلَّف الحقول الرقمية والمنطقية كسلاسل نصية مثل "0" و"false".
  • تُسطَّح الـ structs المضمَّنة غير الموسومة داخل الأب، وتفوز الحقول الخارجية عند تعارض الأسماء؛ أما الـ struct المضمَّن الموسوم فيصبح كائنًا متداخلًا تحت ذلك الاسم.
  • تُملأ المؤشرات (*int، *Profile) بالنوع الذي تشير إليه، والأنواع المعرَّفة مثل type Status string تتبع نوعها الأساسي.
  • []byte يصبح سلسلة Base64 (فارغة)، وmap[int]T يستخدم المفتاح "0"، وtime.Duration هو العدد الصحيح بالنانو ثانية 0، وinterface{}/any تصبح null.
  • الـ structs المرجعية ذاتيًا مثل Children []Node تتوقف عند مصفوفة فارغة. وحقول الـ struct المتداخلة المجهولة مدعومة.

حالات الاستخدام

أجسام الطلبات لاختبارات الـ handlers

الصق الـ struct الذي تربطه بـ c.ShouldBindJSON(&req)، وولّد الجسم، واستدعِ نقطة النهاية عبر httptest.NewRequest أو curl. بما أن المفاتيح تأتي مباشرة من الوسوم، يقل احتمال عدم تطابق الربط.

العثور على أخطاء الوسوم

الخلط بين وسوم json:"user_id" وjson:"userId"، أو نسيان وسم يُسرّب مفتاحًا بأحرف كبيرة مثل UserID، يظهر بوضوح من نظرة واحدة إلى الناتج.

مشاركة المخطط مع عملاء بلغات أخرى

أعطِ مستهلكي الواجهة الأمامية أو Python ملف JSON المولَّد من struct الاستجابة في Go؛ ويمكنهم تحويله مجددًا إلى نماذج بأدوات مثل JSON → TypeScript أو JSON → Python.

ملاحظات وقيود

  • حقول omitempty تظهر دائمًا في العيّنة؛ بينما يحذفها الـ marshaling الحقيقي حين تحمل القيمة الصفرية.
  • المؤشر nil يُحوَّل إلى null، لكن العيّنة تُظهر الحالة المملوءة.
  • الأنواع التي لها MarshalJSON() مخصص والمحتوى الفعلي لـ json.RawMessage لا يمكن معرفتها ولا تنعكس في الناتج.
  • الخيارات الأحدث مثل omitzero في Go 1.24 وسلوك encoding/json/v2 غير مشمولة.

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

ما المفتاح الذي يحصل عليه حقل بلا وسم؟

يستخدم encoding/json اسم الحقل المُصدَّر حرفيًا، فيصبح Done bool هو "Done". فك الترميز في Go يطابق دون تمييز حالة الأحرف، لكن العملاء بلغات أخرى لا يفعلون ذلك، لذا فالوسوم الصريحة أكثر أمانًا.

لماذا يُضبط time.Time على السنة 0001؟

القيمة الصفرية لـ time.Time في Go هي 0001-01-01 00:00:00 UTC، وتُحوَّل بصيغة RFC 3339 إلى 0001-01-01T00:00:00Z. ولهذا تختلف عن تواريخ 1970 في صفحات التحويل الأخرى إلى JSON.

متى يكون json:",string" مفيدًا؟

غالبًا لمعرّفات int64 الكبيرة التي لا تستطيع JavaScript تمثيلها بدقة، فتنتقل كسلاسل نصية. تُظهر العيّنة "0"، فيتضح للعملاء أنهم سيستلمون سلسلة نصية.

أريد العكس: structs في Go من JSON.

استخدم صفحة JSON → Go struct. وإعادة إدخال ناتجها في هذه الصفحة طريقة سريعة للتحقق من أن الذهاب والإياب يحافظ على المفاتيح الأصلية.