Resumo dos Destaques de Serialização

Cada item de destaque das 9 páginas desta seção, reunido em uma única página e agrupado pela página de origem.

Serialização em Go: JSON Primeiro, Formatos Sob Demanda

• encoding/json é o formato de comunicação padrão para APIs HTTP, configurações e logs
• Tags de struct mapeiam campos Go para chaves JSON; omitempty e - controlam a visibilidade
• MarshalJSON e UnmarshalJSON personalizam tipos que a biblioteca padrão não consegue inferir
• Codecs XML, gob e binários atendem a nichos legados, RPC e de armazenamento
• Validação e evolução de esquema ficam ao lado da serialização, não dentro dela

Noções Básicas de Serialização

• Marshal retorna bytes, Unmarshal precisa de destinos de ponteiro, apenas campos exportados codificam
• Use tags de struct para mapear chaves JSON, excluir campos e omitir valores padrão zero
• Use omitempty para ocultar valores zero e ponteiros para campos opcionais que precisam de null
• Slices nil codificam como null, slices não vazios como arrays, prefira structs a mapas
• Use Encoder e Decoder para streams para evitar carregar corpos inteiros na memória
• Structs embutidas promovem campos via embutimento anônimo para composição flexível

Serialização Personalizada do encoding/json

• Implemente Marshaler e Unmarshaler quando as tags de struct não puderem expressar as formas JSON necessárias
• MarshalJSON retorna JSON completo, incluindo aspas para strings, não valores duplamente codificados
• Use receptores de ponteiro em UnmarshalJSON para que o decodificador possa modificar os valores de destino
• Defina structs de alias de tipo para passar pela serialização para comportamento padrão sem recursão
• Serializadores externos substituem métodos embutidos quando ambos definem MarshalJSON
• Campos embutidos são achatados no JSON pai, a menos que o tipo embutido tenha seu próprio serializador

encoding/xml, gob & Formatos Binários

• Escolha o serializador pelo consumidor: JSON para REST, XML para empresas, gob para uso exclusivo em Go
• gob codifica informações de tipo Go na comunicação; o codificador e o decodificador devem registrar os mesmos tipos
• Chame gob.Register para tipos de interface para evitar pânico em tempo de execução
• Tags XML espelham JSON com xml:attr para atributos e xml:chardata para texto
• gob é inadequado para navegadores, serviços poliglotos ou armazenamento de longo prazo
• Use gob para armazenar em cache structs entre dois binários Go implantados juntos

Tags de Struct para JSON, DB & Validação

• Use tags de struct json, db e validate juntas para lidar com serialização, armazenamento e regras de entrada
• Campos Go usam PascalCase, enquanto JSON e SQL comumente usam snake_case, exigindo tags explícitas
• Tags json são ignoradas em campos não exportados, limitando a serialização da API a membros públicos da struct
• Comece com uma única struct para HTTP e DB, depois divida quando o versionamento da sua API divergir
• ORMs como GORM usam suas próprias tags de struct, então comprometa-se com um estilo de persistência por projeto
• Cada biblioteca ignora chaves de tag desconhecidas, portanto, misture com segurança json, db e validate no mesmo campo

Evolução de Esquema & Tratamento de Campos Desconhecidos

• json.Unmarshal padrão ignora silenciosamente campos desconhecidos para compatibilidade futura
• Use DisallowUnknownFields para capturar erros de digitação em ferramentas internas e webhooks
• Adicione campos opcionais com omitempty ou ponteiros, nunca renomeie chaves no local
• Adicione chaves versionadas como price_cents_v2 em vez de alterar os tipos existentes
• json.RawMessage preserva extensões e dados aninhados sem recodificar
• Documente os padrões do servidor para campos ausentes para garantir a compatibilidade do cliente

JSON de Alto Desempenho: Alternativas jsoniter & sonic

• Faça benchmark da biblioteca padrão primeiro; o overhead de reflexão só aparece em alta taxa de transferência de mensagens
• Migre para jsoniter/go via ConfigCompatibleWithStandardLibrary; observe as sutilezas de omitempty
• Sonic usa SIMD e JIT para benchmarks de ponta em cargas úteis grandes, mas requer validação de plataforma
• O fixo de versão é crítico; bibliotecas JSON alternativas divergem sutilmente de encoding/json
• Mantenha a biblioteca padrão quando o JSON for inferior a 5% da CPU ou a latência for dominada pela rede/banco de dados
• Reduza alocações e transmita com json.Encoder ou gere código com easyjson primeiro

Validação com go-playground/validator

• Decodifique JSON primeiro, depois valide com validator.Struct para erros de campo
• Use tags de struct como required, email, gte para expressar restrições comuns
• Registre validadores personalizados com RegisterValidation para regras específicas do domínio
• Mantenha os validadores puros e rápidos, pois eles são executados por solicitação
• Mapeie erros de validador para códigos de API estáveis sem vazar caminhos de campo
• A validação permanece separada da serialização para reutilização de struct

Melhores Práticas de Serialização

• Escolha uma convenção de nomenclatura JSON por API, geralmente snake_case
• Oculte campos sensíveis da saída JSON antes de registrar quaisquer structs
• Envolva corpos de solicitação com MaxBytesReader antes de decodificar para evitar ataques de alocação
• Valide imediatamente após a decodificação, não durante — a serialização não é validação
• Adicione novos campos apenas; nunca renomeie ou retipe chaves JSON durante migrações
• Codifique inteiros acima de 2^53 como strings para evitar perda de precisão em JavaScript

WTI5a1pXZDFhV1JsY3k1cGIzeGpaMmx2TkRjNWZESXdNall3Tnc9PQ==