Melhores Práticas de Serialização
Convenções de equipe para tags JSON, limites de decodificação, ordem de validação e testes de evolução.
//
Busque em todas as páginas da documentação
Convenções de equipe para tags JSON, limites de decodificação, ordem de validação e testes de evolução.
Bugs de serialização aparecem como perda silenciosa de dados, não como erros de compilação.
Estas regras mantêm os formatos de comunicação estáveis entre implantações e versões de clientes.
userId e user_id.json, db e validate alinhadas em structs compartilhadas, a menos que um esquema legado force uma exceção documentada. O grep captura desvios na revisão.json:"-" para segredos e campos internos. Nunca registre a struct completa se houver campos sensíveis sem redação.map[string]any para APIs públicas estáveis. Mapas ocultam o esquema de compiladores e OpenAPI.r.Body com http.MaxBytesReader antes de qualquer decodificação. Rejeite payloads excessivamente grandes antes que ataques de alocação tenham sucesso.json.NewDecoder em caminhos de requisição; defina DisallowUnknownFields apenas para APIs internas/administrativas estritas. APIs públicas permanecem permissivas para compatibilidade futura.go-playground/validator (ou equivalente) imediatamente após a decodificação. A serialização não é validação.validator.ValidationErrors para JSON de problema documentado.Content-Type: application/json; charset=utf-8 em respostas JSON. Clientes e caches dependem de cabeçalhos explícitos.MarshalJSON e UnmarshalJSON simétricos ao personalizar tipos. Testes de ida e volta são obrigatórios.type alias T dentro de métodos.testdata/. CI decodifica payloads antigos em structs novas.Unmarshal em DTOs sensíveis à segurança. Capture panics e combinações de tipos inesperadas precocemente.json.RawMessage. Processe tipos de evento desconhecidos sem travar workers.Categoria A: limites de tamanho de corpo em manipuladores, testes JSON de referência para DTOs públicos e validador em endpoints de criação/atualização.
A nomenclatura de tags é aplicada na revisão, a menos que um linter seja configurado.
Apenas structs que cruzam os limites HTTP e SQL precisam de json, db e validate.
Divida DTOs quando os formatos divergirem materialmente.
Seja permissivo por padrão.
Use métricas e diff de OpenAPI em CI para capturar erros de digitação do cliente sem quebrar aplicativos antigos.
Quando as respostas precisam ocultar campos somente de escrita, colunas de junção ou formatos versionados.
Não reutilize modelos de banco de dados cegamente para JSON público.
gin, echo e chi ainda precisam de limites de corpo explícitos e configuração de validação.
Os vinculadores de framework não substituem a defesa em profundidade.
Protobuf é o dono do contrato na comunicação.
Aplique a mesma disciplina de evolução aos nomes de campos JSON transcodificados documentados para navegadores.
Sim - validator.New() em nível de pacote com registros personalizados em init.
Evite a criação de engine por requisição.
Consumidores de fila decodificam JSON da mesma forma que HTTP.
Aplique limites de tamanho nos bytes da mensagem do cliente do broker.
Nomenclatura JSON, política de decodificação estrita vs. permissiva, formato por limite e cronogramas de depreciação.
Link para fixtures testdata.
Copie o template de manipulador da equipe: MaxBytesReader, decodificar, validar, mapear erros.
Indique os engenheiros para Fundamentos de Serialização primeiro.
Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verifique o patch na compilação), chi (última versão - verifique na compilação), gin (última versão - verifique na compilação), echo (última versão - verifique na compilação), google.golang.org/grpc (última versão - verifique na compilação), sigs.k8s.io/controller-runtime (última versão - verifique na compilação), kubebuilder (última versão - verifique na compilação), tinygo (última versão - verifique os alvos de placa na compilação), wazero (última versão - verifique na compilação) e golangci-lint (última versão - verifique o conjunto de linters na compilação).
Revisado por Chris St. John·Última atualização: 18 de jul. de 2026