JSON إلى Go Struct: المولّد يسلّم الهيكل، وأربعة أمور تحتاج يدك
الخلاصة: الصق استجابة API نموذجية في المحوّل وخلال عشر ثوانٍ تحصل على struct للغة Go مع الوسوم — لكن الأرقام تتحول إلى float64، والحقول الاختيارية لا تصبح مؤشرات من تلقاء نفسها، وomitempty لا يزيل البنى الفارغة، ومعظم التواريخ تبقى سلسلة نصية. جدول تحويل كامل، وتوازن بين المؤشر وomitzero، وقائمة تحقق من أربع خطوات لإتقان الكود المولَّد.

الخلاصة أولًا: البنى التي ينتجها المحوّل في عشر ثوانٍ تُجمَّع بنجاح، لكنها ليست جاهزة للإنتاج. المولّد يصف النموذج الوحيد الذي لصقته فقط — الأرقام تتحول إلى float64، والحقول الاختيارية لا تصبح مؤشرات بنفسها، وomitempty لا يسقط البنى الفارغة، ومعظم سلاسل التواريخ تبقى نصية. هذه الفجوات الأربع بعد اللصق تبقى عملك أنت.
تحويل استجابة API إلى بنى Go عمل ميكانيكي خالص، وثمن العمل الميكانيكي يختبئ في الصمت: اسم حقل به خطأ إملائي لا يسبب خطأ تجميع، فقط حقلًا يبقى صفرًا للأبد؛ مفتاح خاطئ في التعامل مع null — ويظهر
"note": nullفي الإنتاج حيث لم يتوقعه أحد. توليد البنى يحل محاذاة الأسماء والأنواع، لكن أمرين لا يتوازنان أبدًا من تلقاء نفسيهما: الأشكال خارج نموذجك، والهاوية بين نظام أنواع Go وأنواع JSON.
ما يقرأه المولّد فعلًا: جدول التحويل
كل محوّل JSON ← Go يعمل على الجدول نفسه. مرّر استجابة طلب نموذجية عبر صفحة /convert/go في هذا الموقع — الصق النموذج، شغّل وسوم json — وستحصل على هذا الشكل:
| قيمة JSON | نوع Go المولَّد | ملاحظات |
|---|---|---|
| string | string |
سلاسل التواريخ تبقى عادة نصية، انظر time.Time أدناه |
| عدد صحيح | float64 |
يحلل encoding/json الأرقام داخليًا كـ double |
| عشري | float64 |
استبدل الحقول المالية بمكتبة decimal أو int64 بوحدات أصغر |
| true / false | bool |
لا فخاخ |
| null | any |
نموذج null واحد لا يثبت شيئًا، احتياط متحفظ |
| كائن | struct مسمى | الكائنات المتداخلة تصبح بنى خاصة بها |
كائن فارغ {} |
map[string]any |
لا حقول ملحوظة، المولّد لا يخمّن |
| مصفوفة | []نوعالعنصر |
يُستنتج نوع العنصر من أول نموذج |
| أنواع مختلطة | any |
ليس في Go اتحادات، الحقول متعددة الأنواع تسقط في any |
// نموذج الإدخال
// {"id":"A-1029","items":[{"sku":"J-01","qty":2}],"coupon":null}
type Root struct {
ID string `json:"id"`
Items []Item `json:"items"`
Coupon any `json:"coupon"`
}
type Item struct {
Sku string `json:"sku"`
Qty int `json:"qty"`
}
ثلاث ملاحظات. الكائن المتداخل items أصبح بنية خاصة به تسمى Item يشير إليها slice. أما coupon فظهر بصيغة null فقط: المولّد لا يستطيع إثبات ما سيصبح لاحقًا فيسقط في any. والرقم qty يهبط int أو float64 بحسب الأداة — الاستراتيجيات تختلف، لكنها كلها تقوم على الافتراض نفسه: النموذج هو الحقيقة كاملة.
وسوم json: الأسماء الأصلية والخيارات وثلاثة أخطاء سهلة
الوسوم تحمل أعلى كثافة معلومات في مخرجات المولّد، وهي أيضًا الجزء الأسهل الخطأ عند التعديل. القواعد تأتي مباشرة من توثيق encoding/json:
Field int `json:"myName"` // يظهر تحت المفتاح myName
Field int `json:"myName,omitempty"` // حقل صحيح يُحذف عندما يكون فارغًا
Field int `json:",omitempty"` // اسم حقل افتراضي، الخيار فقط
Field int `json:"-"` // مُتجاهل دائمًا، لا ترميز ولا فك ترميز
Field int64 `json:"id,string"` // رقم مُرمَّز داخل سلسلة نصية
ثلاثة إهمالات تستحق الحفظ. أولًا، الفاصلة الافتتاحية في json:",omitempty" — عندما تريد فقط تخطي القيم الفارغة دون إعادة تسمية المفتاح، الفاصلة إلزامية؛ بدونها يُعامل الحقل كمفتاح اسمه حرفيًا ,omitempty. ثانيًا، احتفظ بمفتاح JSON الأصلي في الوسم (user_id، html_url) بينما يستخدم حقل Go الاصطلاح المألوف (UserID، HTMLURL): بدون وسم تتم المطابقة باسم الحقل حرفيًا، فمفتاح userId في الاستجابة لا يُطابق أبدًا — بصمت. ثالثًا، إلى جانب json:"-" يوجد json:"-," — الأخير يعني أن المفتاح اسمه فعلًا -.
المؤشرات: nil هي الطريقة الوحيدة للتمييز بين "غائب" و"صفر"
نظام القيم الصفرية في Go يمنع int وstring من التعبير عن "حقل غير موجود" — 0 و"" قد تكونا بيانات حقيقية أو مجرد غير محللة. المفتاح الواحد في JSON له ثلاث حالات: موجود بقيمة، موجود بصيغة null، وغائب. الأنواع بالقيمة تغطي الحالة الأولى فقط.
type Config struct {
Note string `json:"note,omitempty"` // يُحذف فقط عندما يكون "" بالضبط
Alias *string `json:"alias,omitempty"` // يُحذف عندما يكون nil
Details *Meta `json:"details,omitempty"`
}
القيمة الصفرية لحقل المؤشر هي nil. يتركه json.Unmarshal بقيمة nil عندما يكون المفتاح غائبًا أو null، وomitzty يتخطاه في تلك الحالة فقط. لهذا يقدم معظم المحوّلات مفتاح "استخدم مؤشرات للكائنات المتداخلة": شغّله — البنى المتداخلة تصبح *Item، وطلب PATCH يفرّق أخيرًا بين "حقل لم يُرسل" و"أُرسل null للحذف". الثمن فحوص nil في كل مكان — p.Address.Street يدخل في panic عندما يكون Address هو nil، أحد أعطاب وقت التشغيل الأكثر شيوعًا في كود JSON بلغة Go.
البنية الفارغة التي لا يستطيع omitempty إسقاطها، والثغرة التي يسدها omitzero
التعريف الرسمي لـ omitempty يحكم بالقيم: false، 0، مؤشرات nil، واجهات nil، ومصفوفات أو slices أو maps أو سلاسل بطول صفر. لاحظ ما ليس في القائمة: البنى الفارغة.
type Order struct {
Meta Meta `json:"meta,omitempty"`
}
type Meta struct {
Version string
Build int
}
// Meta{Version: "1.0"} → "meta":{"version":"1.0","build":0}
// Meta{} → "meta":{} ← omitempty لم يفعل شيئًا
حقل من نوع struct لا يُحذف أبدًا بواسطة omitempty — يعيش في الذاكرة كحاوية بحجم ثابت، والحاوية الموجودة ليست "فارغة". الإصلاح تحويل الحقل إلى *Meta؛ المؤشر nil فقط هو ما يُرمى. منذ Go 1.24 يوجد مفتاح ثانٍ، omitzero: يحكم بالقيمة الصفرية في Go، مستدعيًا IsZero() bool عندما يعرفها النوع — الطريقة الوحيدة لحذف time.Time الصفري. مع encoding/json/v2 (تجريبي في Go 1.25) ينزاح المعنى مجددًا: omitempty في v2 يحكم بالنتيجة JSON المرمَّزة (null و"" و{} و[] فقط تُحسب فارغة)، فبقي count: 0 في المخرجات؛ وعند ترحيل الكود القديم يجب أن يتحول omitempty على الحقول المنطقية والرقمية إلى omitzero للحفاظ على المعنى الأصلي.
كل رقم يصبح float64: فخ الأعداد الصحيحة الكبيرة
بدون نوع صريح، يتعامل مزيل الترميز في encoding/json مع الأرقام كـ float64، وfloat64 لديه 53 بت مانتيسا فقط. الحالة الكلاسيكية في JavaScript — 9007199254740993 تتحول إلى 9007199254740992 — موجودة في Go أيضًا، ما دام الحقل الهدف float64 أو any.
var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] يساوي float64(9007199254740992)، الدقة ضاعت بالفعل
ثلاثة مخارج. أعلن حقل البنية int64 وسيحللها مزيل الترميز بدقة فيه. عندما تضطر للمرور عبر any، استدعِ decoder.UseNumber() لتصل الأرقام كسلاسل json.Number تحوّلها بقصد. لا تستخدم الفاصلة العائمة للمال أبدًا — خزّن الوحدات الأصغر في int64 أو استخدم مكتبة decimal. كلما أعادت واجهة API معرفات snowflake أو أرقام طلبات بـ 64 بت، فهذا القسم فحص إلزامي.
time.Time يقبل RFC 3339 فقط
أمام "2024-01-15T10:30:00Z" يرسم المولّد time.Time؛ وأمام "2024-01-15 10:30:00" يترك سلسلة نصية. ليس كسلًا — إنه قيد صارم في encoding/json: time.Time يطبق UnmarshalJSON ويحلل بدقة وفق نسق RFC 3339 وهو 2006-01-02T15:04:05Z07:00. غياب T أو غياب المنطقة الزمنية أو Z يتبعها إزاحة — كلها تفشل:
parsing time "\"2022-07-27T14:16:00Z04:00\"" as
"\"2006-01-02T15:04:05Z07:00\"": cannot parse "04:00\"" as "\""
حين لا يمكن تغيير تنسيق المصدر، الإصلاح المعياري نوع مخصص يلف time.Time ويحاول UnmarshalJSON الخاص به عدة نسق:
type CustomDate struct{ time.Time }
func (c *CustomDate) UnmarshalJSON(b []byte) error {
s := strings.Trim(string(b), `"`)
t, err := time.Parse("2006-01-02 15:04:05", s)
if err != nil {
t, err = time.Parse(time.RFC3339, s)
if err != nil {
return fmt.Errorf("invalid date format: %w", err)
}
}
c.Time = t
return nil
}
قائمة تحقق من أربع خطوات بعد التوليد
أربع خطوات تفصل مخرجات المولّد عن كود الإنتاج، ومرورها مرة واحدة أرخص من التنقيح لاحقًا:
- استبدل كل fallback من نوع any: ابحث عن
any، راجع ثلاثة إلى خمسة نماذج حقيقية لكل حقل ساقط في الاحتياط، ثم أنزله إلى نوع محدد أو مؤشر؛ - راجع العروض الرقمية مجددًا: انقل المعرفات والمبالغ والعدادات من float64 إلى int64 / int32 / decimal؛ في الشك عن العرض اكتب int64؛
- ضع علامة الاختيارية: مؤشرات أو omitempty/omitzero لحقول الكائنات في المصفوفات وأجسام PATCH وحقول nullable لواجهات الأطراف الثالثة — حدد دلالة nil مرة واحدة، هنا؛
- جمّع واختبر الاتجاهين: شغّل
go vet، ثم أضف اختبار ذهاب وعودة Marshal→Unmarshal لتثبيت التنسيق على السلك — يلتقط انزياح سلوك تحديثات encoding/json القادمة.
من النموذج إلى العقد: حدود المحوّل
المحوّل يجيب عن سؤال "كيف يبدو هذا النموذج"، لا "كيف سيبدو هذا النمط دائمًا". الأدوات المنافسة تقول ذلك صراحة في توثيقها نفسه: نموذج واحد لا يستطيع إثبات أشكال الإنتاج — الاختيارية وتنسيقات التواريخ وقيم العدّ تحتاج مراجعة بشرية. فابنِ العادة: قبل اللصق اجمع الاستجابات الأكثر ميولًا لكشف الفروق (قائمة فارغة، جميع الحقول، واحدة مليئة بـ null)؛ وبعد التوليد عامل المخرجات كمخطط لا تسليم. إذا كان للنمط وثيقة عقد، فاجعل القيود صريحة عبر JSON Schema وحاذِ الكود المولَّد معها — يتغلب على الاستنتاج من النماذج بمراحل. للنظر الجانبي في المسألة نفسها، الطرف Java مغطى في اختبارنا الميداني لمولد Java، وعقد الواجهة الأمامية في واجهات TypeScript؛ وهاوية دقة الأرقام تعود في كل لغة بزي مختلف، مفصلة في فخ الأعداد الكبيرة في JSON.
ما الحقول التي تحتاج بعد التوليد مراجعة يدوية لا تزال؟
أربعة على الأقل: الاحتياطات any، والعروض الرقمية (float64 ← int64)، وتحويل الحقول الاختيارية إلى مؤشرات، وهل تكون حقول التواريخ string أم time.Time. الأربعة كلها أشكال إنتاج غير مرئية في النموذج؛ المولّد لا يخمّن، والإنسان عليه أن يكمل.
لماذا يظهر حقي في JSON بعد إضافة omitempty؟
يتخطى omitempty القيم الصفرية فقط: false و0 و"" وnil وslices الفارغة. البنية الفارغة {} ليست قيمة صفرية، فتنجو — حوّل الحقل إلى مؤشر. أما time.Time الصفري فيحتاج omitzero لا omitempty.
لماذا تغيّر معرّفي الصحيح الكبير بعد إزالة الترميز؟
بدون نوع صريح يحلل encoding/json الأرقام كـ float64 الذي يحمل 53 بت مانتيسا؛ الأعداد الصحيحة وراء 2^53 تفقد الدقة. اكتب الحقل int64 أو استدعِ UseNumber() لإبقاء الأرقام كـ json.Number.
متى يكون حقل الكائن المتداخل مؤشرًا؟
حالتان: الحقل قد يكون غائبًا أو null (nil يفصل "لم يُرسل" عن "القيمة الصفرية")، وطلب PATCH يحتاج التمييز بين "لم يُرسل" و"أُرسل null للحذف". في بنى الاستجابة الاعتيادية بحقولها غير القابلة للصفير، الأنواع بالقيمة أأمن — ادفع ثمن فحوص nil فقط عندما تحتاج التمييز فعلًا.