Mejores Prácticas para el Manejo de Errores

Estrategia de errores consistente entre bibliotecas y aplicaciones.

Los equipos de Go envían código más rápido cuando cada paquete está de acuerdo en cómo se crean, envuelven, inspeccionan, registran y exponen los errores a los clientes.

Estas reglas convierten los artículos de manejo de errores en esta sección en hábitos revisables para bibliotecas, servicios y CLIs.

Cómo Usar Esta Lista

• Aplica durante el diseño de API, la implementación de manejadores y la revisión de código para cualquier función que devuelva error.
• Las bibliotecas y las aplicaciones tienen trabajos diferentes: devolver vs. traducir.
• Revisa al incorporar nuevos miembros o cuando un servicio agrega gRPC junto con HTTP.

A - Disciplina Central

• Verifica cada retorno de error inmediatamente. Los errores ignorados son bugs; usa linters (errcheck) en CI.
• Devuelve (cero, err) en caso de fallo; nunca uses el valor de éxito cuando err != nil. Los llamadores dependen de este invariante.
• Usa errors.Is y errors.As en lugar de == y coincidencias de cadenas. Sobrevive a cadenas de envoltura y cambios de redacción.
• Envuelve con fmt.Errorf("operación: %w", err) para añadir contexto. Una envoltura por capa con nombres de operación significativos.
• Devuelve nil error en caso de éxito, no punteros nil tipados. Previene sorpresas de err != nil en rutas de éxito.

B - Biblioteca vs. Aplicación

• Las bibliotecas devuelven errores; no registran y devuelven el mismo error. Evita ruido de registro duplicado a menos que añadas contexto único no disponible previamente.
• Las aplicaciones mapean errores a estados HTTP/gRPC en manejadores o interceptores. Los paquetes de dominio permanecen agnósticos al transporte.
• Exporta solo contratos de sentinel y tipos estables. Los errores no exportados te liberan para refactorizar internos.
• No hagas panic para validaciones esperadas o fallos de I/O en bibliotecas. Devuelve error para que los llamadores controlen el comportamiento de salida.
• Usa %v en lugar de %w en los límites públicos cuando las causas internas deban permanecer ocultas. Compromiso de seguridad y abstracción.

C - Contratos de API y Cliente

• Expón códigos estables legibles por máquina (tipo problem, código gRPC), no texto crudo de Error(). Los clientes se ramifican según los códigos.
• Mapea context.DeadlineExceeded a respuestas de tiempo de espera (504/408, gRPC deadline exceeded). Distingue tiempos de espera de no encontrado.
• Registra las causas 5xx con ID de solicitud; devuelve mensajes opacos a los clientes. Incluye pilas solo en el lado del servidor.
• Documenta qué errores son reintentables. Política opcional Retryable() bool o código gRPC documentado.
• Mantén los errores de validación agregados con errors.Join cuando todos los campos importan. Respuesta única que lista cada fallo.

D - Concurrencia y Operaciones

• Nunca escribas variables err compartidas desde goroutines sin sincronización. Usa canales o errgroup.
• Cancela el trabajo hermano al primer fallo con errgroup.WithContext. Ahorra cuotas y CPU.
• Propaga context.Context y envuelve ctx.Err() con %w. Los llamadores distinguen la cancelación del fallo de I/O.
• Captura debug.Stack en diagnósticos de aplicaciones, no en bibliotecas reutilizables. Las pilas son para operadores.
• Prueba las rutas de error: errors.Is, errors.As, y estados HTTP/gRPC mapeados. Las pruebas solo de rutas de éxito se pierden regresiones.

E - Estilo y Mantenimiento

• Nombra los sentinels ErrX en PascalCase. Coincide con las convenciones de la biblioteca estándar.
• Prefiere pocos sentinels; usa tipos personalizados cuando se requieran campos. Evita jerarquías estilo excepciones.
• Mantén las cadenas Error() concisas y estables en significado. La lógica del programa utiliza campos y Is/As, no subcadenas.
• Revisa las nuevas dependencias externas para el comportamiento de envoltura de errores. ORMs y SDKs pueden necesitar mapeadores adaptadores.
• Alinea el ADR del equipo en 400 vs 422 para validación y cíñete a él. Las políticas mixtas rompen los SDKs de cliente.

Preguntas Frecuentes

Relacionado

• Errores como Valores: La Filosofía de Errores de Go - base conceptual
• Conceptos Básicos de Manejo de Errores - introducción a la sección ejecutable
• Errores Sentinel y errors.Is - reglas de sentinel en profundidad
• Envoltura de Errores con %w y errors.As - mecánica de envoltura
• Diseño de Errores de API para Servicios HTTP y gRPC - contratos de cliente

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