JSON de Produção

type Account struct {
	Name   string `json:"display_name"` // fixa o nome externo
	Secret string `json:"-"`            // nunca cruza a fronteira
	Age    int    `json:"age,omitempty"` // zero desaparece
	ID     int64  `json:"id,string"`     // número sai entre aspas
}
account := Account{Name: "Ana", Secret: "token", ID: 42}
data, _ := json.Marshal(account) // aplica o contrato das tags

Quando uma struct atravessa a fronteira de uma API, os nomes dos campos exportados deixam de ser apenas detalhe interno. Sem tags, DisplayName vira DisplayName; um refactor inocente pode alterar o documento enviado a clientes. Pense na struct como o cadastro completo e no JSON como a etiqueta colada do lado de fora da caixa. A etiqueta publica só o contrato necessário.

Tags são metadados lidos por reflexão. O pacote encoding/json procura a chave json e interpreta nome e opções separados por vírgula. json:"display_name" fixa o nome externo. json:"-" proíbe o campo na codificação e o ignora na decodificação. omitempty retira a propriedade quando o valor está vazio segundo as regras do encoder.

O risco mais sério é confundir ausência com zero. Para um int, zero ativa omitempty; para um bool, false; para string, ""; para slices e maps, comprimento zero; para ponteiros e interfaces, nil. Se "não informado" e zero são estados diferentes, um *int torna essa diferença explícita: nil significa ausência e um ponteiro para zero significa presença.

A opção string é um acordo de representação, não uma conversão permissiva. Em um campo ID int64 com a tag json:"id,string", o encoder produz um número dentro de aspas e o decoder exige essa forma. Isso ajuda contratos legados e inteiros que consumidores tratam como texto, mas deve ser documentado: enviar um número JSON normal passa a ser erro.

Leia o fluxo como uma sequência de contratos. Primeiro, bytes entram sem confiança. Depois, o pacote padrão transforma representação em valores Go. Só então o domínio decide se esses valores podem continuar. Essa ordem evita atribuir ao parser uma regra que pertence ao negócio e evita validar texto manualmente quando o decoder já conhece a gramática.

No exemplo desta aula, campos publicados, omitidos e codificados como texto. Observe o que não acontece: não montamos JSON por concatenação, não procuramos campos com expressões regulares e não aceitamos silenciosamente qualquer forma conveniente. Cada atalho desses cria uma segunda implementação parcial do formato. encoding/json já resolve escapes, Unicode, números e delimitadores; seu código deve concentrar a política específica.

Uma boa fronteira também limita recursos. Mesmo em programas didáticos, pense em tamanho máximo do corpo, profundidade esperada, número de registros e destino dos erros. O pacote não substitui limites impostos pelo transporte. Em um servidor, http.MaxBytesReader pode restringir o corpo antes do decode. Em um pipeline, um reader limitado ou o tamanho máximo do scanner cumpre papel semelhante.