Manejo de errores en Go: envolver con %w, errors.Is y errors.As

Qué es

En Go, un error es cualquier valor cuyo tipo tenga un método Error() string; las funciones lo devuelven como último resultado, y nil significa éxito. No hay excepciones: las preguntas frecuentes de Go explican el diseño como retornos de varios valores para los fallos ordinarios, más panic/recover para las condiciones verdaderamente excepcionales. Desde Go 1.13, los errores forman una cadena. fmt.Errorf("open config: %w", err) devuelve un error que implementa Unwrap() error, y la documentación del paquete errors describe cómo errors.Is y errors.As recorren ese árbol (primero un error, después sus hijos, en profundidad): Is compara contra un valor objetivo, As encuentra el primer error asignable a un tipo objetivo y lo copia hacia fuera. errors.Join (Go 1.20) y fmt.Errorf con varios verbos %w producen errores cuyo Unwrap devuelve []error. Go 1.26 añade la función genérica errors.AsType[E](err), que devuelve el valor tipado y un booleano.

Por qué importa

Viniendo de Python o de JavaScript, el reflejo es envolver un bloque en try/except; en Go, cada punto de llamada decide. Dos costumbres de los lenguajes dinámicos se rompen aquí: comparar cadenas de err.Error(), que cambian cada vez que una capa añade contexto, y comparar err == ErrNotFound con ==, que falla en cuanto el error se ha envuelto. La documentación indica que errors.Is(err, fs.ErrExist) es preferible a err == fs.ErrExist precisamente por ese motivo.

Cómo aplicarlo

• Declarar los errores centinela como variables de paquete (var ErrNotFound = errors.New("not found")) y los errores estructurados como tipos con campos; quien llama los compara con errors.Is o errors.As.
• Envolver con %w cuando quien llama pueda razonablemente inspeccionar la causa, y con %v cuando la causa sea un detalle de implementación; la guía del blog de Go es envolver un error para exponerlo a quienes llaman, y no envolverlo cuando hacerlo expondría detalles de implementación.
• Añadir contexto una vez por capa con la forma "what was being done: %w", en minúsculas y sin puntuación final, de modo que los mensajes se lean como una cadena de lo más externo a lo más interno.
• Manejar o devolver, no ambas cosas: registrar un error y también devolverlo produce líneas de log duplicadas en cada nivel.
• Dar a un tipo personalizado un método Is(error) bool cuando deba compararse como igual a un centinela existente; la documentación del paquete describe este mecanismo.

Trampas

%v rompe la cadena silenciosamente. Envolver un error nil crea un error que no es nil. Una función que devuelve un puntero nil tipado como error devuelve una interfaz que no es nil (véase el artículo sobre interfaces). Devolver sql.ErrNoRows a través de %w desde un repositorio ata a quienes llaman al paquete de base de datos, que es el propio ejemplo del blog. panic no es un mecanismo de error general; conviene reservarlo para errores de programación y recuperar solo en los límites de las goroutines.