Sentinel и свои типы ошибок в Go

Sentinel: одно значение на пакет

Sentinel - переменная уровня пакета, созданная через errors.New один раз при запуске: var ErrNotFound = errors.New("не найдено"). Она сравнивается по идентичности, поэтому важна именно та самая переменная, а не другая с тем же текстом.

Проверяют через errors.Is - он пройдёт цепочку обёрток и найдёт эталон на любой глубине. Именно так устроены sql.ErrNoRows, io.EOF (end of file, признак конца потока), os.ErrNotExist: ты сравниваешь с известным значением и точно знаешь, что случилось.

Ограничение очевидно из устройства: sentinel несёт только факт. Какое поле не прошло проверку, какой идентификатор не нашёлся, сколько осталось попыток - всё это в него не помещается.

// Объявляй sentinel-ошибки экспортируемыми и с префиксом Err - это устоявшаяся конвенция, по которой их узнают. И помни, что публичный sentinel - часть контракта пакета: убрать его потом нельзя, кто-то уже написал на него проверку.

var ErrNotFound = errors.New("не найдено")

// в глубине пакета
return fmt.Errorf("пользователь %d: %w", id, ErrNotFound)

// у вызывающего
if errors.Is(err, ErrNotFound) { return http.StatusNotFound }

Свой тип: факт плюс детали

Когда нужны подробности, объявляют структуру с методом Error() string. Внутри - всё, что понадобится вызывающему: поле, значение, код ответа, время до следующей попытки.

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

Одна деталь ловит новичков: метод Error объявляют на указателе, значит и в цепочке лежит *MyErr, и в As надо передавать указатель на переменную типа *MyErr. Смешение получателя-значения и получателя-указателя тут даёт «ошибка не находится», хотя она есть.

// Если типов ошибок в пакете много, их часто объединяют одним интерфейсом с дополнительным методом - например Temporary() bool или Code() int. Тогда вызывающий проверяет через As по интерфейсу и не зависит от конкретных структур.

type ValidationError struct {
    Field string
    Value any
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("поле %s: недопустимое значение %v", e.Field, e.Value)
}

var ve *ValidationError
if errors.As(err, &ve) {
    highlight(ve.Field)   // подсветить именно это поле формы
}

Что выбрать

Правило простое: нужен только факт - sentinel, нужны детали - свой тип. «Записи нет» это чистый факт, тут sentinel. «Поле email не прошло проверку» это факт с деталями, тут структура.

Не плоди сущности заранее. Три десятка sentinel-значений на пакет - признак того, что автор пытался предусмотреть каждый случай; пользователи всё равно проверяют два-три из них. Начинай с одного-двух и добавляй по реальному спросу.

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

// Отдельный частый случай - временные ошибки. Если вызывающему нужно решать, повторять ли запрос, дай ему способ это узнать: свой тип с методом или отдельный sentinel. Иначе он будет повторять всё подряд, включая ошибки валидации, которые не исправятся никогда.

Как отвечать: «Sentinel или свой тип ошибки - что выбрать?»

Смотрю, нужен ли вызывающему только факт или ещё и подробности. Если факт - беру sentinel: переменная уровня пакета через errors.New, экспортируемая, с префиксом Err, проверяется через errors.Is. Так устроены sql.ErrNoRows и io.EOF, и это самый дешёвый вариант. Если нужны детали - какое поле не прошло, какой код вернул сервис, через сколько повторять - делаю структуру с методом Error и достаю её через errors.As. Тогда у вызывающего обычные поля, а не разбор текста. Метод Error я объявляю на указателе и помню, что в As надо передавать указатель на переменную типа указателя, иначе ошибка просто не найдётся. Чего стараюсь избегать: тридцати sentinel-значений на пакет заранее - реально проверяют два-три, остальные превращаются в контракт, который придётся тащить. И внутренние ошибки наружу через %w не пробрасываю: заворачиваю в свою, чтобы никто не завязался на детали реализации.

Критерий выбора сформулирован одним вопросом, названы конвенции и способ проверки для обоих вариантов, и упомянута ловушка с получателем-указателем в As.

На чём валят

• −Сравнивают ошибки по тексту вместо sentinel или своего типа.
• −Объявляют sentinel внутри функции, и каждое обращение создаёт новое значение.
• −Берут sentinel там, где вызывающему нужны детали, и заставляют его парсить строку.
• −Путают получатель метода Error и передают в As указатель не того уровня.
• −Заводят три десятка ошибок заранее и превращают их все в публичный контракт.
• −Не дают способа отличить временную ошибку от постоянной - и клиент повторяет всё подряд.