Go 1.27: encoding/json/v2 é estável e os defaults rígidos mudam o contrato da sua API
Go 1.27: encoding/json/v2 é estável — e os defaults rígidos mudam o contrato da sua API
Em 4 de novembro, o time de Go publicou no blog oficial a declaração de que encoding/json/v2 e encoding/json/jsontext estão estáveis e disponíveis para uso geral na Go 1.27. Foram cerca de seis anos de trabalho — de uma talk na GopherCon a uma proposta formal, seguida de um período atrás de GOEXPERIMENT=jsonv2 desde a 1.25.
O ponto que interessa a quem mantém serviço em produção não é o anúncio em si, e sim o que ele oficializa: o pacote que praticamente todo backend Go usa todos os dias ganhou uma segunda geração com defaults mais estritos. Nome de membro duplicado vira erro. UTF-8 inválido vira erro. Campo do struct passa a casar por caixa exata. E um nil slice deixa de virar null no JSON.
É o tipo de mudança que não quebra compilação, não aparece em code review e chega direto no contrato da API. Este texto separa o que é fato documentado do que é avaliação de projeto, e mostra onde ajustar.
Duas camadas: sintaxe separada de semântica
A arquitetura é a parte que explica todo o resto. O jsontext cuida só de sintaxe: lê e escreve tokens, valida a estrutura segundo a RFC 8259, e não usa reflexão. Ele enxerga JSON como uma sequência de tokens e como jsontext.Value , o "JSON arbitrário" que você segura na mão sem decidir ainda o que ele significa.
O encoding/json/v2 fica por cima e cuida de semântica: mapear struct para objeto JSON, tags, Marshaler , Unmarshaler , opções. Como a camada de sintaxe não precisa de reflexão por campo, o caminho de decodificação ficou bem mais barato — o blog oficial fala em até 10x mais rápido no Unmarshal e "aproximadamente em paridade" no Marshal .
Essa separação também muda a API pública: json.Marshal , json.Unmarshal , mas também json.MarshalWrite , json.UnmarshalRead , json.MarshalEncode , json.UnmarshalDecode , além das opções passadas por chamada ( json.Unmarshal(body, &v, ...) aceita variádicas).
O que muda mesmo sem você importar o pacote novo
Detalhe pouco comentado: na 1.27, o encoding/json (v1) passou a ser implementado em cima do v2, com as opções legadas aplicadas por padrão. A semântica antiga foi preservada de propósito, mas a implementação mudou — ou seja, atualizar a versão da linguagem já mexe em um pacote que você não tocou. Mensagens de erro ficaram mais específicas e algumas bordas mudam de comportamento. Antes de subir a 1.27, rode a suíte de testes que cobre serialização; não confie só na ausência de erro de compilação.
O quadro de diferenças que importa no código
Os três primeiros são os que costumam aparecer no primeiro deploy. Veja o efeito em código:
Aquela última linha é a mudança mais silenciosa e a mais perigosa. Cliente que distinguia null de [] para saber "campo ausente" versus "lista vazia" agora recebe [] sempre. Em TypeScript, itens: Item[] | null vira contrato quebrado sem nenhum erro de runtime no servidor.
Voltando ao comportamento antigo, opção por opção
Ninguém precisa reescrever tudo de uma vez. O v2 aceita recompor o comportamento legado por chamada:
A recomendação é granular: cada ponto que precisa do comportamento antigo recebe a opção, e o resto já nasce no padrão novo. O guia de migração oficial ( go.dev/doc/jsonv2-migration ) lista as opções por atributo — casamento por caixa, duplicados, formatação de nil , escapes — e a regra de composição é simples: opção passada depois sobrescreve a anterior do mesmo atributo.
Streaming sem buffer intermediário
Quem serializa payload grande ganha duas ferramentas novas. json.MarshalWrite(w, v) e json.UnmarshalRead(r, v) trabalham direto em io.Writer e io.Reader , sem aquele []byte intermediário de json.Marshal :
O outro par é de interfaces: MarshalerTo ( MarshalJSONTo(*jsontext.Encoder) error ) e UnmarshalerFrom ( UnmarshalJSONFrom(*jsontext.Decoder) error ). Elas substituem o padrão de MarshalJSON() ([]byte, error) nas situações em que o custo do buffer aparece — no meio de um array grande, ou escrevendo direto no encoder. As interfaces antigas seguem funcionando.
Desempenho: o 10x é teto de pacote, não SLA de endpoint
Vale calibrar a expectativa. O número do blog é microbenchmark de pacote, com CPU dedicada e payload controlado. Em serviço HTTP real, boa parte do tempo está em I/O, middleware, TLS e serialização de outros formatos. Quem mediu em API sob carga relata ganho menor e mais dependente de payload grande e CPU saturada. Ganho de CPU em decoder é bem-vindo — só não planeje capacidade com base no "10x".
Do lado de projeto, o que tenho visto funcionar é tratar o JSON como fronteira de contrato, não como detalhe de framework. Em times que mantêm APIs em Go convivendo com serviços Node.js e .NET, como o que a Maquinaweb mantém em operação, o valor real do v2 aparece quando existe teste de contrato em cima de cada payload: os quatro casos da tabela viram teste, e a migração deixa de ser aposta.
Riscos e armadilhas
Golden files desatualizados. Qualquer snapshot de resposta JSON gerado antes da migração vai falhar — e é bom que falhe. Revisar cada diff é o que revela null virando [] .
PATCH que deixa de ser vazio. Com omitempty redefinido, um struct zerado que serializava {} passa a emitir {"count":0,"enabled":false} . Em endpoints PATCH, onde ausência de membro significa "não mexa", isso muda o significado da requisição. Use omitzero nesses campos.
Cliente que dependia de caixa. Integrações antigas que mandavam {"ID": 7} funcionavam por acidente. Agora falham em silêncio (campo fica zero) — pior que falhar com erro.
Log e métrica que parseiam JSON. Pipeline que lê saída de serviço próprio com parser tolerante pode engasgar em erro novo ou em [] no lugar de null .
MarshalWrite não tem rollback. Se o erro aparece no meio do stream, o 200 OK já foi enviado. Valide o payload antes de escrever a resposta.
Recomendação
Para código novo, comece no encoding/json/v2 — os defaults estritos são o comportamento correto para API pública. Para código existente, a ordem que reduz risco: suba a 1.27, rode a suíte com -race , adicione testes de contrato para duplicados, caixa, UTF-8 e slice vazio, migre handlers por handler e use as opções legadas apenas onde houver motivo documentado. Um golangci-lint bloqueando import de v1 em pacotes novos é o tipo de regra simples que evita regressão em seis meses.
Se o time está avaliando migrar uma API grande, ou começando um serviço novo e quer discutir estrutura de payload, versionamento de contrato e testes de serialização, dá para conversar com o pessoal da Maquinaweb — eles trabalham com Go, Node.js, C#, .NET, Angular e TypeScript em times multidisciplinares, e desenvolvem sob medida do desenho da API ao deploy.
Fontes
Continue lendo
Desenvolvimento Rust 1.100: o tipo `!` vira estável, o fallback muda em todas as edições e o Cargo segura crates recém-publicadas
Rust 1.100 estabiliza o never type `!`, o núcleo do Allocator API e o cooldown de dependências do Cargo. O fallback agora resolve para `!` em todas as edições, o que quebra código antigo e cria armadilhas em blocos unsafe.
Ler artigo →
Desenvolvimento Vercel abre o UI SDK em beta: comportamentos de interface viram biblioteca TypeScript — e o agente ganha uma ponte para agir na tela
O Vercel UI SDK saiu em beta sob Apache 2.0 e separa comportamentos (foco, teclado, seleção, popup, drag and drop) dos componentes, com adaptadores para React, Vue, Svelte, Solid e Web Components. Também expõe estado e ações a agentes, com aprovação do app. Veja o que isso muda no seu código.
Ler artigo →
Desenvolvimento MAG expõe 8,7 milhões em três aeroportos do Reino Unido — e a credencial de terceiro vira o vetor do dia
MAG confirmou acesso indevido que expôs dados de cerca de 8,7 milhões de passageiros de Manchester, Stansted e East Midlands. O rastro de credenciais vazadas vai de 149.346 motoristas da Uber a 5 mil devs do Cursor e 5 milhões de registros da AirAsia.
Ler artigo →