O que é encoding/json/v2

O encoding/json/v2 é uma revisão do pacote de JSON da biblioteca padrão do Go. Ele chegou como pacote experimental no Go 1.25 e passou a fazer parte do Go 1.27.

O pacote original continua disponível e coberto pela promessa de compatibilidade do Go. A versão 2 oferece uma API nova para quem precisa de comportamento mais estrito e interoperável.

A mudança responde a anos de uso do JSON em APIs e integrações. O objetivo é deixar mais claros os casos de borda que podem fazer componentes diferentes interpretarem a mesma entrada de formas diferentes.

💡
Dica

Trate o v2 como uma migração que exige testes. A compatibilidade de código pode ser alta, mas alguns resultados mudam.

Como funciona

O pacote oferece operações como Marshal e Unmarshal, além de funções para trabalhar com leitores e escritores.

O pacote encoding/json/jsontext fica em uma camada mais baixa. Seus tipos trabalham com tokens e valores JSON, mantendo uma máquina de estados para validar o texto.

Na prática, o v2 tenta transformar problemas silenciosos em erros observáveis. Isso ajuda serviços que recebem dados de clientes diferentes.

Principais recursos

Os defaults são mais rigorosos. Uma string com UTF-8 inválido gera erro, objetos com nomes duplicados são rejeitados e a correspondência de nomes de campos é mais estrita por padrão.

Há novas operações para escrever e ler usando io.Writer e io.Reader. Isso combina com servidores que já processam dados por streams.

  • encoding/json/v2: serialização e desserialização de alto nível.
  • encoding/json/jsontext: processamento sintático de tokens e valores.
  • Options: configuração de comportamento da operação.
⚠️
Atenção

Um cliente que envia JSON duplicado ou UTF-8 inválido pode começar a receber erro depois da migração.

Como começar: instalação ou acesso passo a passo

O primeiro passo é instalar o Go 1.27 em um ambiente de teste e conferir o compilador.

go version
go env GOVERSION

Depois, crie uma branch exclusiva e troque o import somente no código que será avaliado. Mantenha os testes do pacote original disponíveis para comparação.

import jsonv2 "encoding/json/v2"

var dados Payload
err := jsonv2.Unmarshal(entrada, &dados)

Por fim, rode testes unitários, testes de contrato e exemplos com dados reais anonimizados. Não faça a troca diretamente em produção sem observar as respostas dos clientes.

Exemplo prático

Imagine uma API Go que recebe um cadastro. O handler pode desserializar o modelo e transformar falhas de formato em resposta HTTP 400.

func lerPayload(r io.Reader) (Payload, error) {
    var p Payload
    if err := jsonv2.UnmarshalRead(r, &p); err != nil {
        return Payload{}, fmt.Errorf("JSON inválido: %w", err)
    }
    return p, nil
}

Se a entrada tiver nome duplicado ou bytes inválidos, o serviço deve registrar o erro sem gravar o payload.

Esse comportamento é útil em gateways, webhooks e integrações. Uma entrada ambígua para na borda antes de ser interpretada por várias camadas.

Comparação com alternativas

O encoding/json original continua sendo a escolha para sistemas que dependem exatamente do comportamento anterior.

O encoding/json/v2 faz sentido quando a prioridade é ter defaults rigorosos e opções novas dentro da biblioteca padrão.

Bibliotecas de terceiros podem oferecer recursos específicos, mas também introduzem uma decisão de manutenção. Compare compatibilidade, telemetria e contratos, não apenas velocidade.

Pontos positivos e limitações

O benefício principal é reduzir comportamentos surpreendentes em fronteiras de sistema. Rejeitar UTF-8 inválido e nomes duplicados pode evitar interpretações divergentes.

Outro benefício é configurar a operação com opções e usar APIs de leitura e escrita adequadas ao fluxo do serviço.

A limitação é a compatibilidade semântica. Valores nulos, regras de nomes e erros podem produzir resultados diferentes dos esperados pelo código antigo.

🔴
Cuidado

Não substitua todos os imports em uma busca global. Comece por um serviço e compare as respostas.

Casos de uso reais

Em uma API pública, o v2 ajuda a rejeitar payloads malformados antes da validação de negócio.

Em webhooks, detectar nomes duplicados é útil quando o evento atravessa proxies, filas e consumidores diferentes.

Em ferramentas internas, a migração pode começar por um worker que lê arquivos JSON externos e mede entradas incompatíveis.

Também é um bom laboratório para bibliotecas compartilhadas, desde que as opções escolhidas sejam documentadas.

Dicas e boas práticas

💡
Teste contratos

Guarde exemplos de JSON aceitos e rejeitados. Compare status, corpo serializado e erros.

💡
Observe a produção

Conte falhas de desserialização depois de um deploy gradual para descobrir clientes dependentes do comportamento antigo.

🚀
Separe formatos

Mantenha adaptadores por versão para proteger endpoints novos sem quebrar consumidores antigos.

Vale a pena?

O encoding/json/v2 vale a avaliação para equipes que mantêm APIs, webhooks ou pipelines de dados.

Ele não é uma troca automática para todo projeto. Se o sistema depende do pacote antigo, crie testes de contrato antes de migrar.

O próximo passo é comparar v1 e v2 com payloads reais anonimizados. Assim, a decisão passa a ser baseada em evidência.