Errores en Golang: wrap, errors.Is, errors.As y tipos propios

Tres clases de errores

El código Go usa tres formas de error, de la más simple a la más rica:

1. Un error improvisado: errors.New("...") o fmt.Errorf("...") creado en el momento. Quien llama solo puede leer el mensaje.
2. Un error centinela: una variable a nivel de paquete como io.EOF. Quien llama puede comprobarlo con errors.Is.
3. Un tipo de error: un struct con un método Error() que lleva campos. Quien llama puede extraerlo con errors.As y leer los campos.

Elige la más simple que permita a quien llama hacer lo que necesita.

Errores centinela

Un centinela es un valor de error que se declara una vez y se compara por identidad. Por convención, los nombres empiezan por Err.

package main

import (
	"errors"
	"fmt"
)

var (
	ErrNotFound   = errors.New("not found")
	ErrOutOfStock = errors.New("out of stock")
)

var stock = map[string]int{"mug": 3, "cap": 0}

func buy(item string) error {
	n, ok := stock[item]
	if !ok {
		return fmt.Errorf("buy %q: %w", item, ErrNotFound)
	}
	if n == 0 {
		return fmt.Errorf("buy %q: %w", item, ErrOutOfStock)
	}
	stock[item]--
	return nil
}

func main() {
	for _, item := range []string{"mug", "cap", "hat"} {
		err := buy(item)
		switch {
		case err == nil:
			fmt.Println(item, "bought")
		case errors.Is(err, ErrOutOfStock):
			fmt.Println(item, "is out of stock, notify me later")
		case errors.Is(err, ErrNotFound):
			fmt.Println(err)
		}
	}
}

Salida:

mug bought
cap is out of stock, notify me later
buy "hat": not found

Dos llamadas a errors.New con el mismo texto producen errores distintos: errors.New("x") == errors.New("x") es false. Por eso un centinela tiene que ser una única variable compartida.

Los centinelas pasan a formar parte de la API de tu paquete. Una vez que quien llama comprueba ErrNotFound, no puedes dejar de devolverlo sin romper su código. Exporta solo los que realmente se necesitan para tomar decisiones.

Tipos de error propios

Cuando quien llama necesita detalles (qué campo, qué código de estado, qué espera antes de reintentar), define un tipo.

package main

import (
	"errors"
	"fmt"
)

type ValidationError struct {
	Field  string
	Reason string
}

func (e *ValidationError) Error() string {
	return fmt.Sprintf("%s: %s", e.Field, e.Reason)
}

func validateAge(age int) error {
	if age < 0 || age > 150 {
		return &ValidationError{Field: "age", Reason: "must be between 0 and 150"}
	}
	return nil
}

func register(age int) error {
	if err := validateAge(age); err != nil {
		return fmt.Errorf("register: %w", err)
	}
	return nil
}

func main() {
	err := register(200)
	fmt.Println(err)

	var ve *ValidationError
	if errors.As(err, &ve) {
		fmt.Println("bad field:", ve.Field)
	}
}

Salida:

register: age: must be between 0 and 150
bad field: age

El método tiene un receptor puntero y la función devuelve &ValidationError{...}, así que el destino de errors.As es un *ValidationError y pasas su dirección (&ve, un **ValidationError). Equivocarse en ese nivel es el error clásico con errors.As: con un receptor por valor devolverías ValidationError{...} y declararías var ve ValidationError. go vet detecta el despiste más común, pasar ve en lugar de &ve: second argument to errors.As must be a non-nil pointer to either a type that implements error, or to any interface type.

Envolver con %w

fmt.Errorf con %w devuelve un error que recuerda al que envuelve. Cada capa añade contexto y mantiene la cadena intacta.

package main

import (
	"errors"
	"fmt"
)

var ErrTimeout = errors.New("timeout")

func dial() error    { return ErrTimeout }
func connect() error { return fmt.Errorf("connect db: %w", dial()) }
func start() error   { return fmt.Errorf("start: %w", connect()) }

func main() {
	err := start()
	fmt.Println(err)

	// Walk the chain by hand.
	for e := err; e != nil; e = errors.Unwrap(e) {
		fmt.Printf("  %T: %v\n", e, e)
	}

	fmt.Println(errors.Is(err, ErrTimeout))

	hidden := fmt.Errorf("start: %v", connect()) // %v: text only
	fmt.Println(errors.Is(hidden, ErrTimeout))
}

Salida:

start: connect db: timeout
  *fmt.wrapError: start: connect db: timeout
  *fmt.wrapError: connect db: timeout
  *errors.errorString: timeout
true
false

Con %v el mensaje es el mismo pero la cadena se corta, así que errors.Is devuelve false. Elige %w cuando quien llama deba poder ver la causa, y %v cuando la causa sea un detalle de implementación del que no quieres que dependa.

Desde Go 1.20, una sola llamada puede envolver varios errores: fmt.Errorf("%w; %w", err1, err2). errors.Is coincide entonces con cualquiera de los dos.

errors.Join: varios errores a la vez

La validación y la limpieza suelen producir más de un error. errors.Join (Go 1.20) los agrupa.

package main

import (
	"errors"
	"fmt"
)

var ErrRequired = errors.New("required")

type Form struct {
	Name, Email string
	Age         int
}

func (f Form) Validate() error {
	var errs []error
	if f.Name == "" {
		errs = append(errs, fmt.Errorf("name: %w", ErrRequired))
	}
	if f.Email == "" {
		errs = append(errs, fmt.Errorf("email: %w", ErrRequired))
	}
	if f.Age < 0 {
		errs = append(errs, errors.New("age: negative"))
	}
	return errors.Join(errs...) // nil when errs is empty
}

func main() {
	err := Form{Age: -1}.Validate()
	fmt.Println(err)
	fmt.Println("---")
	fmt.Println(errors.Is(err, ErrRequired))
	fmt.Println(Form{Name: "Ana", Email: "a@x.com"}.Validate() == nil)
}

Salida:

name: required
email: required
age: negative
---
true
true

errors.Join devuelve nil cuando todos los argumentos son nil, así que la función anterior no necesita un caso especial para "sin errores".

Métodos Unwrap e Is

errors.Is y errors.As encuentran errores envueltos llamando a un método Unwrap. Un tipo propio que guarda una causa debería exponerla:

package main

import (
	"errors"
	"fmt"
	"io/fs"
	"os"
)

type QueryError struct {
	Query string
	Err   error
}

func (e *QueryError) Error() string { return "query " + e.Query + ": " + e.Err.Error() }
func (e *QueryError) Unwrap() error { return e.Err }

func main() {
	_, openErr := os.Open("/no/such/db")
	err := &QueryError{Query: "SELECT 1", Err: openErr}

	fmt.Println(err)
	fmt.Println(errors.Is(err, fs.ErrNotExist)) // found through Unwrap
}

Un tipo que envuelve varios errores implementa Unwrap() []error en su lugar.

Un tipo también puede definir Is(target error) bool para decidir la igualdad por sí mismo, por ejemplo para coincidir con cualquier *HTTPError con el mismo código de estado. Rara vez hace falta; envolver un centinela y devolverlo desde Unwrap suele bastar.

La trampa del nil con tipo

Nunca declares una variable de error con tu tipo concreto para devolverla como error:

func check() error {
	var err *ValidationError // nil pointer
	// ... no problem found
	return err // non-nil error! Its type is *ValidationError
}

El if err != nil de quien llama es verdadero, porque una interfaz que contiene un puntero nil con tipo no es nil. Devuelve un nil literal cuando todo va bien, y declara las variables locales de error con el tipo error. La página de interfaces explica por qué.

Qué clase elegir

Errores comunes

• Comparar errores envueltos con ==. Usa errors.Is.
• Pasar algo que no es un puntero a errors.As. Necesita un puntero a una variable del tipo de destino.
• Crear un "centinela" dentro de una función. return errors.New("not found") crea un valor nuevo en cada llamada; quien llama no puede compararlo.
• Exportar todos los errores. Cada centinela o tipo exportado es una promesa de API.
• Comparar con err.Error(). Los strings son para las personas.