Envoltura de Errores con %w y errors.As

La envoltura añade contexto a los fallos mientras preserva la causa original para su inspección.

fmt.Errorf con %w construye una cadena de desenvoltura; errors.Is y errors.As recorren esa cadena para que los llamadores reconozcan centinelas y tipos personalizados a través de capas intermedias.

Resumen

Go 1.13 estandarizó la envoltura de errores: cada capa añade contexto de operación (leer configuración, conectar a db) sin destruir el os.ErrNotExist raíz o tu tipo de dominio.

errors.As extrae datos tipados cuando un centinela es demasiado genérico.

Usa %v cuando el error interno no deba participar en Is/As.

Receta

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

if err != nil {
    return fmt.Errorf("obtener usuario %q: %w", id, err)
}
 
var pathErr *os.PathError
if errors.As(err, &pathErr) {
    log.Println("ruta:", pathErr.Path)
}
 
if errors.Is(err, os.ErrNotExist) {
    return ErrNotFound
}

Cuándo usar esto:

• Cada capa entre I/O y el manejador añade contexto distinto
• Los llamadores deben distinguir entre tiempo de espera y no encontrado a través de envolturas
• Necesitas campos de un tipo de error personalizado en medio de la cadena
• Los pasos paralelos producen múltiples errores para agregar con errors.Join

Ejemplo de Trabajo

package main
 
import (
	"errors"
	"fmt"
	"net"
	"os"
)
 
type OpError struct {
	Op string
}
 
func (e OpError) Error() string {
	return fmt.Sprintf("%s falló", e.Op)
}
 
func readDB(path string) error {
	_, err := os.ReadFile(path)
	if err != nil {
		return OpError{Op: "leer"}
	}
	return nil
}
 
func loadUser(path string) error {
	if err := readDB(path); err != nil {
		return fmt.Errorf("cargar usuario desde %q: %w", path, err)
	}
	return nil
}
 
func main() {
	err := loadUser("missing.db")
	var op OpError
	if errors.As(err, &op) {
		fmt.Println("operación:", op.Op)
	}
	fmt.Println("no existe:", errors.Is(err, os.ErrNotExist))
	fmt.Println("tiempo de espera de red:", errors.Is(err, net.ErrClosed))
}

Lo que esto demuestra:

• El tipo personalizado OpError es alcanzable a través de una envoltura fmt.Errorf
• errors.As requiere un puntero al tipo de destino
• errors.Is todavía encuentra os.ErrNotExist bajo OpError si la cadena lo incluye
• Los mensajes de texto son para humanos; Is/As son para lógica de programa

Inmersión Profunda

Cómo Funciona

• %w crea un envoltorio que implementa Unwrap() error.
• errors.Unwrap(err) devuelve un nivel; Is/As iteran hasta encontrar una coincidencia o nil.
• Solo se permite un %w por llamada a fmt.Errorf.
• errors.Join(errs...) (Go 1.20+) devuelve un error que se desenvuelve en múltiples valores; Is/As comprueban cada uno.

%w vs %v

Reglas de errors.As

• El segundo argumento debe ser un puntero a un tipo que implemente error o un puntero a un campo de struct.
• Devuelve true y asigna el primer valor coincidente en la cadena.
• Prefiere receptores de valor en tipos de error a menos que necesites comportamiento específico de puntero.

Notas de Go

// Extracción tipada
var pe *os.PathError
if errors.As(err, &pe) {
    _ = pe.Path
}
 
// Desenvoltura manual de un nivel (raro)
inner := errors.Unwrap(err)

Trampas

• Múltiples %w en un Errorf - Error de compilación. Solución: Envuelve una vez por llamada; encadena con fmt.Errorf anidado.
• Pasar un no-puntero a errors.As - Siempre falla. Solución: var target MyErr; errors.As(err, &target).
• Receptor de puntero vs valor en tipos de error - errors.As en *MyErr vs MyErr debe coincidir con lo que devuelves. Solución: Sé consistente; documenta el tipo de retorno del constructor.
• Usar As para centinelas - errors.Is es más simple para var ErrX. Solución: Reserva As para tipos con campos.
• Fugas de secretos en mensajes de envoltura - %w junto con logs verbosos pueden exponer tokens. Solución: Sanea los mensajes; usa %v en los límites públicos.
• Asumir que el texto de Error() es estable - Los llamadores no deben parsear cadenas. Solución: Exporta centinelas o tipos para verificaciones programáticas.

Alternativas

Preguntas Frecuentes

Relacionado

• Errores Centinela y errors.Is - comparación de centinelas a través de cadenas
• Tipos de Error Personalizados e Interfaces de Error - diseño de tipos para As
• Trazas de Pila con runtime/debug - adjuntar diagnósticos a errores envueltos
• Manejo de Errores en Código Concurrente - unir errores de goroutines
• Mejores Prácticas de Manejo de Errores - política de envoltura para equipos

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de GC Green Tea, 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).