Errori in Golang: wrap, errors.Is, errors.As e tipi personalizzati

Tre tipi di errori

Il codice Go usa tre forme di errore, dalla più semplice alla più ricca:

1. Un errore ad hoc: errors.New("...") o fmt.Errorf("...") creato sul momento. Chi lo riceve può solo leggerne il messaggio.
2. Un errore sentinella: una variabile a livello di package come io.EOF. Chi lo riceve può verificarlo con errors.Is.
3. Un tipo di errore: una struct con un metodo Error() che trasporta dei campi. Chi lo riceve può estrarlo con errors.As e leggerne i campi.

Scegli la forma più semplice che permette ai chiamanti di fare ciò che serve loro.

Errori sentinella

Una sentinella è un valore di errore dichiarato una volta e confrontato per identità. Per convenzione i nomi iniziano con 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)
		}
	}
}

Output:

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

Due chiamate a errors.New con lo stesso testo producono errori diversi: errors.New("x") == errors.New("x") vale false. Per questo una sentinella deve essere un'unica variabile condivisa.

Le sentinelle diventano parte dell'API del tuo package. Una volta che i chiamanti controllano ErrNotFound, non puoi smettere di restituirlo senza rompere il loro codice. Esporta solo quelle su cui i chiamanti hanno davvero bisogno di prendere decisioni.

Tipi di errore personalizzati

Quando il chiamante ha bisogno di dettagli (quale campo, quale codice di stato, quale attesa prima di riprovare), definisci 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)
	}
}

Output:

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

Il metodo ha un receiver puntatore e la funzione restituisce &ValidationError{...}, quindi la destinazione per errors.As è un *ValidationError e ne passi l'indirizzo (&ve, un **ValidationError). Sbagliare questo livello è l'errore classico con errors.As: con un receiver per valore restituiresti ValidationError{...} e dichiareresti var ve ValidationError. go vet rileva la svista più comune, passare ve invece di &ve: second argument to errors.As must be a non-nil pointer to either a type that implements error, or to any interface type.

Wrapping con %w

fmt.Errorf con %w restituisce un errore che ricorda quello che avvolge. Ogni livello aggiunge contesto e mantiene intatta la catena.

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

Output:

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

Con %v il messaggio è lo stesso ma la catena viene interrotta, quindi errors.Is restituisce false. Scegli %w quando i chiamanti devono poter vedere la causa, %v quando la causa è un dettaglio di implementazione da cui non vuoi che dipendano.

Da Go 1.20, una chiamata può avvolgere più errori: fmt.Errorf("%w; %w", err1, err2). errors.Is trova allora una corrispondenza con l'uno o con l'altro.

errors.Join: più errori insieme

La validazione e la pulizia producono spesso più di un errore. errors.Join (Go 1.20) li raggruppa.

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

Output:

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

errors.Join restituisce nil quando tutti gli argomenti sono nil, quindi la funzione qui sopra non ha bisogno di un caso speciale per "nessun errore".

I metodi Unwrap e Is

errors.Is ed errors.As trovano gli errori avvolti chiamando un metodo Unwrap. Un tipo personalizzato che contiene una causa dovrebbe esporla:

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 che avvolge più errori implementa invece Unwrap() []error.

Un tipo può anche definire Is(target error) bool per decidere da sé l'uguaglianza, per esempio per considerare uguale qualsiasi *HTTPError con lo stesso codice di stato. Ti servirà di rado; avvolgere una sentinella e restituirla da Unwrap di solito basta.

La trappola del nil tipizzato

Non dichiarare mai una variabile di errore con il tuo tipo concreto per poi restituirla tramite error:

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

L'if err != nil del chiamante risulta vero, perché un'interfaccia che contiene un puntatore nil tipizzato non è nil. Restituisci un nil letterale in caso di successo e dichiara le variabili di errore locali con il tipo error. La pagina sulle interfacce spiega il perché.

Quale tipo scegliere

Errori comuni

• Confrontare errori avvolti con ==. Usa errors.Is.
• Passare un valore che non è un puntatore a errors.As. Serve un puntatore a una variabile del tipo di destinazione.
• Creare una "sentinella" dentro una funzione. return errors.New("not found") crea un nuovo valore a ogni chiamata; i chiamanti non possono confrontarlo.
• Esportare ogni errore. Ogni sentinella o tipo esportato è una promessa dell'API.
• Confrontare err.Error(). Le stringhe sono per le persone.