Wiki
猫Error Handling RU
English version: Error-Handling
Это краткая русскоязычная версия страницы про централизованный поток обработки ошибок. Полная и наиболее актуальная страница: Error-Handling.
Базовая идея
В Laniakea handlers возвращают error.
Это относится к:
- обработчики команд;
- обработчики данных callback;
- обработчики обновлений.
Если handler возвращает ошибку, bot:
- форматирует user-facing текст через
ErrorTemplate(...); - отправляет этот текст пользователю;
- логирует исходную ошибку через текущий logger.
По умолчанию возвращённые ошибки остаются пользовательскими ради обратной совместимости. Но Laniakea теперь даёт и явную маркировку:
AsUserError(err)явно оставляет ошибку на пользовательском пути;AsInternalError(err)логирует ошибку, но подавляет автоматический ответ пользователю.
Как это выглядит
func ping(ctx *laniakea.MessageContext, db *App) error {
ctx.Answer("pong")
return nil
}
или:
if err != nil {
return err
}
Когда возвращать error
Возвращай error, когда:
- хочешь единый стиль user-facing ошибок;
- ошибка действительно exceptional;
- хочешь централизованное логирование и formatting.
Если хочешь сделать намерение явным, можно вернуть:
return laniakea.AsUserError(errors.New("access denied"))
Когда лучше ответить вручную
Лучше ответить вручную и вернуть nil, когда:
- это обычная UX-ветка, а не реальная ошибка;
- тебе нужен специальный ответ;
- ты уже сам показал пользователю нужный текст.
Пример:
if !allowed {
ctx.Answer("Access denied")
return nil
}
Когда возвращать internal-only ошибку
Возвращай AsInternalError(...), когда:
- ошибку нужно видеть в логах, но не нужно показывать пользователю;
- это внутренний сбой инфраструктуры или инварианта;
- сырой текст ошибки даст плохой или шумный UX.
Пример:
if err := db.WarmCache(); err != nil {
return laniakea.AsInternalError(fmt.Errorf("warm cache: %w", err))
}
Callback-specific поведение
Для callback-потока возвращённая ошибка превращается не в обычное сообщение в чат, а в ответ на callback query.
Если нужен другой UX, лучше:
- вызвать
AnswerCallbackText(...)илиAnswerCallbackAlert(...); - вернуть
nil.
ErrorTemplate(...)
Через Bot.ErrorTemplate(...) или BotOpts.ErrorTemplate можно настроить user-facing шаблон.
Пример:
bot.ErrorTemplate("Error\n\n%s")
Middleware и ошибки
Middleware не возвращает error, он возвращает bool.
Поэтому если middleware хочет остановить цепочку:
- он сам показывает ответ;
- возвращает
false.
Internal-only ошибки идут по тому же logger path, но не создают автоматический ответ пользователю.
Что читать дальше
Navigation
Start here
Runtime and Architecture
- Bot-Lifecycle
- Webhook-Runtime
- Middleware
- Runners
- Error-Handling
- Logging
- Update-Routing-Model
- Policies
- Scenes
Interaction and Telegram API
- Inline-Keyboards-and-Payloads
- Auto-Generated-Commands
- Drafts
- Rich-Messages
- Localization
- Rate-Limiting
- tgapi-Overview