JSON in Golang: Marshal, Unmarshal e struct tag

Marshal e Unmarshal

json.Marshal trasforma un valore Go in byte JSON. json.Unmarshal riempie un valore Go a partire da byte JSON. Gli struct tag scelgono i nomi dei campi 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 manca nel primo output per via di omitempty e di una stringa vuota. Unmarshal ha bisogno di un puntatore (&back); passare il valore stesso restituisce un InvalidUnmarshalError.

Struct tag

La sintassi del 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))
}

La password non esce mai dalla struct, il saldo è tra virgolette, e deleted_at sparisce mentre created_at stampa il tempo zero 0001-01-01T00:00:00Z. Questa differenza è il motivo per cui è stato aggiunto omitzero: omitempty non ha mai funzionato con le struct, ed è una sorpresa di lunga data con time.Time. Su Go 1.23 e precedenti, usa un *time.Time con omitempty per ottenere lo stesso effetto.

MarshalIndent(v, prefix, indent) produce un output leggibile. Usalo per i file di configurazione e il debug; le API di solito inviano JSON compatto.

Solo campi esportati

encoding/json usa la reflection e può vedere solo i campi esportati. È il bug JSON più comune in Go:

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

Nessun errore, nessun avviso, solo {} in uscita e campi lasciati a zero in entrata. Metti la maiuscola ai campi e aggiungi i tag per le chiavi in minuscolo.

Come la decodifica abbina i campi

Quando fai l'unmarshal in una struct:

• Le chiavi vengono abbinate al nome del tag, o al nome del campo, senza distinguere maiuscole e minuscole. {"NAME": "x"} riempie un campo con tag json:"name".
• Le chiavi senza un campo corrispondente vengono ignorate senza avvisi.
• I campi senza una chiave corrispondente mantengono il loro valore attuale. Unmarshal non li azzera, quindi decodificare in una struct che contiene già dati li unisce.
• Un tipo non corrispondente (una stringa dove la struct ha un int) restituisce un *json.UnmarshalTypeError, ma gli altri campi vengono comunque riempiti.

Per rifiutare chiavi inattese, per esempio in una API rigorosa o in un file di configurazione con errori di battitura, usa un Decoder con 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)
}

Struttura sconosciuta: map[string]any

Quando non conosci la forma in anticipo, decodifica in map[string]any o in any. La corrispondenza è fissa:

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

Nell'output si vedono due trappole. Ogni numero è float64, quindi m["stock"].(int) fallirebbe. E gli interi sopra 2^53 perdono precisione come float64: l'id 9007199254740993 torna indietro come ...992. UseNumber evita entrambe.

Se conosci una parte della struttura, decodifica quella parte in una struct e usa json.RawMessage per il resto. Contiene i byte grezzi di un campo così puoi decodificarlo più tardi, quando ne conosci il tipo.

Slice, map, puntatori e nil

La differenza tra slice nil e slice vuota conta per i client di una API che si aspettano un array. Inizializza con []T{} o make([]T, 0) quando il campo deve essere [].

Usa un campo puntatore (*int, *bool) quando in input devi distinguere "assente" da "zero". Dopo l'unmarshal, un puntatore nil significa che la chiave mancava o era null; un puntatore a 0 significa che il client ha inviato 0.

Stream: Encoder e Decoder

json.Marshal e Unmarshal lavorano su slice di byte intere. Per un io.Reader o un io.Writer (un body HTTP, un file, stdin), usa json.NewDecoder e json.NewEncoder. Un Decoder può anche leggere una sequenza di valori JSON uno alla volta:

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 scrive un a capo finale dopo ogni valore. Per default sia Marshal sia Encoder fanno l'escape di <, > e & come \u003c, \u003e e \u0026, così il JSON si può incorporare in sicurezza nell'HTML. SetEscapeHTML(false) lo disattiva. Negli handler HTTP, json.NewDecoder(r.Body).Decode(&v) e json.NewEncoder(w).Encode(v) sono la coppia abituale.

Codifica personalizzata

Un tipo può controllare il proprio JSON implementando json.Marshaler e json.Unmarshaler. Un caso comune è un enum con iota che deve comparire come nome, non come numero:

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 ha un receiver valore così funziona sia per i valori sia per i puntatori; UnmarshalJSON ha bisogno di un receiver puntatore perché modifica il valore. I tipi che hanno bisogno solo di una forma testuale possono implementare invece encoding.TextMarshaler (MarshalText), che li rende utilizzabili anche come chiavi di una map.

Errori comuni

• Nomi di campo in minuscolo. Vengono saltati senza avvisi.
• Passare un valore a Unmarshal. Serve un puntatore.
• Ignorare l'errore. Il JSON malformato e i tipi non corrispondenti vengono segnalati solo attraverso l'errore.
• Dare per scontato che i numeri in map[string]any siano int. Sono float64.
• Aspettarsi che omitempty escluda una struct vuota o un time.Time a zero. Usa omitzero su Go 1.24, oppure un puntatore.
• Contare sull'ordine dei campi nelle map. Le chiavi delle map vengono ordinate in output; i campi delle struct mantengono l'ordine di dichiarazione.