JSON ב-Golang: Marshal, Unmarshal ו-struct tags

Marshal ו-Unmarshal

json.Marshal הופכת ערך Go לבייטים של JSON. json.Unmarshal ממלאת ערך Go מבייטים של JSON. struct tags קובעים את שמות השדות ב-JSON.

package main

import (
	"encoding/json"
	"fmt"
)

type User struct {
	ID    int      `json:"id"`
	Name  string   `json:"name"`
	Email string   `json:"email,omitempty"`
	Tags  []string `json:"tags"`
}

func main() {
	u := User{ID: 1, Name: "Ada", Tags: []string{"admin"}}

	data, err := json.Marshal(u)
	if err != nil {
		fmt.Println("marshal:", err)
		return
	}
	fmt.Println(string(data))

	var back User
	input := []byte(`{"id": 2, "name": "Linus", "email": "l@example.com", "tags": ["kernel", "git"]}`)
	if err := json.Unmarshal(input, &back); err != nil {
		fmt.Println("unmarshal:", err)
		return
	}
	fmt.Printf("%+v\n", back)
}

Email חסר בפלט הראשון בגלל omitempty ומחרוזת ריקה. Unmarshal צריכה pointer (&back); העברה של הערך עצמו מחזירה InvalidUnmarshalError.

Struct tags

התחביר של tag הוא json:"name,option,option".

package main

import (
	"encoding/json"
	"fmt"
	"time"
)

type Account struct {
	ID        int       `json:"id"`
	Password  string    `json:"-"`
	Nickname  string    `json:"nickname,omitempty"`
	Balance   int64     `json:"balance,string"`
	CreatedAt time.Time `json:"created_at,omitempty"` // omitempty never omits a struct
	DeletedAt time.Time `json:"deleted_at,omitzero"`  // Go 1.24: omitted when zero
	internal  string    // unexported: always ignored
}

func main() {
	a := Account{ID: 7, Password: "hunter2", Balance: 1500, internal: "x"}
	out, err := json.MarshalIndent(a, "", "  ")
	if err != nil {
		fmt.Println(err)
		return
	}
	fmt.Println(string(out))
}

הסיסמה אף פעם לא יוצאת מה-struct, היתרה מופיעה במירכאות, ו-deleted_at נעלם בזמן ש-created_at מדפיס את זמן האפס 0001-01-01T00:00:00Z. ההבדל הזה הוא הסיבה שנוסף omitzero: omitempty אף פעם לא עבד על structs, וזו הפתעה ותיקה עם time.Time. ב-Go 1.23 ומטה, השתמשו ב-*time.Time עם omitempty כדי לקבל את אותה תוצאה.

MarshalIndent(v, prefix, indent) מייצרת פלט קריא. השתמשו בה לקובצי הגדרות ולדיבאג; APIs בדרך כלל שולחים JSON דחוס.

רק שדות מיוצאים

encoding/json משתמשת ב-reflection ויכולה לראות רק שדות מיוצאים. זה באג ה-JSON הנפוץ ביותר ב-Go:

type point struct {
	x, y int // lowercase: json.Marshal(point{1, 2}) gives {}
}

בלי שגיאה, בלי אזהרה, רק {} ביציאה ושדות שנשארים באפס בכניסה. כתבו את השדות באות גדולה והוסיפו tags למפתחות באותיות קטנות.

איך הפענוח מתאים שדות

כשעושים unmarshal לתוך struct:

• מפתחות מותאמים לשם ב-tag, או לשם השדה, בלי הבחנה בין אותיות גדולות לקטנות. {"NAME": "x"} ממלא שדה עם tag json:"name".
• מפתחות בלי שדה מתאים מתעלמים מהם בשקט.
• שדות בלי מפתח מתאים שומרים על הערך הנוכחי שלהם. Unmarshal לא מאפסת אותם, כך שפענוח לתוך struct שכבר יש בו נתונים ממזג לתוכו.
• אי התאמה בטיפוס (מחרוזת במקום שבו ב-struct יש int) מחזירה *json.UnmarshalTypeError, אבל שאר השדות עדיין מתמלאים.

כדי לדחות מפתחות לא צפויים, למשל ב-API קפדני או בקובץ הגדרות עם שגיאות כתיב, השתמשו ב-Decoder עם DisallowUnknownFields:

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

type Config struct {
	Port  int  `json:"port"`
	Debug bool `json:"debug"`
}

func main() {
	input := `{"port": 8080, "debgu": true}` // typo in "debug"

	var lenient Config
	err := json.Unmarshal([]byte(input), &lenient)
	fmt.Printf("Unmarshal: %+v, err=%v\n", lenient, err)

	var strict Config
	dec := json.NewDecoder(strings.NewReader(input))
	dec.DisallowUnknownFields()
	err = dec.Decode(&strict)
	fmt.Println("Decoder:", err)

	var typed Config
	err = json.Unmarshal([]byte(`{"port": "8080"}`), &typed)
	fmt.Println("type mismatch:", err)
}

מבנה לא ידוע: map[string]any

כשלא יודעים את המבנה מראש, פענחו לתוך map[string]any או any. המיפוי קבוע:

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

func main() {
	input := `{"name": "widget", "price": 9.5, "stock": 3, "tags": ["a", "b"], "meta": {"id": 9007199254740993}}`

	var m map[string]any
	if err := json.Unmarshal([]byte(input), &m); err != nil {
		fmt.Println(err)
		return
	}

	name, _ := m["name"].(string)
	stock, _ := m["stock"].(float64) // numbers are float64, even 3
	tags, _ := m["tags"].([]any)
	fmt.Println(name, int(stock), len(tags))

	meta := m["meta"].(map[string]any)
	fmt.Printf("id as float64: %.0f\n", meta["id"]) // precision lost

	// UseNumber keeps numbers as json.Number (a string) for exact handling.
	dec := json.NewDecoder(strings.NewReader(input))
	dec.UseNumber()
	var exact map[string]any
	if err := dec.Decode(&exact); err != nil {
		fmt.Println(err)
		return
	}
	id, err := exact["meta"].(map[string]any)["id"].(json.Number).Int64()
	fmt.Println("id with UseNumber:", id, err)
}

שתי מלכודות נראות בפלט. כל מספר הוא float64, ולכן m["stock"].(int) הייתה נכשלת. ומספרים שלמים מעל 2^53 מאבדים דיוק כ-float64: ה-id 9007199254740993 חוזר כ-...992. UseNumber מונעת את שתיהן.

אם אתם מכירים חלק מהמבנה, פענחו את החלק הזה לתוך struct והשתמשו ב-json.RawMessage לשאר. הוא מחזיק את הבייטים הגולמיים של שדה, כך שאפשר לפענח אותו מאוחר יותר, כשיודעים את הטיפוס שלו.

Slices, maps, pointers ו-nil

ההבדל בין slice שהוא nil ל-slice ריק חשוב ללקוחות API שמצפים למערך. אתחלו עם []T{} או make([]T, 0) כשהשדה חייב להיות [].

השתמשו בשדה pointer (*int, *bool) כשצריך להבחין בין "חסר" ל"אפס" בקלט. אחרי unmarshal, pointer שהוא nil אומר שהמפתח היה חסר או null; pointer ל-0 אומר שהלקוח שלח 0.

Streams: Encoder ו-Decoder

json.Marshal ו-Unmarshal עובדות על slices שלמים של בייטים. ל-io.Reader או ל-io.Writer (body של HTTP, קובץ, stdin), השתמשו ב-json.NewDecoder וב-json.NewEncoder. Decoder יכול גם לקרוא רצף של ערכי JSON אחד אחרי השני:

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"os"
	"strings"
)

type Event struct {
	Type string `json:"type"`
	N    int    `json:"n"`
}

func main() {
	// Newline-delimited JSON, as in log files and many streaming APIs.
	stream := `{"type":"click","n":1}
{"type":"view","n":2}
{"type":"click","n":3}`

	dec := json.NewDecoder(strings.NewReader(stream))
	clicks := 0
	for {
		var e Event
		err := dec.Decode(&e)
		if errors.Is(err, io.EOF) {
			break
		}
		if err != nil {
			fmt.Println("decode:", err)
			return
		}
		if e.Type == "click" {
			clicks++
		}
	}
	fmt.Println("clicks:", clicks)

	enc := json.NewEncoder(os.Stdout)
	enc.SetEscapeHTML(false) // keep <, > and & readable
	enc.SetIndent("", "  ")
	if err := enc.Encode(map[string]any{"clicks": clicks, "note": "a < b & c"}); err != nil {
		fmt.Println("encode:", err)
	}
}

Encoder.Encode כותבת שורה חדשה אחרי כל ערך. כברירת מחדל גם Marshal וגם Encoder מבצעים escape ל-<, ל-> ול-& כ-\u003c, \u003e ו-\u0026, כך שבטוח להטמיע את ה-JSON ב-HTML. SetEscapeHTML(false) מכבה את זה. ב-handlers של HTTP, json.NewDecoder(r.Body).Decode(&v) ו-json.NewEncoder(w).Encode(v) הם הצמד הרגיל.

קידוד מותאם אישית

טיפוס יכול לשלוט ב-JSON שלו בעצמו על ידי מימוש json.Marshaler ו-json.Unmarshaler. מקרה נפוץ הוא enum עם iota שצריך להופיע כשם ולא כמספר:

package main

import (
	"encoding/json"
	"fmt"
	"strings"
)

type Level int

const (
	Low Level = iota
	High
)

var levelNames = []string{"low", "high"}

func (l Level) MarshalJSON() ([]byte, error) {
	return json.Marshal(levelNames[l])
}

func (l *Level) UnmarshalJSON(b []byte) error {
	var s string
	if err := json.Unmarshal(b, &s); err != nil {
		return err
	}
	for i, name := range levelNames {
		if strings.EqualFold(s, name) {
			*l = Level(i)
			return nil
		}
	}
	return fmt.Errorf("unknown level %q", s)
}

type Alert struct {
	Msg   string `json:"msg"`
	Level Level  `json:"level"`
}

func main() {
	out, _ := json.Marshal(Alert{Msg: "disk full", Level: High})
	fmt.Println(string(out))

	var a Alert
	err := json.Unmarshal([]byte(`{"msg":"cpu","level":"LOW"}`), &a)
	fmt.Printf("%+v %v\n", a, err)

	err = json.Unmarshal([]byte(`{"msg":"cpu","level":"urgent"}`), &a)
	fmt.Println(err)
}

ל-MarshalJSON יש value receiver, כך שהיא עובדת גם לערכים וגם ל-pointers; UnmarshalJSON צריכה pointer receiver כי היא משנה את הערך. טיפוסים שצריכים רק צורת מחרוזת יכולים לממש במקום זה את encoding.TextMarshaler (MarshalText), וזה גם מאפשר להשתמש בהם כמפתחות של map.

טעויות נפוצות

• שמות שדות באותיות קטנות. מדלגים עליהם בשקט.
• העברת ערך ל-Unmarshal. היא צריכה pointer.
• התעלמות מהשגיאה. JSON פגום ואי התאמות בטיפוסים מדווחים רק דרכה.
• הנחה שמספרים ב-map[string]any הם int. הם float64.
• ציפייה ש-omitempty ישמיט struct ריק או time.Time באפס. השתמשו ב-omitzero ב-Go 1.24, או ב-pointer.
• הסתמכות על סדר השדות ב-maps. מפתחות של map ממוינים בפלט; שדות של struct שומרים על סדר ההצהרה שלהם.