Обработка ошибок в Go: обёртывание с %w, errors.Is и errors.As

Что это такое

В Go ошибкой является любое значение, тип которого имеет метод Error() string; функции возвращают его последним результатом, а nil означает успех. Исключений нет: Go FAQ объясняет этот подход возвратом нескольких значений для обычных сбоев и механизмами panic/recover для действительно исключительных условий. Начиная с Go 1.13 ошибки образуют цепочку. fmt.Errorf("open config: %w", err) возвращает ошибку, реализующую Unwrap() error, а документация пакета errors описывает обход этого дерева функциями errors.Is и errors.As: сначала сама ошибка, затем её потомки, в глубину. Is сравнивает с целевым значением, а As находит первую ошибку, присваиваемую целевому типу, и копирует её в целевую переменную. errors.Join (Go 1.20) и fmt.Errorf с несколькими спецификаторами %w создают ошибки, чей метод Unwrap возвращает []error. В Go 1.26 добавлена обобщённая функция errors.AsType[E](err), возвращающая типизированное значение и логическое значение.

Почему это важно

После Python или JavaScript привычно окружать блок конструкцией try/except; в Go решение принимается в каждом месте вызова. Здесь не работают две привычки из динамических языков: сравнение строк err.Error(), меняющихся при добавлении контекста на любом уровне, и проверка err == ErrNotFound оператором ==, которая перестаёт работать после обёртывания ошибки. Именно по этой причине документация рекомендует errors.Is(err, fs.ErrExist) вместо err == fs.ErrExist.

Как применять

• Объявляйте сигнальные ошибки переменными пакета (var ErrNotFound = errors.New("not found")), а структурированные ошибки — типами с полями; вызывающий код сопоставляет их через errors.Is или errors.As.
• Используйте %w, когда вызывающему коду разумно дать возможность проверить причину, и %v, когда причина является деталью реализации. Блог Go рекомендует оборачивать ошибку, чтобы открыть её вызывающему коду, и не оборачивать, если это раскроет детали реализации.
• Добавляйте контекст один раз на уровень в форме "what was being done: %w", со строчной буквы и без завершающей пунктуации, чтобы сообщения читались как цепочка от внешнего уровня к внутреннему.
• Либо обрабатывайте ошибку, либо возвращайте её: если и записывать её в журнал, и возвращать, на каждом уровне появятся повторяющиеся строки.
• Добавьте пользовательскому типу метод Is(error) bool, если он должен считаться равным существующей сигнальной ошибке; документация пакета описывает этот механизм.

Подводные камни

%v незаметно разрывает цепочку. Обёртывание ошибки nil создаёт ошибку, не равную nil. Функция, возвращающая типизированный nil-указатель как error, возвращает интерфейс, не равный nil (см. статью об интерфейсах). Возврат sql.ErrNoRows через %w из репозитория связывает вызывающий код с пакетом базы данных — этот пример взят из самого блога. panic не является универсальным механизмом ошибок: оставляйте его для ошибок программиста и применяйте восстановление только на границах горутин.