Оборачивание ошибок в Go

Цепочка держится на %w

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

С %v такого не происходит. Ошибка превращается в текст, и текст этот выглядит совершенно так же - разница видна только программно. Проверено: errors.Is по цепочке, собранной через %w, возвращает true, а по такой же на вид строке через %v - false. Одна буква в формате, и обработка выше ломается молча.

errors.Unwrap снимает ровно один слой. Ходить по цепочке руками почти никогда не нужно: errors.Is и errors.As делают это сами, до самого дна.

// С Go 1.20 в одном Errorf можно указать несколько %w сразу - проверено, errors.Is находит обе обёрнутые ошибки. Удобно, когда операция провалилась по двум причинам одновременно.

err := fmt.Errorf("слой репозитория: %w",
        fmt.Errorf("слой драйвера: %w", ErrNotFound))

err.Error()                     // слой репозитория: слой драйвера: не найдено
errors.Is(err, ErrNotFound)     // true  - цепочка цела
errors.Unwrap(err)              // слой драйвера: не найдено (один слой)

bad := fmt.Errorf("через %v", ErrNotFound)
errors.Is(bad, ErrNotFound)     // false - текст тот же, связи нет

%w

глагол fmt.Errorf, который сохраняет исходную ошибку в цепочке; %v оставляет только текст

Is ищет значение, As ищет тип

errors.Is отвечает на вопрос «это та самая ошибка?». Идёт по цепочке и сравнивает каждое звено с эталоном. Применяют к sentinel-значениям: ErrNotFound, sql.ErrNoRows, io.EOF (end of file, признак конца потока), os.ErrPermission.

errors.As отвечает на вопрос «есть ли в цепочке ошибка такого типа, и если да, дай её мне». Вторым аргументом передают указатель на переменную нужного типа, туда кладётся найденное звено. Применяют, когда из ошибки нужны детали: код ответа, номер поля, имя таблицы.

Проверено: для ошибки, обёрнутой поверх &MyErr{Code: 404}, errors.As возвращает true и заполняет переменную, после чего Code читается как обычное поле. Именно за этим As и нужен - Is сказал бы только «да или нет».

// Прямое сравнение err == ErrNotFound работает, только пока ошибку никто не обернул. Как только между слоями появится хоть один Errorf с %w, сравнение начнёт возвращать false, а errors.Is продолжит работать. Поэтому в новом коде пишут Is сразу, даже когда обёрток пока нет.

var me *MyErr
if errors.As(err, &me) {
    log.Printf("код ответа: %d", me.Code)   // 404 - детали доступны
}

if errors.Is(err, ErrNotFound) {
    return http.StatusNotFound
}

Join и границы оборачивания

errors.Join собирает несколько независимых ошибок в одну. Проверено: текст получается склейкой через перевод строки, а errors.Is находит каждую из вложенных. Естественное применение - валидация формы, где надо вернуть все нарушения сразу, а не первое попавшееся.

Теперь про границу. Оборачивание с %w делает исходную ошибку частью публичного контракта: пользователи начнут писать errors.Is на неё, и убрать её ты уже не сможешь, не сломав их код. Ошибку драйвера базы, случайно протёкшую наружу через %w, придётся поддерживать вечно.

Поэтому на границе пакета решают осознанно: наружу отдаём свою ошибку через %v или через собственный sentinel, а внутренние детали оставляем внутри. Оборачиваем через %w только то, что действительно хотим показать наружу как часть контракта.

// Практическое следствие: внутри пакета оборачивай смело, на публичном API - подумав. Вопрос простой: захотят ли пользователи различать эту причину программно? Если да - %w и документируй. Если нет - %v.

errors.Join

объединяет несколько ошибок в одну; Is находит каждую, текст склеивается переводами строк

Как отвечать: «Чем %w отличается от %v и когда Is, а когда As?»

%w встраивает исходную ошибку в цепочку и добавляет метод Unwrap, а %v просто вставляет её текст. Внешне строка получается одинаковой, и в этом главная опасность: с %v errors.Is перестаёт находить ошибку, я это проверял - на одинаковых на вид строках Is возвращает true и false соответственно. То есть обработка наверху ломается молча, без единого предупреждения компилятора. Дальше выбор между Is и As зависит от вопроса. Is отвечает «это та самая ошибка?» - для sentinel-значений вроде sql.ErrNoRows или io.EOF. As отвечает «есть ли в цепочке ошибка такого типа, дай её мне» - когда нужны детали: код, номер поля, имя таблицы. Оба идут по всей цепочке до дна, руками Unwrap звать почти никогда не нужно. Прямое сравнение через двойное равно я стараюсь не использовать: оно ломается от первой же обёртки. И держу в голове границу: обёртка через %w делает вложенную ошибку частью публичного контракта, поэтому наружу пакета так пробрасываю только то, что готов поддерживать.

Разница названа механизмом и подтверждена проверкой, критерий выбора между Is и As сформулирован вопросом, и добавлено рассуждение про контракт - его на собеседовании слышат редко.

На чём валят

• −Пишут %v вместо %w и молча ломают errors.Is у всех, кто выше.
• −Сравнивают ошибки через двойное равно - первая же обёртка ломает сравнение.
• −Берут Is там, где нужны детали, и остаются без кода ошибки.
• −Передают в As значение вместо указателя на переменную нужного типа.
• −Оборачивают через %w внутренние ошибки на публичном API и обрекают себя их поддерживать.
• −Не знают про errors.Join и возвращают из валидации только первую ошибку.