Erreurs en Golang : wrap, errors.Is, errors.As et types personnalisés

Trois sortes d'erreurs

Le code Go utilise trois formes d'erreur, de la plus simple à la plus riche :

1. Une erreur ad hoc : errors.New("...") ou fmt.Errorf("...") créée sur place. Les appelants ne peuvent que lire le message.
2. Une erreur sentinelle : une variable au niveau du package comme io.EOF. Les appelants peuvent la tester avec errors.Is.
3. Un type d'erreur : une struct avec une méthode Error(), qui porte des champs. Les appelants peuvent l'extraire avec errors.As et lire les champs.

Choisissez la plus simple qui permet aux appelants de faire ce dont ils ont besoin.

Erreurs sentinelles

Une sentinelle est une valeur d'erreur déclarée une fois et comparée par identité. Par convention, les noms commencent par 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)
		}
	}
}

Sortie :

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

Deux appels à errors.New avec le même texte produisent des erreurs différentes : errors.New("x") == errors.New("x") vaut false. C'est pour cela qu'une sentinelle doit être une variable unique et partagée.

Les sentinelles font partie de l'API de votre package. Dès que des appelants testent ErrNotFound, vous ne pouvez plus arrêter de la renvoyer sans les casser. N'exportez que celles sur lesquelles les appelants ont réellement besoin de brancher.

Types d'erreur personnalisés

Quand l'appelant a besoin de détails (quel champ, quel code de statut, quel délai avant de réessayer), définissez un type.

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)
	}
}

Sortie :

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

La méthode a un receveur pointeur et la fonction renvoie &ValidationError{...}, donc la cible de errors.As est un *ValidationError, et vous passez son adresse (&ve, un **ValidationError). Se tromper de niveau est l'erreur classique avec errors.As : avec un receveur valeur, vous renverriez ValidationError{...} et déclareriez var ve ValidationError. go vet détecte l'étourderie la plus courante, passer ve au lieu 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.

Envelopper avec %w

fmt.Errorf avec %w renvoie une erreur qui se souvient de celle qu'elle enveloppe. Chaque couche ajoute du contexte et garde la chaîne intacte.

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))
}

Sortie :

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

Avec %v, le message est le même mais la chaîne est coupée, donc errors.Is renvoie false. Choisissez %w quand les appelants doivent pouvoir voir la cause, %v quand la cause est un détail d'implémentation dont vous ne voulez pas qu'ils dépendent.

Depuis Go 1.20, un seul appel peut envelopper plusieurs erreurs : fmt.Errorf("%w; %w", err1, err2). errors.Is trouve alors l'une ou l'autre.

errors.Join : plusieurs erreurs à la fois

La validation et le nettoyage produisent souvent plus d'une erreur. errors.Join (Go 1.20) les regroupe.

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)
}

Sortie :

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

errors.Join renvoie nil quand tous les arguments sont nil, donc la fonction ci-dessus n'a pas besoin de cas particulier pour « aucune erreur ».

Méthodes Unwrap et Is

errors.Is et errors.As trouvent les erreurs enveloppées en appelant une méthode Unwrap. Un type personnalisé qui contient une cause devrait l'exposer :

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 type qui enveloppe plusieurs erreurs implémente plutôt Unwrap() []error.

Un type peut aussi définir Is(target error) bool pour décider lui-même de l'égalité, par exemple pour correspondre à n'importe quel *HTTPError ayant le même code de statut. Vous en avez rarement besoin ; envelopper une sentinelle et la renvoyer depuis Unwrap suffit en général.

Le piège du nil typé

Ne déclarez jamais une variable d'erreur avec votre type concret pour la renvoyer via error :

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

Le if err != nil de l'appelant est vrai, parce qu'une interface contenant un pointeur nil typé n'est pas nil. Renvoyez un nil littéral en cas de succès, et gardez vos variables d'erreur locales typées error. La page sur les interfaces explique pourquoi.

Quelle sorte choisir

Erreurs courantes

• Comparer des erreurs enveloppées avec ==. Utilisez errors.Is.
• Passer autre chose qu'un pointeur à errors.As. Il faut un pointeur vers une variable du type cible.
• Créer une « sentinelle » dans une fonction. return errors.New("not found") crée une nouvelle valeur à chaque appel ; les appelants ne peuvent pas s'y comparer.
• Exporter toutes les erreurs. Chaque sentinelle ou type exporté est une promesse d'API.
• Comparer sur err.Error(). Les chaînes sont faites pour les humains.