JSON ל-Go Struct: המחולל מסור את השלד, ארבעה דברים דורשים את הידיים שלכם
שורה תחתונה: מדביקים תשובת API לדוגמה לממיר ובעשר שניות יש לכם struct של Go עם תגיות — אבל מספרים הופכים ל-float64, שדות אופציונליים לעולם לא הופכים למצביעים בעצמם, omitempty לא מוריד מבנים ריקים, ורוב התאריכים נשארים מחרוזת. טבלת מיפוי מלאה, האיזון בין מצביע ל-omitzero, ורשימת בדיקה בת ארבעה שלבים לגימור הקוד שנוצר.

מסקנה תחילה: המבנים שממיר מייצר בעשר שניות מתקמפלים, אבל לא מוכנים לייצור. המחולל מתאר רק את הדוגמה היחידה שהדבקתם — מספרים הופכים ל-float64, שדות אופציונליים לעולם לא הופכים למצביעים בעצמם, omitempty לא מוריד מבנים ריקים, ורוב מחרוזות התאריך נשארות מחרוזות. ארבעת הפערים האלה אחרי ההדבקה נשארים העבודה שלכם.
להפוך תשובת API ל-struct של Go הוא עבודה מכנית טהורה, והעלות של עבודה מכנית מסתתרת בשקט: שם שדה עם שגיאת כתיב לא מעלה שגיאת קומפילציה, רק שדה שנשאר אפס לנצח; מתג שגוי בטיפול ב-null — ו-
"note": nullמופיע בייצור במקום שאף אחד לא ציפה לו. ייצור מבנים פותר יישור שמות וטיפוסים, אבל שני דברים לעולם לא מתיישרים לבד: הווריאציות מחוץ לדוגמה שלכם, והתהום בין מערכת הטיפוסים של 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 בודדת לא מוכיחה דבר, גיבוי שמרני |
| אובייקט | struct בעל שם | אובייקטים מקוננים הופכים ל-struct משלהם |
אובייקט ריק {} |
map[string]any |
אין שדות ניתנים לצפייה, המחולל לא מנחש |
| מערך | []טיפוסאיבר |
טיפוס האיבר נגזר מהדוגמה הראשונה |
| טיפוסים מעורבים | any |
אין unions ב-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 הפך ל-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:"-," — האחרון אומר שהמפתח באמת נקרא -.
מצביעים: 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, ו-omitempty מדלג עליו רק במקרה הזה. זו הסיבה שרוב הממירים מציעים מתג "השתמש במצביעים לאובייקטים מקוננים": מופעל — מבנים מקוננים הופכים *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 בשדות bool ומספריים צריך להפוך ל-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), הדיוק כבר אבד
שלושה יציאות. הכריזו על שדה ה-struct כ-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 של API צד שלישי — החליטו על הסמנטיקה של nil פעם אחת, כאן;
- קמפלו ובדקו הלוך ושוב: הריצו
go vet, ואז הוסיפו בדיקת הלוך ושוב Marshal→Unmarshal לנעילת הפורמט על החוט — היא תופסת סטיית התנהגות של עדכוני encoding/json עתידיים.
מדוגמה לחוזה: גבול הממיר
ממיר עונה "איך נראית הדוגמה הזאת", לא "איך הממשק הזה תמיד ייראה". כלים מתחרים אומרים זאת בפירוש בתיעוד שלהם עצמם: דוגמה אחת לא יכולה להוכיח וריאציות ייצור — אופציונליות, פורמטי תאריך וערכי enum דורשים עין אנושית. אז בנו הרגל: לפני ההדבקה אספו תשובות שהכי נוטות לחשוף הבדלים (רשימה ריקה, כל השדות, אחת מלאה ב-null); אחרי הייצור התייחסו לפלט כטיוטה, לא כמסירה. אם לממשק יש מסמך חוזה, הפכו את האילוצים למפורשים באמצעות JSON Schema ויישרו את הקוד שנוצר לפיהם — מנצח הסקה מדוגמאות בכמה מדרגות. למבט רוחב על אותה בעיה, הצד ה-Java מכוסה במבחן השדה שלנו למחולל Java, וחוזה ה-frontend בממשקי TypeScript; תהום דיוק המספרים חוזרת בכל שפה בתחפושת אחרת, מפורטת במלכודת המספרים הגדולים של JSON.
אילו שדות עדיין דורשים תיקון ידני אחרי הייצור?
לפחות ארבעה: fallbackים של 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 נשלח למחיקה". במבני תשובה רגילים עם שדות לא nullable, טיפוסים לפי ערך בטוחים יותר — שלמו את מחיר בדיקות ה-nil רק כשההבחנה באמת נחוצה.