Errores Centinela y errors.Is

Los errores centinela son variables a nivel de paquete que representan una identidad de fallo fija.

Los llamadores los reconocen con errors.Is en lugar de coincidencias de cadenas o comprobaciones == frágiles que se rompen una vez que los errores se envuelven.

Resumen

Los errores centinela dan a tu API un pequeño vocabulario de resultados estables: no encontrado, ya existe, cancelado, entrada inválida.

Go 1.13 añadió errors.Is para que esas identidades sobrevivan a las cadenas de envoltura de fmt.Errorf("...: %w", err).

Usa centinelas para contratos entre paquetes; recurre a tipos personalizados cuando los llamadores necesiten campos estructurados.

Receta

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

var ErrNotFound = errors.New("not found")
 
func Find(id string) (Item, error) {
    if id == "" {
        return Item{}, ErrNotFound
    }
    return Item{}, nil
}
 
if errors.Is(err, ErrNotFound) {
    // manejar recurso faltante
}

Cuándo recurrir a esto:

• Un modo de fallo forma parte del contrato de tu API pública
• Los llamadores necesitan una rama booleana sin analizar cadenas
• El error no tiene campos adicionales más allá de su identidad
• Los patrones de la biblioteca estándar (io.EOF, os.ErrNotExist) se aplican a tu dominio

Ejemplo Funcional

package main
 
import (
	"errors"
	"fmt"
	"os"
)
 
var ErrUserNotFound = errors.New("user not found")
 
func loadUser(path string) error {
	_, err := os.ReadFile(path)
	if err != nil {
		if os.IsNotExist(err) {
			return fmt.Errorf("load user %q: %w", path, ErrUserNotFound)
		}
		return fmt.Errorf("load user %q: %w", path, err)
	}
	return nil
}
 
func main() {
	err := loadUser("alice.json")
	switch {
	case errors.Is(err, ErrUserNotFound):
		fmt.Println("client: 404 user missing")
	case err != nil:
		fmt.Println("client: 500", err)
	default:
		fmt.Println("ok")
	}
}

Lo que esto demuestra:

• Un centinela de dominio (ErrUserNotFound) se mapea a un resultado del cliente
• fmt.Errorf con %w preserva tanto los centinelas de os como los de dominio en la cadena
• errors.Is encuentra ErrUserNotFound a través de las envolturas
• os.IsNotExist es un envoltorio de conveniencia alrededor de errors.Is(err, os.ErrNotExist)

Inmersión Profunda

Cómo Funciona

• errors.New devuelve un valor de error opaco con una identidad fija.
• Envolver con %w implementa Unwrap() error, enlazando errores externos e internos.
• errors.Is(err, target) devuelve verdadero si err == target o cualquier paso de desempaquetado coincide.
• err == ErrX directo falla cuando un envoltorio se interpone entre el llamador y el centinela.

Nomenclatura y Ubicación de Centinelas

io.EOF y Flujo de Control

io.EOF señala el fin del flujo durante Read, no necesariamente un fallo catastrófico.

Bucle hasta errors.Is(err, io.EOF) después de procesar el último fragmento.

Notas de Go

// Malo: se rompe después de envolver
if err == ErrNotFound { ... }
 
// Bueno
if errors.Is(err, ErrNotFound) { ... }
 
// También bueno para ayudantes de la biblioteca estándar
if os.IsNotExist(err) { ... }

Trampas

• Usar == después de envolver - Los errores envueltos nunca son iguales al centinela. Solución: Usa errors.Is.
• Demasiados centinelas - Docenas de variables ErrX se vuelven difíciles de documentar. Solución: Agrupa fallos relacionados en un tipo de error o un enum de códigos de error.
• Exportar centinelas internos - Los llamadores dependen de valores que no puedes evolucionar. Solución: Exporta solo errores de contrato estables; mantén los ayudantes sin exportar.
• Coincidencia de cadenas con strings.Contains - Frágil a través de envolturas y cambios de redacción. Solución: errors.Is o errors.As.
• Devolver punteros nil tipados - return (*MyError)(nil) hace que err != nil sea verdadero. Solución: return nil o var err error = nil.
• Tratar cada EOF como un fallo - Los bucles de lectura esperan EOF. Solución: Ramifica en errors.Is(err, io.EOF) por separado de los errores reales.

Alternativas

Preguntas Frecuentes

Relacionados

• Errores como Valores: La Filosofía de Errores de Go - por qué existen los errores explícitos
• Envoltura de Errores con %w y errors.As - cadenas e inspección tipada
• Tipos de Errores Personalizados e Interfaces de Error - cuando los centinelas no son suficientes
• Diseño de Errores de API para Servicios HTTP y gRPC - mapeo a códigos de estado
• Mejores Prácticas de Manejo de Errores - convenciones del equipo

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