Błędy w Go (Golang): wrap, errors.Is, errors.As i własne typy

Trzy rodzaje błędów

Kod w Go używa trzech postaci błędów, od najprostszej do najbogatszej:

1. Błąd doraźny: errors.New("...") lub fmt.Errorf("...") utworzony na miejscu. Wywołujący mogą tylko przeczytać komunikat.
2. Błąd sentinel: zmienna na poziomie pakietu, taka jak io.EOF. Wywołujący mogą ją sprawdzić przez errors.Is.
3. Typ błędu: struktura z metodą Error(), zawierająca pola. Wywołujący mogą ją wyciągnąć przez errors.As i odczytać pola.

Wybierz najprostszą postać, która pozwala wywołującym zrobić to, czego potrzebują.

Błędy sentinel

Sentinel to wartość błędu zadeklarowana raz i porównywana przez tożsamość. Zgodnie z konwencją nazwy zaczynają się od 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)
		}
	}
}

Wynik:

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

Dwa wywołania errors.New z tym samym tekstem dają różne błędy: errors.New("x") == errors.New("x") to false. Dlatego sentinel musi być jedną wspólną zmienną.

Sentinele stają się częścią API twojego pakietu. Gdy wywołujący zaczną sprawdzać ErrNotFound, nie możesz przestać go zwracać, nie psując im kodu. Eksportuj tylko te, od których wywołujący naprawdę muszą uzależniać dalsze działanie.

Własne typy błędów

Gdy wywołujący potrzebuje szczegółów (które pole, jaki kod statusu, jakie opóźnienie przed ponowieniem), zdefiniuj typ.

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

Wynik:

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

Metoda ma odbiorcę wskaźnikowego, a funkcja zwraca &ValidationError{...}, więc celem dla errors.As jest *ValidationError i przekazujesz jego adres (&ve, czyli **ValidationError). Pomylenie tego poziomu to klasyczny błąd przy errors.As: przy odbiorcy wartościowym funkcja zwracałaby ValidationError{...}, a zmienna miałaby postać var ve ValidationError. go vet wyłapuje najczęstszą pomyłkę, czyli przekazanie ve zamiast &ve: second argument to errors.As must be a non-nil pointer to either a type that implements error, or to any interface type.

Opakowywanie przez %w

fmt.Errorf z %w zwraca błąd, który pamięta opakowany błąd. Każda warstwa dodaje kontekst i zachowuje łańcuch.

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

Wynik:

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

Z %v komunikat jest taki sam, ale łańcuch zostaje przerwany, więc errors.Is zwraca false. Wybierz %w, gdy wywołujący mają widzieć przyczynę, a %v, gdy przyczyna to szczegół implementacji, od którego nie chcesz, żeby zależeli.

Od Go 1.20 jedno wywołanie może opakować kilka błędów: fmt.Errorf("%w; %w", err1, err2). errors.Is pasuje wtedy do każdego z nich.

errors.Join: kilka błędów naraz

Walidacja i sprzątanie często dają więcej niż jeden błąd. errors.Join (Go 1.20) łączy je w paczkę.

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

Wynik:

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

errors.Join zwraca nil, gdy każdy argument jest nil, więc powyższa funkcja nie potrzebuje osobnego przypadku dla "brak błędów".

Metody Unwrap i Is

errors.Is i errors.As znajdują opakowane błędy, wywołując metodę Unwrap. Własny typ, który przechowuje przyczynę, powinien ją udostępniać:

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
}

Typ opakowujący kilka błędów implementuje zamiast tego Unwrap() []error.

Typ może też zdefiniować Is(target error) bool, żeby sam decydować o równości, na przykład żeby pasował do każdego *HTTPError z tym samym kodem statusu. Rzadko jest to potrzebne; zwykle wystarczy opakować sentinel i zwrócić go z Unwrap.

Pułapka typowanego nil

Nigdy nie deklaruj zmiennej błędu z konkretnym typem, żeby potem zwracać ją jako error:

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

U wywołującego if err != nil jest prawdą, bo interfejs zawierający typowany wskaźnik nil nie jest nil. Przy sukcesie zwracaj dosłowne nil, a lokalne zmienne błędów typuj jako error. Strona o interfejsach wyjaśnia dlaczego.

Który rodzaj wybrać

Typowe błędy

• Porównywanie opakowanych błędów przez ==. Użyj errors.Is.
• Przekazanie do errors.As czegoś, co nie jest wskaźnikiem. Funkcja potrzebuje wskaźnika na zmienną typu docelowego.
• Tworzenie "sentinela" wewnątrz funkcji. return errors.New("not found") przy każdym wywołaniu tworzy nową wartość; wywołujący nie mogą się z nią porównać.
• Eksportowanie każdego błędu. Każdy eksportowany sentinel czy typ to obietnica w API.
• Dopasowywanie po err.Error(). Stringi są dla ludzi.