Ошибки как API: sentinel-ы, типы, контракт Is/As и %w, который сливает ваши внутренности

Три вида ошибок, которые можно пообещать

Ошибка, возвращаемая экспортированной функцией, — такой же API, как остальные её результаты, и предложить можно ровно три контракта. Sentinel (дозорное значение — экспортированная переменная с фиксированной идентичностью) — экспортированное значение уровня пакета: io.EOF, sql.ErrNoRows, ваш ErrNotFound — обещает одну сравнимую идентичность, которую потребители проверяют через errors.Is. Дёшево в предоставлении, но не несёт данных и остаётся навсегда: его нельзя раз-экспортировать, и каждый путь кода, который его возвращает, прибит к этому смыслу. Типизированная ошибка — экспортированная структура или интерфейс, реализующий error: *fs.PathError, ваш *RateLimitError — извлекается через errors.As и несёт структурные поля вроде RetryAfter. Самый богатый контракт и самый дорогой: его поля и семантика версионируются, как любая публичная структура. Опаковая ошибка не обещает ничего, кроме не-nil — потребитель может её залогировать, но не может на ней ветвиться. Опаковость — тот дефолт, за который стоит драться: каждый экспортированный sentinel и тип — поверхность, которую вы поддерживаете между версиями, поэтому вопрос дизайна никогда не «какие у меня есть ошибки», а «какие решения должны принимать мои вызывающие». Тем, кому нужен только успех/провал, — опаковая; тем, кто ветвится (ретраить? 404? какой бэкофф?), — минимальный sentinel или тип, поддерживающий ветку. Полезный средний путь — поведенческий интерфейс (behaviour interface): экспортировать только проверку способности в духе interface{ Timeout() bool }, позволяя задать вопрос без привязки к конкретной идентичности. Когда проектируешь новую экспортированную функцию, спроси себя: какое решение моему вызывающему реально нужно принять? Этот вопрос почти всегда сам указывает, какая из трёх форм нужна.

errors.Is и errors.As — контракт; оборачивание — водопровод

С Go 1.13 fmt.Errorf с %w записывает обёрнутую ошибку, а errors.Is/errors.As обходят получившуюся цепочку: Is сравнивает идентичности звено за звеном, As находит первое звено, присваиваемое целевому типу. Именно этот обход вы обещаете, когда документируете «возвращает ErrNotFound, если не найдено», — а не err == ErrNotFound, который ломается, как только кто-нибудь добавит контекст через %w посередине. Полный контракт в коде:

// Пакет user — API ошибок: спроектирован, задокументирован, протестирован.
var ErrNotFound = errors.New("user: not found") // sentinel: экспортирован навсегда

type RateLimitError struct { // типизированная: несёт данные для ветвления
	RetryAfter time.Duration
}

func (e *RateLimitError) Error() string {
	return fmt.Sprintf("user: rate limited, retry after %s", e.RetryAfter)
}

// Сторона потребителя — единственные две проверки, которых должна требовать дока:
if errors.Is(err, user.ErrNotFound) { /* 404, без ретрая */ }

var rl *user.RateLimitError
if errors.As(err, &rl) { backoff(rl.RetryAfter) }

Внутри своего модуля оборачивайте свободно — fmt.Errorf("load profile %s: %w", id, err) добавляет контекст, делающий логи отлаживаемыми, сохраняя работу Is/As сквозь цепочку. Дисциплинарный пункт: оборачивание — это транзитивная видимость: всё, что достижимо по звеньям %w, потребитель может тестировать — ровно об этом следующий раздел.

Дисциплина оборачивания на границах: %w сливает внутренности

Вот ловушка senior-уровня. Ваш слой хранилища делает return fmt.Errorf("get user: %w", sql.ErrNoRows), и ошибка пересекает границу пакета. Вы только что необратимо опубликовали, что ваш пакет работает поверх database/sql: любой потребитель теперь может написать errors.Is(err, sql.ErrNoRows), какой-нибудь потребитель со временем напишет (снова Хайрам), и ваша миграция на кеш или другой драйвер станет его breaking change — зависимость, которую вы не объявляли ни в одном интерфейсе. Отсюда правило: на границе пакета ошибки переводят, а не пробрасывают. Отобразите внутренние сбои на свой опубликованный словарь; оборачивайте %w свой sentinel, а внутреннюю причину запечатывайте %v — текст для логов сохраняется, цепочка обрезается:

func (s *Store) Get(ctx context.Context, id string) (*User, error) {
	u, err := s.db.GetUser(ctx, id)
	switch {
	case errors.Is(err, sql.ErrNoRows):
		return nil, fmt.Errorf("get user %s: %w", id, ErrNotFound) // ваш словарь
	case err != nil:
		return nil, fmt.Errorf("get user %s: %v", id, err) // %v запечатывает: текст есть, цепочки нет
	}
	return u, nil
}

Выбор между %w и %v — таким образом, решение об API, а не предпочтение форматирования: %w означает «я поддерживаю Is/As по всему, что за этим звеном, навсегда»; %v — «контекст для людей, без контракта». Мульти-оборачивание Go 1.20 (errors.Join, несколько глаголов %w) расширяет ту же дверь — каждая присоединённая ошибка достижима для Is/As, — так что правило границы применяется к каждой ветви. Внутри модуля — по умолчанию %w; на экспортированной поверхности — по умолчанию перевод.

Стабильность между версиями: текст ошибки — не API, но кто-то думает иначе

Контракт, который стоит документировать и тестировать, невелик: какие существуют sentinel-ы, какие типы, какие функции могут их вернуть — в doc-комментариях на каждом (конвенция // Get возвращает ошибку, удовлетворяющую errors.Is(err, ErrNotFound), когда… проверяется машинно в тесте). А дальше держите оборону на том, что контрактом не является: текст сообщений. Вы не запретите потребителю матчить строки — у потребителя из Hook были причины, даже приличные, — но вы можете сделать матчинг текста ненужным (каждая задокументированная ветка достижима через Is/As) и можете отказаться считать формулировки замороженными. Правила версионирования, следующие из механики: удалить или переименовать sentinel, либо сузить случаи его возврата — мажорный брейк; добавить поле в типизированную ошибку — можно, поменять смысл поля — нельзя; перевести путь с возврата вашего sentinel-а на оборачивание чужого — снова утечка. И напишите тест, пришпиливающий обещание — errors.Is(Get(ctx, missing), ErrNotFound) через вашу настоящую цепочку обёрток, — потому что цепочка собирается вызовами fmt.Errorf, рассыпанными по кодовой базе, и один коллега, «улучшивший» %w до %v (или наоборот), молча переписывает ваш публичный API.