Mejores Prácticas de Serialización

Convenciones del equipo para etiquetas JSON, límites de decodificación, orden de validación y pruebas de evolución.

Los errores de serialización se manifiestan como pérdida silenciosa de datos, no como errores de compilación.

Estas reglas mantienen los formatos de comunicación estables a través de despliegues y versiones de clientes.

Cómo Usar Esta Lista

• Marque las reglas a medida que su plantilla de servicio las adopte.
• Codifique los elementos de Nivel A en CI: pruebas JSON doradas, límites de tamaño de cuerpo y cobertura de validadores en DTOs públicos.
• Úselo como una rúbrica de PR para cualquier cambio que toque etiquetas de struct o cargas útiles de API.
• Revise al agregar gateways gRPC, nuevos clientes móviles o rutas de ingesta de alto rendimiento.

A - Etiquetas y forma del DTO

• Elija una convención de nomenclatura JSON por API (usualmente snake_case) y repítala en las etiquetas de struct. Los revisores rechazan claves mixtas userId y user_id.
• Mantenga las etiquetas json, db y validate alineadas en structs compartidos, a menos que un esquema heredado fuerce una excepción documentada. Grep detecta desviaciones en la revisión.
• Use json:"-" para secretos y campos solo internos. Nunca registre el struct completo si existen campos sensibles sin redacción.
• Modele números y booleanos opcionales con punteros cuando el cero sea significativo. Distinga ausente de cero explícito para los clientes.
• Prefiera structs explícitos sobre map[string]any para APIs públicas estables. Los mapas ocultan el esquema de los compiladores y OpenAPI.

B - Decodificar, validar y responder

• Envolva r.Body con http.MaxBytesReader antes de cualquier decodificación. Rechace cargas útiles excesivas antes de que los ataques de asignación tengan éxito.
• Decodifique con json.NewDecoder en rutas de solicitud; establezca DisallowUnknownFields solo para APIs internas/de administración estrictas. Las APIs públicas se mantienen permisivas para compatibilidad futura.
• Valide con go-playground/validator (o equivalente) inmediatamente después de decodificar. La serialización no es validación.
• Devuelva errores 400 estables a nivel de campo sin filtrar trazas de pila. Mapee validator.ValidationErrors a JSON de problema documentado.
• Establezca Content-Type: application/json; charset=utf-8 en las respuestas JSON. Los clientes y las cachés dependen de encabezados explícitos.

C - Serialización y formatos personalizados

• Implemente MarshalJSON y UnmarshalJSON simétricos al personalizar tipos. Las pruebas de ida y vuelta son obligatorias.
• Use el patrón de alias para evitar la serialización recursiva. Copie los campos a type alias T dentro de los métodos.
• Elija JSON para HTTP; protobuf para gRPC interno; gob solo para cachés efímeras locales de Go. Documente el formato por límite de sistema en los ADRs.
• No persista blobs gob como almacenamiento a largo plazo. Los cambios de nombre de campo rompen gob silenciosamente entre despliegues.
• Realice benchmarks antes de adoptar sonic/jsoniter; fije versiones y mantenga la reversión a la biblioteca estándar durante una versión. Los cambios de velocidad no son gratuitos.

D - Evolución y pruebas de esquema

• Agregue campos; no renombre ni re-tipifique claves JSON en su lugar. Use ventanas de deprecación y decodificadores de doble clave durante la migración.
• Mantenga fixtures JSON doradas por versión de API en testdata/. CI decodifica cargas útiles antiguas en structs nuevos.
• Fuzz Unmarshal en DTOs sensibles a la seguridad. Detecte panics y combinaciones de tipos inesperadas tempranamente.
• Documente las semánticas nulo vs. ausente para campos punteros opcionales. Los clientes móviles y OpenAPI dependen de un comportamiento consistente.
• Codifique enteros mayores a 2^53 como cadenas cuando los clientes JavaScript los consuman. Prevenga la pérdida silenciosa de precisión.

E - Operaciones y observabilidad

• Registre campos estructurados, no cuerpos de solicitud sin procesar, en producción. Redacte tokens y PII en el límite de registro.
• Métricas de fallos de decodificación/validación por separado de los 500s. Los picos en la validación 400 a menudo señalan errores o ataques del cliente.
• Limite la profundidad anidada y los tamaños de colección en la política de aplicación donde la biblioteca estándar no puede. Barreras de seguridad adicionales para puntos de entrada de importación de administración.
• Versionar analizadores de webhook externos con sobres json.RawMessage. Maneje tipos de eventos desconocidos sin bloquear trabajadores.
• Registre la elección de la biblioteca de serialización (stdlib vs sonic) en el README del servicio. El personal de guardia necesita conocer las diferencias de comportamiento durante los incidentes.

Preguntas Frecuentes

Relacionado

• Serialización en Go: JSON Primero, Formatos Bajo Demanda - vista conceptual
• Conceptos Básicos de Serialización - ejemplos ejecutables
• Etiquetas de Struct para JSON, DB y Validación - referencia de etiquetas
• Evolución de Esquema y Manejo de Campos Desconocidos - APIs compatibles con versiones futuras
• Validación con go-playground/validator - cableado de validación

Versiones de Stack: Esta página fue escrita para Go 1.26.x (GC por defecto Green Tea, go fix modernizers - verifique el parche en la compilación), chi (última - verifique en la compilación), gin (última - verifique en la compilación), echo (última - verifique en la compilación), google.golang.org/grpc (última - verifique en la compilación), sigs.k8s.io/controller-runtime (última - verifique en la compilación), kubebuilder (última - verifique en la compilación), tinygo (última - verifique los objetivos de placa en la compilación), wazero (última - verifique en la compilación) y golangci-lint (última - verifique el conjunto de linters en la compilación).