JSON Toolkit

JSON para Go Struct: o gerador entrega o esqueleto, estas quatro coisas exigem suas mãos

Resumo: Cole uma amostra de resposta de API no conversor e em dez segundos você tem structs Go com tags — mas números viram float64, campos opcionais nunca se tornam ponteiros por conta própria, omitempty não remove structs vazios e a maioria das datas continua como string. Tabela completa de mapeamento, o equilíbrio entre ponteiro e omitzero e uma lista de verificação de quatro passos para finalizar o código gerado.

Intermediário~6 min de leituraPublicado em 2026-11-22Atualizado em 2026-11-22
Convertendo uma amostra JSON em código de struct Go com uma ferramenta online

Conclusão primeiro: os structs que um conversor produz em dez segundos compilam, mas não estão prontos para produção. O gerador descreve apenas a única amostra que você colou — números viram float64, campos opcionais nunca se tornam ponteiros sozinhos, omitempty não derruba structs vazios, e a maioria das strings de data continua strings. Essas quatro lacunas continuam sendo trabalho seu depois de colar.

Transformar uma resposta de API em structs Go é trabalho puramente mecânico, e o custo do trabalho mecânico se esconde no silêncio: um nome de campo escrito errado não gera erro de compilação, apenas um campo que fica em zero para sempre; um interruptor errado no tratamento de null e um "note": null aparece em produção onde ninguém esperava. A geração de structs resolve o alinhamento de nomes e tipos, mas duas coisas nunca se alinham sozinhas: as variações fora da sua amostra e o fosso entre o sistema de tipos de Go e o de JSON.

O que o gerador realmente lê: uma tabela de mapeamento

Todo conversor JSON → Go roda sobre a mesma tabela. Passe uma resposta típica de pedido pela página /convert/go deste site — cole a amostra, ative as tags json — e você recebe esta forma:

Valor JSON Tipo Go gerado Observações
string string Strings de data normalmente continuam strings, veja time.Time abaixo
inteiro float64 encoding/json analisa números internamente como double
decimal float64 Troque campos monetários por biblioteca decimal ou int64 em unidades menores
true / false bool Sem armadilhas
null any Uma única amostra null não prova nada, fallback conservador
objeto struct nomeado Objetos aninhados viram seu próprio struct
objeto vazio {} map[string]any Nenhum campo observável, o gerador não adivinha
array []TipoElemento Tipo do elemento inferido da primeira amostra
tipos mistos any Go não tem uniões, campos com múltiplos tipos recuam para any
// Amostra de entrada
// {"id":"A-1029","items":[{"sku":"J-01","qty":2}],"coupon":null}
type Root struct {
  ID     string `json:"id"`
  Items  []Item `json:"items"`
  Coupon any    `json:"coupon"`
}

type Item struct {
  Sku string `json:"sku"`
  Qty int    `json:"qty"`
}

Três observações. O objeto aninhado items virou seu próprio struct Item referenciado por um slice. coupon só apareceu como null: o gerador não pode provar o que será depois e recua para any. O número qty aterrissa como int ou float64 dependendo da ferramenta — as estratégias diferem, mas todas se apoiam na mesma suposição: a amostra é toda a verdade.

Tags json: nomes originais, opções e três erros fáceis

As tags carregam a maior densidade de informação na saída do gerador e também são a parte mais fácil de errar ao ajustar. As regras vêm direto da documentação do encoding/json:

Field int `json:"myName"`            // aparece sob a chave myName
Field int `json:"myName,omitempty"`  // campo inteiro omitido quando vazio
Field int `json:",omitempty"`        // nome de campo padrão, apenas a opção
Field int `json:"-"`                 // sempre ignorado, sem codificar nem decodificar
Field int64 `json:"id,string"`       // número codificado dentro de uma string

Três descuidos que valem memorizar. Primeiro, a vírgula inicial em json:",omitempty" — quando você quer apenas pular valores vazios sem renomear a chave, a vírgula é obrigatória; sem ela, o campo é tratado como uma chave literalmente chamada ,omitempty. Segundo, mantenha a chave JSON original na tag (user_id, html_url) enquanto o campo Go usa a convenção idiomática (UserID, HTMLURL): sem tag, a correspondência usa o nome do campo literalmente, então uma chave userId na resposta nunca mapeia, silenciosamente. Terceiro, além de json:"-" existe json:"-," — este último significa que a chave realmente se chama -.

Ponteiros: nil é a única forma de distinguir "ausente" de "zero"

O sistema de valores zero de Go impede que int e string expressem "campo não presente" — 0 e "" podem ser dados reais ou apenas não parseados. A mesma chave JSON tem três estados: presente com valor, presente como null e ausente. Tipos por valor cobrem apenas o primeiro.

type Config struct {
  Note    string  `json:"note,omitempty"`   // omitido apenas quando exatamente ""
  Alias   *string `json:"alias,omitempty"`  // omitido quando nil
  Details *Meta   `json:"details,omitempty"`
}

O valor zero de um campo ponteiro é nil. json.Unmarshal o deixa nil quando a chave falta ou é null, e omitempty o pula só nesse caso. É por isso que a maioria dos conversores oferece um interruptor "usar ponteiros para objetos aninhados": ativado, structs aninhados viram *Item, e em uma requisição PATCH "campo não enviado" e "null enviado para deletar" finalmente se separam. O preço são checagens de nil por toda parte — p.Address.Street entra em pânico quando Address é nil, um dos crashes de runtime mais comuns em código JSON em Go.

O struct vazio que omitempty não consegue derrubar, e o buraco que omitzero preenche

A definição oficial de omitempty julga valores: false, 0, ponteiros nil, interfaces nil e arrays, slices, maps ou strings de comprimento zero. Note o que não está na lista: structs vazios.

type Order struct {
  Meta Meta `json:"meta,omitempty"`
}
type Meta struct {
  Version string
  Build   int
}

// Meta{Version: "1.0"} → "meta":{"version":"1.0","build":0}
// Meta{}              → "meta":{}   ← omitempty não fez nada

Um campo struct nunca é omitido pelo omitempty — ele vive na memória como um contêiner de tamanho fixo, e um contêiner existente não é "vazio". A correção é transformar o campo em *Meta; apenas um ponteiro nil é descartado. Desde o Go 1.24 existe um segundo interruptor, omitzero: julgado pelo valor zero de Go, chamando IsZero() bool quando o tipo o define — a única forma de omitir um time.Time zero. Com encoding/json/v2 (experimental no Go 1.25) a semântica desloca de novo: o omitempty do v2 julga o resultado JSON codificado (apenas null, "", {}, [] contam como vazio), então count: 0 permanece na saída; ao migrar código antigo, o omitempty em campos bool e numéricos precisa virar omitzero para manter o significado original.

Todo número vira float64: a armadilha dos inteiros grandes

Sem tipo explícito, o decoder do encoding/json trata números como float64, e float64 tem apenas 53 bits de mantissa. O caso clássico do JavaScript — 9007199254740993 virando 9007199254740992 — existe em Go também, desde que o campo alvo seja float64 ou any.

var v map[string]any
_ = json.Unmarshal([]byte(`{"id":9007199254740993}`), &v)
// v["id"] é float64(9007199254740992), precisão já perdida

Três saídas. Declare o campo do struct como int64 e o decoder analisa exatamente nele. Quando precisar passar por any, chame decoder.UseNumber() para que os números aterrissem como strings json.Number que você converte deliberadamente. Nunca use ponto flutuante para dinheiro — guarde unidades menores em int64 ou use uma biblioteca decimal. Sempre que uma API retorna IDs snowflake ou números de pedido de 64 bits, esta seção é checagem obrigatória.

time.Time aceita apenas RFC 3339

Diante de "2024-01-15T10:30:00Z" um gerador mapeia time.Time; diante de "2024-01-15 10:30:00" deixa uma string. Não é preguiça — é uma restrição dura do encoding/json: time.Time implementa UnmarshalJSON e faz o parse estritamente no layout RFC 3339 2006-01-02T15:04:05Z07:00. T faltando, fuso faltando ou um Z seguido de offset todos falham:

parsing time "\"2022-07-27T14:16:00Z04:00\"" as
"\"2006-01-02T15:04:05Z07:00\"": cannot parse "04:00\"" as "\""

Quando o formato de upstream não pode mudar, a correção padrão é um tipo personalizado envolvendo time.Time cujo UnmarshalJSON tenta vários layouts:

type CustomDate struct{ time.Time }

func (c *CustomDate) UnmarshalJSON(b []byte) error {
  s := strings.Trim(string(b), `"`)
  t, err := time.Parse("2006-01-02 15:04:05", s)
  if err != nil {
    t, err = time.Parse(time.RFC3339, s)
    if err != nil {
      return fmt.Errorf("invalid date format: %w", err)
    }
  }
  c.Time = t
  return nil
}

A lista de verificação de quatro passos depois de gerar

Quatro passos separam a saída do gerador do código de produção, e percorrê-los uma vez custa menos que depurar depois:

  1. Substitua cada fallback any: procure any, revise três a cinco amostras reais por campo em fallback e então aterrisse em um tipo concreto ou ponteiro;
  2. Reverifique as larguras numéricas: mova IDs, valores e contadores de float64 para int64 / int32 / decimal; em caso de dúvida sobre a largura, escreva int64;
  3. Marque a opcionalidade: ponteiros ou omitempty/omitzero para campos de objetos em arrays, corpos de PATCH e campos anuláveis de APIs de terceiros — decida a semântica de nil uma vez, aqui;
  4. Compile e teste a ida e volta: rode go vet, depois adicione um teste de ida e volta Marshal→Unmarshal para travar o formato de fio — isso pega a deriva de comportamento de futuras atualizações do encoding/json.

Da amostra ao contrato: a fronteira do conversor

Um conversor responde "como esta amostra se parece", não "como esta interface sempre se parecerá". Ferramentas concorrentes dizem isso francamente em suas próprias documentações: uma amostra não pode provar variações de produção — opcionalidade, formatos de data e valores de enumeração exigem revisão humana. Então construa o hábito: antes de colar, reúna as respostas mais propensas a expor diferenças (lista vazia, todos os campos, uma com nulls); depois de gerar, trate a saída como rascunho, não como entrega. Se a interface tem um documento de contrato, torne as restrições explícitas com JSON Schema e alinhe o código gerado a ele — isso vence a inferência a partir de amostras por uma ordem de grandeza. Para a visão transversal do mesmo problema, o lado Java está coberto no nosso teste de campo do gerador Java, o contrato de frontend nas interfaces TypeScript; o fosso de precisão numérica reaparece em cada linguagem com outra fantasia, detalhado na armadilha de números grandes do JSON.

Quais campos ainda precisam de revisão manual depois de gerar?

Pelo menos quatro: fallbacks any, larguras numéricas (float64 → int64), tornar ponteiros os campos opcionais e se os campos de data devem ser string ou time.Time. Todos os quatro são variações de produção invisíveis na amostra; o gerador não adivinha, o humano precisa completar.

Por que meu campo ainda aparece no JSON depois de adicionar omitempty?

omitempty só pula valores zero: false, 0, "", nil, slices vazias. Um struct vazio {} não é um valor zero, então sobrevive — transforme o campo em ponteiro. Um time.Time zero precisa de omitzero, não de omitempty.

Por que meu ID inteiro grande mudou depois da desserialização?

Sem tipo explícito, encoding/json faz o parse de números como float64, que carrega 53 bits de mantissa; inteiros além de 2^53 perdem precisão. Tipifique o campo como int64, ou chame UseNumber() para manter números como json.Number.

Quando um campo de objeto aninhado deve ser ponteiro?

Dois casos: o campo pode estar ausente ou ser null (nil separa "não enviado" de "valor zero"), e uma requisição PATCH precisa distinguir "não enviado" de "null enviado para deletar". Em structs de resposta comuns com campos não anuláveis, tipos por valor são mais seguros — pague o custo das checagens de nil apenas quando realmente precisar da distinção.

Referências

Artigos relacionados

JSON para classe Java: o gerador entrega o esqueleto, a produção exige mais cinco coisas

Um olhar prático sobre o que um gerador JSON → Java realmente emite——números viram Double, objetos aninhados viram classes internas estáticas, e nenhuma anotação Jackson é gerada. Precisão monetária, renomeação de campos, apagamento de genéricos, campos desconhecidos e datas são as cinco coisas que você mesmo precisa adicionar, com código pronto para copiar em cada caso.

Intermediário~10 min de leituraAtualizado em 2026-11-04

Por que inteiros grandes perdem precisão

Inteiros acima de 2^53-1 perdem precisão no JSON.parse. IDs snowflake, números de pedido e bigints de banco de dados todos esbarram nisso, então mantenha-os como strings de ponta a ponta.

Intermediário~4 min de leituraAtualizado em 2026-11-04