JSON en Golang : Marshal, Unmarshal et struct tags

Marshal et Unmarshal

json.Marshal transforme une valeur Go en octets JSON. json.Unmarshal remplit une valeur Go à partir d'octets JSON. Les struct tags choisissent les noms des champs 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 manque dans la première sortie à cause de omitempty et d'une chaîne vide. Unmarshal a besoin d'un pointeur (&back) ; passer la valeur elle-même renvoie une InvalidUnmarshalError.

Struct tags

La syntaxe d'un tag est 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))
}

Le mot de passe ne quitte jamais la struct, le solde est entre guillemets, et deleted_at disparaît alors que created_at affiche l'heure zéro 0001-01-01T00:00:00Z. C'est cette différence qui explique l'ajout de omitzero : omitempty n'a jamais fonctionné pour les structs, et c'est une surprise de longue date avec time.Time. Avec Go 1.23 et avant, utilisez un *time.Time avec omitempty pour obtenir le même effet.

MarshalIndent(v, prefix, indent) produit une sortie lisible. Utilisez-le pour les fichiers de configuration et le débogage ; les API envoient généralement du JSON compact.

Seulement les champs exportés

encoding/json utilise la réflexion et ne voit que les champs exportés. C'est le bug JSON le plus courant en Go :

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

Pas d'erreur, pas d'avertissement, juste {} à la sortie et des champs laissés à zéro à l'entrée. Mettez une majuscule aux champs et ajoutez des tags pour les clés en minuscules.

Comment le décodage fait correspondre les champs

Lors de la désérialisation dans une struct :

• Les clés sont associées au nom du tag, ou au nom du champ, sans tenir compte de la casse. {"NAME": "x"} remplit un champ tagué json:"name".
• Les clés sans champ correspondant sont ignorées sans bruit.
• Les champs sans clé correspondante gardent leur valeur actuelle. Unmarshal ne les réinitialise pas, donc décoder dans une struct qui contient déjà des données les fusionne.
• Une incompatibilité de type (une chaîne là où la struct a un int) renvoie une *json.UnmarshalTypeError, mais les autres champs sont quand même remplis.

Pour refuser des clés inattendues, par exemple dans une API stricte ou un fichier de configuration avec des fautes de frappe, utilisez un Decoder avec 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)
}

Structure inconnue : map[string]any

Quand vous ne connaissez pas la forme à l'avance, décodez dans une map[string]any ou un any. La correspondance est fixe :

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

Deux pièges sont visibles dans la sortie. Chaque nombre est un float64, donc m["stock"].(int) échouerait. Et les entiers au-delà de 2^53 perdent en précision sous forme de float64 : l'identifiant 9007199254740993 revient sous la forme ...992. UseNumber évite les deux.

Si vous connaissez une partie de la structure, décodez cette partie dans une struct et utilisez json.RawMessage pour le reste. Il garde les octets bruts d'un champ pour que vous puissiez le décoder plus tard, une fois son type connu.

Slices, maps, pointeurs et nil

La différence entre slice nil et slice vide compte pour les clients d'API qui attendent un tableau. Initialisez avec []T{} ou make([]T, 0) quand le champ doit valoir [].

Utilisez un champ pointeur (*int, *bool) quand vous devez distinguer « absent » de « zéro » en entrée. Après désérialisation, un pointeur nil signifie que la clé manquait ou valait null ; un pointeur vers 0 signifie que le client a envoyé 0.

Flux : Encoder et Decoder

json.Marshal et Unmarshal travaillent sur des slices d'octets entières. Pour un io.Reader ou un io.Writer (un body HTTP, un fichier, stdin), utilisez json.NewDecoder et json.NewEncoder. Un Decoder peut aussi lire une suite de valeurs JSON une par une :

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 écrit un retour à la ligne après chaque valeur. Par défaut, Marshal comme Encoder échappent <, > et & en \u003c, \u003e et \u0026, pour que le JSON puisse être intégré sans risque dans du HTML. SetEscapeHTML(false) désactive ce comportement. Dans les handlers HTTP, json.NewDecoder(r.Body).Decode(&v) et json.NewEncoder(w).Encode(v) forment la paire habituelle.

Encodage personnalisé

Un type peut contrôler son propre JSON en implémentant json.Marshaler et json.Unmarshaler. Un cas courant est un enum iota qui doit apparaître sous forme de nom, pas de nombre :

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 a un receveur valeur pour fonctionner avec les valeurs comme avec les pointeurs ; UnmarshalJSON a besoin d'un receveur pointeur parce qu'il modifie la valeur. Les types qui n'ont besoin que d'une forme texte peuvent plutôt implémenter encoding.TextMarshaler (MarshalText), ce qui les rend aussi utilisables comme clés de map.

Erreurs courantes

• Des noms de champs en minuscule. Ils sont ignorés sans bruit.
• Passer une valeur à Unmarshal. Il faut un pointeur.
• Ignorer l'erreur. Le JSON mal formé et les incompatibilités de type ne sont signalés que par elle.
• Supposer que les nombres d'une map[string]any sont des int. Ce sont des float64.
• S'attendre à ce que omitempty supprime une struct vide ou un time.Time à zéro. Utilisez omitzero avec Go 1.24, ou un pointeur.
• Compter sur l'ordre des champs dans les maps. Les clés de map sont triées en sortie ; les champs de struct gardent leur ordre de déclaration.