الصق تعريفات struct في Go لتحصل على مستند JSON نموذجي مبني بالقواعد نفسها التي يطبّقها encoding/json عند الـ marshaling: أسماء الوسوم json:"..."، والحقول المخفية بـ -، والخيار ,string، والحقول غير المُصدَّرة ذات الأحرف الصغيرة، والـ structs المضمَّنة التي تُسطَّح.
يفيد في إنتاج جسم طلب لـ curl من struct طلب في Gin أو Echo أو net/http، وتجهيز عيّنات لـ gRPC-Gateway أو لوثائق REST، واكتشاف الحقول التي لا تُنتج وسومها المفتاح الذي توقعته.
type Xxx struct { ... }. كتل type ( ... ) المجمّعة وعدة structs معًا لا مشكلة فيها.decimal.Decimal) تصبح null.curl -d أو جسم طلب في Postman أو اختبار handler مبني على httptest.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
}{
"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".*int، *Profile) بالنوع الذي تشير إليه، والأنواع المعرَّفة مثل type Status string تتبع نوعها الأساسي.[]byte يصبح سلسلة Base64 (فارغة)، وmap[int]T يستخدم المفتاح "0"، وtime.Duration هو العدد الصحيح بالنانو ثانية 0، وinterface{}/any تصبح null.Children []Node تتوقف عند مصفوفة فارغة. وحقول الـ struct المتداخلة المجهولة مدعومة.الصق الـ 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"، فيتضح للعملاء أنهم سيستلمون سلسلة نصية.
استخدم صفحة JSON → Go struct. وإعادة إدخال ناتجها في هذه الصفحة طريقة سريعة للتحقق من أن الذهاب والإياب يحافظ على المفاتيح الأصلية.