JSON به Go Struct: مولد اسکلت را تحویل میدهد، چهار چیز دست شما را میخواهد
جمعبندی: یک نمونه پاسخ API را در مبدل بچسبانید و در ده ثانیه struct های Go با تگ دارید — اما اعداد به float64 تبدیل میشوند، فیلدهای اختیاری خودبهخود هرگز pointer نمیشوند، omitempty ساختارهای خالی را حذف نمیکند و بیشتر تاریخها string باقی میمانند. جدول کامل نگاشت، تعادل میان pointer و omitzero، و چکلیست چهار مرحلهای برای نهاییکردن کد تولیدشده.

نتیجه در آغاز: structهایی که مبدل در ده ثانیه تولید میکند کامپایل میشوند، اما برای پروداکشن آماده نیستند. مولد فقط همان تک نمونهای را توصیف میکند که چسباندهاید — اعداد به float64 تبدیل میشوند، فیلدهای اختیاری خودبهخود هرگز pointer نمیشوند، omitempty ساختارهای خالی را کنار نمیگذارد، و بیشتر رشتههای تاریخ string میمانند. این چهار شکاف پس از چسباندن همچنان کار شماست.
تبدیل پاسخ API به structهای Go کاری کاملاً مکانیکی است، و هزینه کار مکانیکی در سکوت پنهان میشود: نام فیلد با غلط املایی خطای کامپایل نمیدهد، فقط فیلدی که برای همیشه صفر میماند؛ کلید اشتباه در مدیریت null — و
"note": nullدر پروداکشن جایی که کسی انتظارش را نداشت ظاهر میشود. تولید struct همترازی نامها و تایپها را حل میکند، اما دو چیز هرگز خودشان همتراز نمیشوند: تنوعهای بیرون از نمونه شما و پرتگاه میان سیستم تایپ Go و JSON.
مولد واقعاً چه میخواند: جدول نگاشت
هر مبدل JSON → Go روی همان جدول میچرخد. یک پاسخ معمول سفارش را از صفحه /convert/go این سایت عبور دهید — نمونه را بچسبانید، تگهای json را روشن کنید — و این شکل را میگیرید:
| مقدار JSON | تایپ Go تولیدشده | یادداشتها |
|---|---|---|
| string | string |
رشتههای تاریخ معمولاً string میمانند، time.Time را پایین ببینید |
| عدد صحیح | float64 |
encoding/json اعداد را درونیباً بهصورت double پارس میکند |
| اعشاری | float64 |
فیلدهای پولی را با کتابخانه decimal یا int64 در واحدهای کوچکتر جایگزین کنید |
| true / false | bool |
بدون تله |
| null | any |
یک نمونه null چیزی را اثبات نمیکند، fallback محافظهکارانه |
| شیء | struct نامدار | اشیای تودرتو به struct خودشان تبدیل میشوند |
شیء خالی {} |
map[string]any |
فیلد قابل مشاهدهای نیست، مولد حدس نمیزند |
| آرایه | []نوععضو |
نوع عضو از اولین نمونه استنتاج میشود |
| تایپهای مخلوط | any |
Go اتحاد (union) ندارد، فیلدهای چندتایپ به 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 به struct خودش یعنی 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:"-," هم هست — دومی یعنی کلید واقعاً - نام دارد.
Pointerها: nil تنها راه تمایز «غایب» از «صفر»
سیستم مقدار-صفرِ Go اجازه نمیدهد int و string «فیلد حاضر نیست» را بیان کنند — 0 و "" میتوانند داده واقعی باشند یا صرفاً پارسنشده. همان کلید JSON سه حالت دارد: حاضر با مقدار، حاضر بهصورت null، و غایب. تایپهای by-value فقط حالت اول را پوشش میدهند.
type Config struct {
Note string `json:"note,omitempty"` // فقط وقتی دقیقاً "" است حذف میشود
Alias *string `json:"alias,omitempty"` // وقتی nil است حذف میشود
Details *Meta `json:"details,omitempty"`
}
مقدار صفرِ فیلد pointer برابر nil است. json.Unmarshal وقتی کلید نیست یا null است آن را nil نگه میدارد، و omitempty فقط در همان حالت از آن میگذرد. به همین دلیل بیشتر مبدلها کلیدی به نام «برای اشیای تودرتو از pointer استفاده کن» دارند: روشن کنید — structهای تودرتو *Item میشوند، و در درخواست PATCH «فیلد ارسال نشد» و «null برای حذف ارسال شد» سرانجام از هم جدا میشوند. بهایش چکهای nil همهجا است — p.Address.Street وقتی Address برابر nil باشد panic میکند، یکی از رایجترین کرشهای رانتایم کد JSON در Go.
ساختار خالیای که omitempty از پسش برنمیآید، و حفرهای که omitzero پر میکند
تعریف رسمی omitempty بر اساس مقدار قضاوت میکند: false، 0، pointerهای 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 است؛ فقط pointer نیل دور ریخته میشود. از Go 1.24 کلید دومی هست، omitzero: بر اساس مقدار صفر Go قضاوت میکند و وقتی تایپ تعریفش کرده IsZero() bool را صدا میزند — تنها راه حذف time.Time صفر. با encoding/json/v2 (آزمایشی در Go 1.25) معنا دوباره جابهجا میشود: omitempty نسخه v2 بر اساس نتیجه JSON انکودشده قضاوت میکند (فقط null، ""، {}، [] خالی شمرده میشوند)، پس count: 0 در خروجی میماند؛ هنگام مهاجرت کد قدیمی، omitempty روی فیلدهای bool و عددی باید omitzero شود تا معنای اصلی حفظ شود.
هر عددی float64 میشود: تله صحیحهای بزرگ
بدون تایپ صریح، دیکودر encoding/json با اعداد مثل float64 رفتار میکند، و float64 فقط ۵۳ بیت مانتیس دارد. مورد کلاسیک جاوااسکریپت — 9007199254740993 تبدیل به 9007199254740992 — در Go هم هست، تا وقتی فیلد مقصد float64 یا any باشد.
var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] برابر float64(9007199254740992) است، دقت از دست رفته
سه راه خروج. فیلد struct را int64 اعلان کنید و دیکودر دقیقاً در آن پارس میکند. وقتی باید از any بگذرید، decoder.UseNumber() را صدا بزنید تا اعداد بهصورت رشتههای json.Number فرود بیایند که آگاهانه تبدیلشان میکنید. هرگز برای پول از ممیز شناور استفاده نکنید — واحدهای کوچکتر را در int64 نگه دارید یا کتابخانه decimal بگیرید. هر وقت API شناسههای snowflake یا شماره سفارشهای ۶۴ بیتی برمیگرداند، این بخش چک اجباری است.
time.Time فقط RFC 3339 میپذیرد
برابر "2024-01-15T10:30:00Z" مولد time.Time نگاشت میکند؛ برابر "2024-01-15 10:30:00" یک string میگذارد. تنبلی نیست — بندی سختگیرانه encoding/json است: time.Time پیادهساز UnmarshalJSON است و دقیقاً با layout RFC 3339 یعنی 2006-01-02T15:04:05Z07:00 پارس میکند. نبودِ T، نبودِ منطقه زمانی یا Z با offset در دنباله — همه شکست میخورند:
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را پیدا کنید، برای هر فیلد در fallback سه تا پنج نمونه واقعی ببینید، سپس روی تایپ مشخص یا pointer فرود بیاورید; - پهنای عددی را دوباره بررسی کنید: شناسهها، مبالغ و شمارندهها را از float64 به int64 / int32 / decimal منتقل کنید؛ در شک درباره پهنا، int64 بنویسید;
- اختیاریبودن را نشانهگذاری کنید: pointer یا omitempty/omitzero برای فیلدهای شیء درون آرایهها، بدنههای PATCH و فیلدهای nullable APIهای ثالث — معنای nil را یکبار، همینجا، تصمیم بگیرید;
- کامپایل و تست رفتوبرگشت:
go vetرا اجرا کنید، سپس تست رفتوبرگشت Marshal→Unmarshal اضافه کنید تا فرمت روی سیم قفل شود — این تست لغزش رفتارِ بهروزرسانیهای آینده encoding/json را میگیرد.
از نمونه تا قرارداد: مرز مبدل
مبدل پاسخ میدهد «این نمونه چه شکلی است»، نه «این اینترفیس همیشه چه شکلی خواهد بود». ابزارهای رقیب همین را در مستندات خودشان رک میگویند: یک نمونه نمیتواند تنوعهای پروداکشن را اثبات کند — اختیاریبودن، قالب تاریخها و مقادیر enum نیازمند بازبینی انسانی است. پس عادت بسازید: پیش از چسباندن، پاسخهایی را جمع کنید که بیشترین استعداد را برای افشای تفاوت دارند (لیست خالی، همه فیلدها، یکی پر از null)؛ پس از تولید، خروجی را پیشنویس بدانید نه تحویل. اگر اینترفیس سند قرارداد دارد، قیدها را با JSON Schema صریح کنید و کد تولیدشده را با آن همتراز کنید — چند پله از استنتاج از نمونه بالاتر است. برای نگاه عرضی به همان مسئله، سمت Java در آزمون میدانی مولد Java ما پوشش داده شده، قرارداد فرانتاندد در اینترفیسهای TypeScript؛ پرتگاه دقت عددی در هر زبانی با لباسی دیگر بازمیگردد، با جزئیات در تله اعداد بزرگ JSON.
کدام فیلدها پس از تولید هنوز نیازمند بازبینی دستیاند؟
دستکم چهار مورد: fallbackهای any، پهنای عددی (float64 → int64)، تبدیل فیلدهای اختیاری به pointer، و اینکه فیلدهای تاریخ string باشند یا time.Time. هر چهار، تنوعهای پروداکشناند که در نمونه دیده نمیشوند؛ مولد حدس نمیزند، انسان باید تکمیل کند.
چرا فیلد من پس از افزودن omitempty هنوز در JSON ظاهر میشود؟
omitempty فقط مقادیر صفر را رد میکند: false، 0، ""، nil، slices خالی. ساختار خالی {} مقدار صفر نیست، پس زنده میماند — فیلد را pointer کنید. time.Time صفر به omitzero نیاز دارد، نه omitempty.
چرا شناسه صحیح بزرگ من بعد از دیسریالایز تغییر کرد؟
بدون تایپ صریح، encoding/json اعداد را float64 پارس میکند که ۵۳ بیت مانتیس دارد؛ صحیحهای فراتر از 2^53 دقت از دست میدهند. فیلد را int64 تایپ کنید، یا UseNumber() را صدا بزنید تا اعداد بهصورت json.Number بمانند.
چه زمانی فیلد شیء تودرتو باید pointer باشد؟
دو حالت: فیلد ممکن است غایب یا null باشد (nil «ارسالنشده» را از «مقدار صفر» جدا میکند)، و درخواست PATCH باید «ارسالنشده» و «null برای حذف ارسال شد» را تفکیک کند. در structهای پاسخ معمولی با فیلدهای non-nullable، تایپهای by-value امنترند — هزینه چکهای nil را فقط وقتی تمایز واقعاً لازم است بپردازید.