Golang Errors: Wrap, errors.Is, errors.As und eigene Fehlertypen

Drei Arten von Fehlern

Go-Code verwendet drei Formen von Fehlern, von der einfachsten zur reichhaltigsten:

1. Ein Ad-hoc-Fehler: errors.New("...") oder fmt.Errorf("..."), an Ort und Stelle erzeugt. Aufrufer können nur die Meldung lesen.
2. Ein Sentinel-Fehler: eine Variable auf Paketebene wie io.EOF. Aufrufer können mit errors.Is darauf prüfen.
3. Ein Fehlertyp: ein Struct mit einer Methode Error(), das Felder trägt. Aufrufer können ihn mit errors.As herausholen und die Felder lesen.

Nimm die einfachste Form, mit der Aufrufer tun können, was sie brauchen.

Sentinel-Fehler

Ein Sentinel ist ein Fehlerwert, der einmal deklariert und über seine Identität verglichen wird. Per Konvention beginnen die Namen mit 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)
		}
	}
}

Ausgabe:

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

Zwei Aufrufe von errors.New mit demselben Text erzeugen verschiedene Fehler: errors.New("x") == errors.New("x") ist false. Deshalb muss ein Sentinel eine einzige geteilte Variable sein.

Sentinels werden Teil der API deines Pakets. Sobald Aufrufer auf ErrNotFound prüfen, kannst du nicht aufhören, ihn zurückzugeben, ohne sie zu brechen. Exportiere nur die, nach denen Aufrufer wirklich verzweigen müssen.

Eigene Fehlertypen

Braucht der Aufrufer Details (welches Feld, welcher Statuscode, welche Wartezeit bis zum Retry), definier einen 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)
	}
}

Ausgabe:

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

Die Methode hat einen Pointer Receiver, und die Funktion gibt &ValidationError{...} zurück, also ist das Ziel für errors.As ein *ValidationError, und du übergibst dessen Adresse (&ve, ein **ValidationError). Diese Ebene falsch zu treffen ist der klassische Fehler bei errors.As: Mit einem Value Receiver würdest du ValidationError{...} zurückgeben und var ve ValidationError deklarieren. go vet findet den häufigsten Ausrutscher, ve statt &ve zu übergeben: second argument to errors.As must be a non-nil pointer to either a type that implements error, or to any interface type.

Wrappen mit %w

fmt.Errorf mit %w gibt einen Fehler zurück, der sich an den gewrappten erinnert. Jede Schicht fügt Kontext hinzu und hält die Kette intakt.

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

Ausgabe:

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

Mit %v ist die Meldung dieselbe, aber die Kette ist unterbrochen, also gibt errors.Is false zurück. Nimm %w, wenn Aufrufer die Ursache sehen sollen, und %v, wenn die Ursache ein Implementierungsdetail ist, von dem sie nicht abhängen sollen.

Seit Go 1.20 kann ein Aufruf mehrere Fehler wrappen: fmt.Errorf("%w; %w", err1, err2). errors.Is trifft dann auf jeden der beiden.

errors.Join: mehrere Fehler auf einmal

Validierung und Aufräumen erzeugen oft mehr als einen Fehler. errors.Join (Go 1.20) bündelt sie.

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

Ausgabe:

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

errors.Join gibt nil zurück, wenn jedes Argument nil ist, also braucht die Funktion oben keinen Sonderfall für „keine Fehler“.

Unwrap- und Is-Methoden

errors.Is und errors.As finden gewrappte Fehler, indem sie eine Methode Unwrap aufrufen. Ein eigener Typ, der eine Ursache enthält, sollte sie herausgeben:

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
}

Ein Typ, der mehrere Fehler wrappt, implementiert stattdessen Unwrap() []error.

Ein Typ kann auch Is(target error) bool definieren, um selbst über Gleichheit zu entscheiden, etwa um jeden *HTTPError mit demselben Statuscode zu treffen. Das brauchst du selten; einen Sentinel zu wrappen und ihn aus Unwrap zurückzugeben reicht meist.

Die Falle mit dem typisierten nil

Deklarier nie eine Fehlervariable mit deinem konkreten Typ und gib sie über error zurück:

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

Das if err != nil des Aufrufers ist wahr, weil ein Interface, das einen typisierten nil-Pointer enthält, nicht nil ist. Gib bei Erfolg ein wörtliches nil zurück und typisiere lokale Fehlervariablen als error. Die Seite zu Interfaces erklärt warum.

Welche Art du wählen solltest

Häufige Fehler

• Gewrappte Fehler mit == vergleichen. Nimm errors.Is.
• Einen Nicht-Pointer an errors.As übergeben. Es braucht einen Pointer auf eine Variable des Zieltyps.
• Einen „Sentinel“ in einer Funktion erzeugen. return errors.New("not found") erzeugt bei jedem Aufruf einen neuen Wert; Aufrufer können nicht dagegen vergleichen.
• Jeden Fehler exportieren. Jeder exportierte Sentinel und jeder exportierte Typ ist ein API-Versprechen.
• Auf err.Error() prüfen. Strings sind für Menschen.