JSON w Golang: Marshal, Unmarshal i tagi struktur

Marshal i Unmarshal

json.Marshal zamienia wartość Go na bajty JSON. json.Unmarshal wypełnia wartość Go na podstawie bajtów JSON. Tagi struktur wybierają nazwy pól w 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)
}

W pierwszym wyniku brakuje Email z powodu omitempty i pustego stringa. Unmarshal potrzebuje wskaźnika (&back); przekazanie samej wartości zwraca InvalidUnmarshalError.

Tagi struktur

Składnia tagu to 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))
}

Hasło nigdy nie opuszcza struktury, saldo jest w cudzysłowie, a deleted_at znika, podczas gdy created_at wypisuje zerowy czas 0001-01-01T00:00:00Z. Z powodu tej różnicy dodano omitzero: omitempty nigdy nie działało dla struktur, a przy time.Time od dawna zaskakuje. W Go 1.23 i starszych ten sam efekt da *time.Time z omitempty.

MarshalIndent(v, prefix, indent) daje czytelny wynik. Używaj go w plikach konfiguracyjnych i przy debugowaniu; API zwykle wysyłają zwarty JSON.

Tylko pola eksportowane

encoding/json korzysta z refleksji i widzi tylko pola eksportowane. To najczęstszy błąd z JSON w Go:

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

Bez błędu, bez ostrzeżenia, po prostu {} na wyjściu i pola z wartościami zerowymi na wejściu. Zmień pierwsze litery pól na wielkie i dodaj tagi dla kluczy pisanych małymi literami.

Jak dekodowanie dopasowuje pola

Przy deserializacji do struktury:

• Klucze są dopasowywane do nazwy z tagu albo do nazwy pola, bez rozróżniania wielkości liter. {"NAME": "x"} wypełnia pole z tagiem json:"name".
• Klucze bez pasującego pola są po cichu ignorowane.
• Pola bez pasującego klucza zachowują obecną wartość. Unmarshal ich nie zeruje, więc dekodowanie do struktury, która ma już dane, scala z nią nowe.
• Niezgodność typów (string tam, gdzie struktura ma int) zwraca *json.UnmarshalTypeError, ale pozostałe pola i tak zostają wypełnione.

Aby odrzucać nieoczekiwane klucze, np. w ścisłym API albo w pliku konfiguracyjnym z literówkami, użyj Decoder z 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)
}

Nieznana struktura: map[string]any

Gdy nie znasz kształtu danych z góry, dekoduj do map[string]any albo any. Odwzorowanie jest stałe:

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)
}

W wyniku widać dwie pułapki. Każda liczba to float64, więc m["stock"].(int) by zawiodło. A liczby całkowite powyżej 2^53 tracą precyzję jako float64: identyfikator 9007199254740993 wraca jako ...992. UseNumber pozwala uniknąć obu problemów.

Jeśli znasz część struktury, zdekoduj tę część do struktury, a dla reszty użyj json.RawMessage. Przechowuje on surowe bajty pola, więc możesz je zdekodować później, gdy poznasz jego typ.

Slice'y, mapy, wskaźniki i nil

Różnica między slice'em nil a pustym ma znaczenie dla klientów API, którzy oczekują tablicy. Inicjalizuj przez []T{} albo make([]T, 0), gdy pole musi być [].

Użyj pola wskaźnikowego (*int, *bool), gdy na wejściu musisz odróżnić „brak” od „zera”. Po deserializacji nilowy wskaźnik oznacza, że klucza nie było albo miał wartość null; wskaźnik na 0 oznacza, że klient wysłał 0.

Strumienie: Encoder i Decoder

json.Marshal i Unmarshal działają na całych slice'ach bajtów. Dla io.Reader albo io.Writer (body HTTP, plik, stdin) użyj json.NewDecoder i json.NewEncoder. Decoder potrafi też czytać ciąg wartości JSON po jednej:

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 dopisuje znak nowej linii po każdej wartości. Domyślnie zarówno Marshal, jak i Encoder zamieniają <, > i & na \u003c, \u003e i \u0026, więc JSON można bezpiecznie osadzić w HTML. SetEscapeHTML(false) to wyłącza. W handlerach HTTP typową parą są json.NewDecoder(r.Body).Decode(&v) i json.NewEncoder(w).Encode(v).

Własne kodowanie

Typ może sam kontrolować swój JSON, implementując json.Marshaler i json.Unmarshaler. Częsty przypadek to enum oparty na iota, który ma się pojawiać jako nazwa, a nie liczba:

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 ma odbiorcę wartościowego, więc działa zarówno dla wartości, jak i wskaźników; UnmarshalJSON potrzebuje odbiorcy wskaźnikowego, bo modyfikuje wartość. Typy, którym wystarczy postać tekstowa, mogą zamiast tego implementować encoding.TextMarshaler (MarshalText), co pozwala też używać ich jako kluczy mapy.

Częste błędy

• Nazwy pól małą literą. Są po cichu pomijane.
• Przekazywanie wartości do Unmarshal. Potrzebny jest wskaźnik.
• Ignorowanie błędu. Tylko przez niego zgłaszany jest błędny JSON i niezgodność typów.
• Zakładanie, że liczby w map[string]any to int. To float64.
• Oczekiwanie, że omitempty pominie pustą strukturę albo zerowe time.Time. Użyj omitzero w Go 1.24 albo wskaźnika.
• Poleganie na kolejności pól w mapach. Klucze mapy są na wyjściu sortowane; pola struktur zachowują kolejność deklaracji.