Tipos de Error Personalizados e Interfaces de Error

Los tipos de error personalizados adjuntan datos estructurados a los fallos: pistas de estado HTTP, nombres de campo, indicadores de reintento y códigos de error opacos.

Díseñalos para que los llamadores usen errors.As sin importar tus internos, y para que puedas añadir campos más tarde sin romper el contrato de error.

Resumen

La interfaz error solo requiere Error() string.

Todo lo que va más allá es convención: tipos exportados, interfaces de comportamiento opcionales y envolturas no exportadas que mantienen tu implementación flexible.

Los errores enriquecidos potencian el mapeo de API y la observabilidad; las jerarquías sobre-diseñadas perjudican la simplicidad que Go favorece.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

type APIError struct {
    Code    string
    Status  int
    Retry   bool
}
 
func (e APIError) Error() string {
    return e.Code
}
 
var err error = APIError{Code: "USER_MISSING", Status: 404}
var api APIError
if errors.As(err, &api) {
    _ = api.Status
}

Cuándo usar esto:

• Los llamadores necesitan más que un booleano centinela
• Las capas HTTP/gRPC mapean errores a estados y JSON de problemas
• Las métricas necesitan etiquetas Code estables sin analizar cadenas
• Quieres interfaces opcionales como Timeout() bool para reintentos

Ejemplo de Trabajo

package main
 
import (
	"errors"
	"fmt"
)
 
type ValidationError struct {
	Field   string
	Message string
}
 
func (e ValidationError) Error() string {
	return fmt.Sprintf("validation: %s %s", e.Field, e.Message)
}
 
func (e ValidationError) HTTPStatus() int { return 422 }
 
func validateEmail(email string) error {
	if email == "" {
		return ValidationError{Field: "email", Message: "required"}
	}
	return nil
}
 
type statusCoder interface {
	HTTPStatus() int
}
 
func writeResponse(err error) {
	if err == nil {
		fmt.Println("200 ok")
		return
	}
	var sc statusCoder
	if errors.As(err, &sc) {
		fmt.Printf("%d %v\n", sc.HTTPStatus(), err)
		return
	}
	fmt.Printf("500 %v\n", err)
}
 
func main() {
	writeResponse(validateEmail(""))
}

Lo que esto demuestra:

• ValidationError es un tipo de valor con campos y una cadena Error() estable
• La interfaz opcional HTTPStatus() permite a los manejadores mapear sin un type switch en cada variante
• errors.As extrae el tipo concreto de cadenas envueltas cuando añades %w en capas superiores
• Las interfaces de comportamiento se mantienen pequeñas (un método) según los modismos de Go

Análisis Profundo

Cómo Funciona

• Cualquier tipo con Error() string satisface error.
• Los llamadores usan errors.As(err, &target) para enlazar el primer tipo coincidente.
• Envolver con %w mantiene los tipos descubribles a través de las capas.
• Una struct no exportada + funciones constructoras exportadas ocultan campos que puedes cambiar.

Guías de Diseño

Interfaces de Comportamiento Opcionales

Las bibliotecas y la biblioteca estándar usan interfaces opcionales pequeñas comprobadas con aserciones de tipo o errors.As:

• interface{ Timeout() bool } - decisiones de reintento
• interface{ Temporary() bool } - obsoleto pero todavía visto en código antiguo
• interface{ Unwrap() error } - envolviendo (también satisfecho por errores fmt con %w)

Define las tuyas cuando múltiples tipos de error compartan comportamiento sin una struct común.

Notas de Go

// El constructor evita filtrar la disposición de la struct
func NewRateLimitError(retryAfter int) error {
    return rateLimitError{retryAfter: retryAfter}
}
 
// Mal: puntero nil tipado como interfaz de error
func bad() error {
    var p *APIError
    return p // ¡interfaz no nil!
}

Trampas

• Retornar un puntero nil tipado - var e *MyErr; return e produce un error no nil. Solución: Retorna nil o usa tipos de valor.
• Cambiar el texto de Error() como API - Los llamadores pueden registrarlo; no confíes en la coincidencia de subcadenas. Solución: Exporta campos Code para la lógica.
• Jerarquías de errores exportadas enormes - Refleja árboles de excepciones que Go evita. Solución: Pocos tipos, interfaces opcionales, centinelas para casos simples.
• Falta de Unwrap en envolturas personalizadas - Rompe Is/As a través de tu tipo. Solución: Implementa Unwrap() error o incrusta el error envuelto.
• Etiquetas JSON en errores retornados a clientes - Filtra campos internos. Solución: Mapea a un DTO separado en la capa HTTP.
• Receptores de puntero inconsistentes - As hacia MyErr vs *MyErr deben coincidir con los retornos. Solución: Elige un estilo por familia de tipos.

Alternativas

Preguntas Frecuentes

Relacionados

• Errores Centinela y errors.Is - cuando la identidad sin campos es suficiente
• Envoltura de Errores con %w y errors.As - cadenas hacia tipos personalizados
• Diseño de Errores de API para Servicios HTTP y gRPC - cuerpos de error orientados al cliente
• Trazas de Pila con runtime/debug - pilas en tipos de error de diagnóstico
• Mejores Prácticas de Manejo de Errores - reglas de exportación y estabilidad

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

Y29kZWd1aWRlcy5pb3xjZ2lvNDUyfDIwMjYwNw==