Исполняемые доки Go: Собственные ошибки

Q: Как обернуть ошибку в Go?

Используйте fmt.Errorf с глаголом %w: return fmt.Errorf("load user %d: %w", id, err). Сообщение новой ошибки включает старое, а errors.Unwrap, errors.Is и errors.As могут добраться до исходной. Начиная с Go 1.20 один вызов Errorf может обернуть несколько ошибок несколькими глаголами %w.

Q: Чем errors.Is отличается от errors.As?

errors.Is(err, target) отвечает на вопрос «есть ли это конкретное значение ошибки где-то в цепочке», для маркеров вроде io.EOF. errors.As(err, &target) отвечает на вопрос «есть ли в цепочке ошибка этого типа» и, если есть, сохраняет её в target, чтобы можно было прочитать поля.

Q: Что делает errors.Join?

errors.Join(errs...) (Go 1.20) объединяет несколько ошибок в одну. Её сообщение это отдельные сообщения, разделённые переводами строк; nil-ошибки отбрасываются, а если все аргументы nil, возвращается nil. errors.Is и errors.As срабатывают, если совпадает любая из объединённых ошибок.

Три вида ошибок

В коде на Go встречаются три формы ошибок, от простой к самой богатой:

Разовая ошибка: errors.New("...") или fmt.Errorf("..."), созданная на месте. Вызывающий код может только прочитать сообщение.
Ошибка-маркер (sentinel): переменная уровня пакета вроде io.EOF. Вызывающий код может проверить её через errors.Is.
Тип ошибки: структура с методом Error() и полями. Вызывающий код может извлечь её через errors.As и прочитать поля.

Выбирайте самую простую форму, которая позволяет вызывающему коду сделать то, что ему нужно.

Ошибки-маркеры

Маркер это значение ошибки, объявленное один раз и сравниваемое по идентичности. По соглашению имена начинаются с 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)
		}
	}
}

Вывод:

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

Два вызова errors.New с одинаковым текстом дают разные ошибки: errors.New("x") == errors.New("x") равно false. Поэтому маркер должен быть одной общей переменной.

Маркеры становятся частью API вашего пакета. Как только вызывающий код начал проверять ErrNotFound, перестать его возвращать без поломки нельзя. Экспортируйте только те, по которым вызывающему коду действительно нужно ветвиться.

Собственные типы ошибок

Когда вызывающему коду нужны подробности (какое поле, какой код статуса, какая задержка перед повтором), определите тип.

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

Вывод:

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

У метода получатель-указатель, а функция возвращает &ValidationError{...}, поэтому цель для errors.As это *ValidationError, и вы передаёте её адрес (&ve, то есть **ValidationError). Ошибиться с этим уровнем косвенности это классическая ошибка с errors.As: с получателем-значением вы бы возвращали ValidationError{...} и объявляли var ve ValidationError. Самый частый промах, передачу ve вместо &ve, ловит go vet: second argument to errors.As must be a non-nil pointer to either a type that implements error, or to any interface type.

Оборачивание через %w

fmt.Errorf с %w возвращает ошибку, которая помнит ту, что обёрнута. Каждый слой добавляет контекст и сохраняет цепочку.

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

Вывод:

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

С %v сообщение то же, но цепочка обрывается, поэтому errors.Is возвращает false. Выбирайте %w, когда вызывающий код должен видеть причину, и %v, когда причина это деталь реализации, от которой он не должен зависеть.

Начиная с Go 1.20 один вызов может обернуть несколько ошибок: fmt.Errorf("%w; %w", err1, err2). Тогда errors.Is совпадает с любой из них.

errors.Join: несколько ошибок сразу

Проверка данных и очистка ресурсов часто дают больше одной ошибки. errors.Join (Go 1.20) собирает их вместе.

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

Вывод:

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

errors.Join возвращает nil, когда все аргументы nil, поэтому функции выше не нужен особый случай для «ошибок нет».

Методы Unwrap и Is

errors.Is и errors.As находят обёрнутые ошибки, вызывая метод Unwrap. Собственный тип, который хранит причину, должен её отдавать:

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
}

Тип, который оборачивает несколько ошибок, вместо этого реализует Unwrap() []error.

Тип может также определить Is(target error) bool, чтобы самому решать, что считать равенством, например совпадение любого *HTTPError с тем же кодом статуса. Это нужно редко; обычно достаточно обернуть маркер и возвращать его из Unwrap.

Ловушка типизированного nil

Никогда не объявляйте переменную ошибки со своим конкретным типом, чтобы потом вернуть её как error:

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

if err != nil в вызывающем коде даст true, потому что интерфейс с типизированным nil-указателем не равен nil. При успехе возвращайте литерал nil, а локальные переменные ошибок объявляйте с типом error. Почему так, объясняет страница об интерфейсах.

Что выбрать

Вызывающему коду нужно	Что предоставить
только залогировать или показать сбой	`fmt.Errorf("...: %w", err)`
ветвиться по одному конкретному условию	маркер `var ErrX = errors.New(...)`
прочитать подробности сбоя	тип ошибки с полями
увидеть несколько независимых сбоев	`errors.Join`

Частые ошибки

Сравнение обёрнутых ошибок через ==. Используйте errors.Is.
Передача в errors.As не указателя. Нужен указатель на переменную целевого типа.
«Маркер», созданный внутри функции. return errors.New("not found") при каждом вызове создаёт новое значение; вызывающий код не сможет с ним сравнить.
Экспорт каждой ошибки. Каждый экспортированный маркер или тип это обещание в API.
Сопоставление по err.Error(). Строки предназначены для людей.

Часто задаваемые вопросы

Как создать собственную ошибку в Go?

Для фиксированного условия объявите маркер на уровне пакета: var ErrNotFound = errors.New("not found"). Для ошибки, которая несёт данные, определите тип с методом Error() string: type ValidationError struct { Field string } и func (e *ValidationError) Error() string { return e.Field + " is invalid" }.

Как обернуть ошибку в Go?

Используйте fmt.Errorf с глаголом %w: return fmt.Errorf("load user %d: %w", id, err). Сообщение новой ошибки включает старое, а errors.Unwrap, errors.Is и errors.As могут добраться до исходной. Начиная с Go 1.20 один вызов Errorf может обернуть несколько ошибок несколькими глаголами %w.

Чем errors.Is отличается от errors.As?

errors.Is(err, target) отвечает на вопрос «есть ли это конкретное значение ошибки где-то в цепочке», для маркеров вроде io.EOF. errors.As(err, &target) отвечает на вопрос «есть ли в цепочке ошибка этого типа» и, если есть, сохраняет её в target, чтобы можно было прочитать поля.

Что делает errors.Join?

errors.Join(errs...) (Go 1.20) объединяет несколько ошибок в одну. Её сообщение это отдельные сообщения, разделённые переводами строк; nil-ошибки отбрасываются, а если все аргументы nil, возвращается nil. errors.Is и errors.As срабатывают, если совпадает любая из объединённых ошибок.

Связанные концепции