JSON em Golang: Marshal, Unmarshal e struct tags

Marshal e Unmarshal

json.Marshal transforma um valor Go em bytes JSON. json.Unmarshal preenche um valor Go a partir de bytes JSON. As struct tags escolhem os nomes dos campos no 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 falta na primeira saída por causa do omitempty e de uma string vazia. O Unmarshal precisa de um ponteiro (&back); passar o próprio valor devolve um InvalidUnmarshalError.

Struct tags

A sintaxe da tag é json:"nome,opção,opção".

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

A senha nunca sai da struct, o saldo sai entre aspas, e deleted_at some enquanto created_at imprime o tempo zero 0001-01-01T00:00:00Z. Essa diferença é o motivo de o omitzero ter sido criado: o omitempty nunca funcionou para structs, e isso é uma surpresa antiga com time.Time. No Go 1.23 e anteriores, use um *time.Time com omitempty para ter o mesmo efeito.

MarshalIndent(v, prefix, indent) gera uma saída legível. Use para arquivos de configuração e depuração; APIs costumam enviar JSON compacto.

Só campos exportados

O encoding/json usa reflection e só enxerga campos exportados. Este é o bug de JSON mais comum em Go:

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

Nenhum erro, nenhum aviso, só {} na saída e campos que continuam zerados na entrada. Coloque os campos em maiúscula e acrescente tags para chaves em minúscula.

Como a decodificação casa os campos

No unmarshal para uma struct:

• As chaves são casadas com o nome da tag, ou com o nome do campo, sem diferenciar maiúsculas de minúsculas. {"NAME": "x"} preenche um campo com a tag json:"name".
• Chaves sem campo correspondente são ignoradas em silêncio.
• Campos sem chave correspondente mantêm o valor atual. O Unmarshal não os zera, então decodificar em uma struct que já tem dados mescla com eles.
• Um tipo incompatível (uma string onde a struct tem um int) devolve um *json.UnmarshalTypeError, mas os outros campos ainda são preenchidos.

Para rejeitar chaves inesperadas, por exemplo em uma API estrita ou em um arquivo de configuração com erros de digitação, use um Decoder com 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)
}

Estrutura desconhecida: map[string]any

Quando você não conhece o formato de antemão, decodifique em map[string]any ou any. O mapeamento é fixo:

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

Duas armadilhas aparecem na saída. Todo número é float64, então m["stock"].(int) falharia. E inteiros acima de 2^53 perdem precisão como float64: o id 9007199254740993 volta como ...992. O UseNumber evita as duas.

Se você conhece parte da estrutura, decodifique essa parte em uma struct e use json.RawMessage para o resto. Ele guarda os bytes brutos de um campo para você decodificá-lo depois, quando souber o tipo.

Slices, maps, ponteiros e nil

A diferença entre slice nil e vazio importa para clientes de API que esperam um array. Inicialize com []T{} ou make([]T, 0) quando o campo precisar ser [].

Use um campo ponteiro (*int, *bool) quando precisar diferenciar "ausente" de "zero" na entrada. Depois do unmarshal, um ponteiro nil significa que a chave faltava ou era null; um ponteiro para 0 significa que o cliente enviou 0.

Fluxos: Encoder e Decoder

json.Marshal e Unmarshal trabalham com slices de bytes inteiros. Para um io.Reader ou io.Writer (um corpo HTTP, um arquivo, o stdin), use json.NewDecoder e json.NewEncoder. Um Decoder também consegue ler uma sequência de valores JSON, um de cada vez:

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

O Encoder.Encode escreve uma quebra de linha depois de cada valor. Por padrão, tanto o Marshal quanto o Encoder escapam <, > e & como \u003c, \u003e e \u0026, para que o JSON possa ser embutido com segurança em HTML. SetEscapeHTML(false) desliga isso. Em handlers HTTP, json.NewDecoder(r.Body).Decode(&v) e json.NewEncoder(w).Encode(v) são a dupla de sempre.

Codificação personalizada

Um tipo pode controlar o próprio JSON implementando json.Marshaler e json.Unmarshaler. Um caso comum é um enum com iota que deve aparecer como nome, não como número:

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 tem receiver de valor, então funciona tanto para valores quanto para ponteiros; UnmarshalJSON precisa de receiver ponteiro porque modifica o valor. Tipos que só precisam de uma forma em string podem implementar encoding.TextMarshaler (MarshalText), o que também permite usá-los como chaves de map.

Erros comuns

• Nomes de campo em minúscula. Eles são pulados em silêncio.
• Passar um valor para o Unmarshal. Ele precisa de um ponteiro.
• Ignorar o erro. JSON malformado e tipos incompatíveis só são reportados por meio dele.
• Supor que os números em map[string]any são int. Eles são float64.
• Esperar que o omitempty descarte uma struct vazia ou um time.Time zero. Use omitzero no Go 1.24, ou um ponteiro.
• Depender da ordem dos campos em maps. As chaves de map saem ordenadas; os campos de struct mantêm a ordem de declaração.