Erros em Golang: empacotar, errors.Is, errors.As e tipos próprios

Três tipos de erro

Código Go usa três formatos de erro, do mais simples ao mais rico:

1. Um erro avulso: errors.New("...") ou fmt.Errorf("...") criado na hora. Quem chama só consegue ler a mensagem.
2. Um erro sentinela: uma variável de nível de pacote como io.EOF. Quem chama pode testá-lo com errors.Is.
3. Um tipo de erro: uma struct com um método Error(), carregando campos. Quem chama pode extraí-lo com errors.As e ler os campos.

Escolha o mais simples que permita a quem chama fazer o que precisa.

Erros sentinela

Um sentinela é um valor de erro declarado uma vez e comparado por identidade. Por convenção, os nomes começam com 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)
		}
	}
}

Saída:

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

Duas chamadas de errors.New com o mesmo texto geram erros diferentes: errors.New("x") == errors.New("x") é false. Por isso um sentinela precisa ser uma única variável compartilhada.

Sentinelas passam a fazer parte da API do seu pacote. Depois que quem chama verifica ErrNotFound, você não pode parar de devolvê-lo sem quebrar esse código. Exporte só os que quem chama realmente precisa para tomar decisões.

Tipos de erro personalizados

Quando quem chama precisa de detalhes (qual campo, qual código de status, quanto esperar antes de tentar de novo), defina um 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)
	}
}

Saída:

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

O método tem receiver ponteiro e a função devolve &ValidationError{...}, então o alvo do errors.As é um *ValidationError, e você passa o endereço dele (&ve, um **ValidationError). Errar esse nível é o erro clássico com errors.As: com receiver de valor, você devolveria ValidationError{...} e declararia var ve ValidationError. O go vet pega o deslize mais comum, passar ve em vez 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.

Empacotando com %w

fmt.Errorf com %w devolve um erro que se lembra daquele que empacota. Cada camada acrescenta contexto e mantém a cadeia 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))
}

Saída:

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

Com %v a mensagem é a mesma, mas a cadeia é cortada, então errors.Is devolve false. Escolha %w quando quem chama deve conseguir ver a causa, e %v quando a causa é um detalhe de implementação do qual você não quer que dependam.

Desde o Go 1.20, uma chamada pode empacotar vários erros: fmt.Errorf("%w; %w", err1, err2). errors.Is então casa com qualquer um dos dois.

errors.Join: vários erros de uma vez

Validação e limpeza muitas vezes geram mais de um erro. O errors.Join (Go 1.20) os 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)
}

Saída:

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

errors.Join devolve nil quando todos os argumentos são nil, então a função acima não precisa de um caso especial para "nenhum erro".

Métodos Unwrap e Is

errors.Is e errors.As encontram erros empacotados chamando um método Unwrap. Um tipo próprio que guarda uma causa deve expô-la:

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
}

Um tipo que empacota vários erros implementa Unwrap() []error no lugar.

Um tipo também pode definir Is(target error) bool para decidir a igualdade por conta própria, por exemplo para casar qualquer *HTTPError com o mesmo código de status. Você raramente precisa disso; empacotar um sentinela e devolvê-lo em Unwrap normalmente resolve.

A armadilha do nil tipado

Nunca declare uma variável de erro com o seu tipo concreto e a devolva como error:

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

O if err != nil de quem chama dá verdadeiro, porque uma interface que guarda um ponteiro nil tipado não é nil. Devolva um nil literal em caso de sucesso e mantenha as variáveis locais de erro com o tipo error. A página de interfaces explica o porquê.

Qual tipo escolher

Erros comuns

• Comparar erros empacotados com ==. Use errors.Is.
• Passar algo que não é ponteiro para o errors.As. Ele precisa de um ponteiro para uma variável do tipo alvo.
• Criar um "sentinela" dentro de uma função. return errors.New("not found") cria um valor novo a cada chamada; quem chama não consegue comparar com ele.
• Exportar todos os erros. Cada sentinela ou tipo exportado é uma promessa de API.
• Comparar pelo err.Error(). Strings são para humanos.