
Go 1.27 torna encoding/json/v2 disponível com padrões mais rígidos
Contexto e problemas da versão atual
O post do blog oficial do Go anuncia que os pacotes encoding/json/v2 e encoding/json/jsontext se tornaram estáveis e disponíveis em geral no Go 1.27. O texto descreve que a biblioteca encoding/json atual, em uso desde antes do Go 1.0, funciona bem de modo geral, mas acumulou falhas de comportamento e limitações de API e de desempenho.
Entre os comportamentos apontados estão: aceitar UTF-8 inválido, aceitar nomes de membros duplicados (algo que já foi explorado, como no CVE-2017-12635), serializar slices e maps nil como null, e resolver nomes de campos sem diferenciar maiúsculas de minúsculas. Também há inconsistência na chamada de métodos MarshalJSON com receptor ponteiro, classificada como bug que não pode ser corrigido sem quebrar aplicações existentes.
Na API, os autores citam dificuldade em ler de um io.Reader corretamente (o padrão json.NewDecoder(r).Decode(v) não rejeita lixo no fim da entrada) e opções que não funcionam em todos os caminhos de chamada. Nas limitações de desempenho, citam a obrigação de MarshalJSON retornar um []byte validado, a necessidade de analisar o valor duas vezes em UnmarshalJSON e a ausência de streaming real.
Por que um novo pacote
Segundo o texto, esses problemas são consequências da API existente e, por isso, seriam praticamente impossíveis de corrigir dentro da promessa de compatibilidade do Go 1. Nomes como MarshalV2 foram descartados por criarem um namespace paralelo no mesmo pacote. A solução escolhida foi um novo pacote encoding/json/v2, em um namespace separado.
Arquitetura: jsontext e v2
O pacote jsontext trata apenas da sintaxe do JSON, sem usar reflexão, e opera de forma realmente streaming. Já v2 atribui significado semântico aos valores, relacionando valores JSON e tipos Go. Os novos métodos MarshalJSONTo e UnmarshalJSONFrom operam sobre Encoder e Decoder, o que permite processamento em fluxo e repassa opções pela pilha de chamadas.
As opções passam a ser argumento de primeira classe em Marshal e Unmarshal. Também é possível que o chamador defina representações personalizadas para qualquer tipo, com precedência sobre métodos do tipo.
Mudanças de comportamento
A v2 reporta erro para UTF-8 inválido e para nomes duplicados; serializa slices e maps nil como array ou objeto vazio; faz correspondência de campos sensível a maiúsculas; redefine omitempty para omitir valores vazios (null, "", [], {}); e reporta erro ao serializar time.Duration. Para a maioria dessas mudanças há uma opção ou tag para manter o comportamento da v1.
Desempenho
Segundo o post, o desempenho de Marshal fica aproximadamente no mesmo nível da v1, às vezes um pouco melhor e às vezes um pouco pior. Unmarshal é significativamente mais rápido, com ganhos de até 10x nos benchmarks. Os autores recomendam migrar implementações para MarshalerTo e UnmarshalerFrom para obter mais ganhos; um caso citado no Kubernetes melhorou em ordens de grandeza. Os autores afirmam que haverá novas otimizações no Go 1.28.
Compatibilidade e migração
A v1 continuará suportada indefinidamente e não precisa migrar. A v1 foi reimplementada sobre a v2, e os dois pacotes são interoperáveis, para que dependências usando versões diferentes funcionem juntas. Há um guia de migração e exemplos de como combinar opções para manter comportamentos específicos da v1 ou da v2.
Histórico
O trabalho começou no fim de 2020, com rascunhos de Daniel Martí e um protótipo de Joe Tsai, a partir da lógica de serialização do módulo protobuf do Go. O texto diz que o projeto levou cerca de seis anos, passou por experimento no Go 1.25 e que grande parte do desenvolvimento foi feita por pessoas que não trabalham no Google.