JSON Toolkit

JSON ל-Go Struct: המחולל מסור את השלד, ארבעה דברים דורשים את הידיים שלכם

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

בינוניכ-6 דקות קריאהפורסם 2026-11-22עודכן 2026-11-22
המרת דוגמת JSON לקוד struct של Go באמצעות כלי מקוון

מסקנה תחילה: המבנים שממיר מייצר בעשר שניות מתקמפלים, אבל לא מוכנים לייצור. המחולל מתאר רק את הדוגמה היחידה שהדבקתם — מספרים הופכים ל-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
}

רשימת בדיקה בת ארבעה שלבים אחרי הייצור

ארבעה שלבים מפרידים את פלט המחולל מקוד ייצור, ומעבר אחד עליהם זול יותר מדיבוג אחר כך:

  1. החליפו כל fallback של any: חפשו any, עברו על שלוש עד חמש דוגמאות אמיתיות לכל שדה שנופל לגיבוי ואז הנחיתו על טיפוס מוחשי או מצביע;
  2. בדקו שוב את רוחבי המספרים: העבירו מזהים, סכומים ומונים מ-float64 ל-int64 / int32 / decimal; בספק לגבי הרוחב, כתבו int64;
  3. סמנו אופציונליות: מצביעים או omitempty/omitzero לשדות אובייקטים במערכים, גופי PATCH ושדות nullable של API צד שלישי — החליטו על הסמנטיקה של nil פעם אחת, כאן;
  4. קמפלו ובדקו הלוך ושוב: הריצו 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 רק כשההבחנה באמת נחוצה.