Обработка ошибок HTTPError: Code, Message, Internal и свой ErrorHandler

Тема «echo httperror» — это обработка ошибок echo, построенная вокруг одной идеи: обработчик возвращает ошибку значением, а ответом на неё занимается фреймворк. В Gin вы пишете c.JSON(http.StatusBadRequest, ...) прямо в теле при каждом отказе; в Echo вы просто возвращаете error, и единственное место, которое решает, каким будет HTTP-ответ, — глобальный HTTPErrorHandler. Сигнатура объявлена в echo.go строкой type HTTPErrorHandler func(err error, c Context): на вход — ошибка и живой контекст запроса, через который можно и статус поставить, и JSON отдать, и в лог записать. Обработка ошибок echo — это, по сути, вся эта функция целиком. Поле HTTPErrorHandler — обычное поле структуры Echo, и echo.New() заполняет его штатной функцией: e.HTTPErrorHandler = e.DefaultHTTPErrorHandler.

Это третье обещание, которое мы исполняем: в восьмом уроке, строя bearerAuth, мы сказали «подробная анатомия HTTPError — тема десятого урока», в девятом — «разбор ошибок целиком — дело десятого урока». Сегодня разбираем весь вертикальный срез: что происходит между return err из вашего обработчика и байтами, уехавшими клиенту; из чего состоит echo.HTTPError; как дефолтный обработчик решает статус и тело; почему при Debug в ответе появляется лишнее поле; и как заменить весь конвейер своим — с единым форматом {error, code} для всего API.

Проведём ошибку по цепочке. Первый узел — ServeHTTP: после того как стек middleware и обработчик исполнены, в echo.go стоит короткая проверка: if err := h(c); err != nil { e.HTTPErrorHandler(err, c) }. Всё, что всплыло из любого звена — обработчика, bearerAuth, валидации, — приходит в обработчик ровно один раз: middleware, который вернул next(c) без изменений, в передаче ошибки не участвует, он просто пропускает её наверх.

Второй узел — ручной вызов. У echo.Context есть метод c.Error(err), и его тело — одна строка: c.echo.HTTPErrorHandler(err, c). Это способ позвать глобальный обработчик из середины цепочки — так делает RequestLogger с HandleError: true из девятого урока: middleware сам оформляет ответ ошибкой ДО снятия значений access-записи, чтобы статус в записи был честным. Разница между return err и c.Error(err) в позиции звена: return передает ошибку выше, c.Error завершает историю на месте.

Третий узел — защита от двойного ответа. У Response из response.go есть флаг Committed bool: WriteHeader ставит его в true, и повторный вызов WriteHeader уже ничего не отправит — только запишет в e.Logger.Warn строку «response already committed». Именно поэтому первые строки DefaultHTTPErrorHandler — это guard: if c.Response().Committed { return } (echo.go, строка 428). Сценарий, ради которого guard написан, прямо описан в доккомментарии: хендлер уже ответил через c.JSON — заголовки ушли в сеть — и тут какое-то middleware на раскрутке вернуло ошибку. Обработчик получает её, видит Committed и молча выходит: перезаписать уже уехавший ответ невозможно физически.

Структура из echo.go крошечная — три поля, и каждое со своей ролью:

Internal error — исходная причина от внешней зависимости, с тегом json:"-": в дефолтный JSON она не попадает никогда, это канал для логов. Message interface{} — то, что увидит клиент; тег json:"message" намекает, что при маршалинге самой структуры поле уедет под этим ключом. Code int — HTTP-статус, тоже с json:"-": статус дублировать в тело незачем, он уже в строке ответа.

Тип Message — interface{}, и это главная гибкость и главная ловушка структуры. Туда можно положить строку — самый частый случай; error — дефолтный обработчик вызовет его Error(); структуру или echo.Map — она уедет клиенту как есть, со своими json-тегами; наконец, значение, реализующее json.Marshaler, — обработчик вообще не станет его трогать.

Обратите внимание на порядок полей: Internal объявлен первым, Code — последним. Позиционная инициализация &echo.HTTPError{401, "нет доступа", nil} по незнанию положит 401 в Internal — всегда пишите имена полей явно, как это делает штатный key_auth.go: return &echo.HTTPError{Code: http.StatusUnauthorized, Message: "Unauthorized", Internal: lastValidatorErr}. Это живой образец из каталога middleware: аутентификация кладёт в Message краткий наружный текст, а в Internal — реальную причину от валидатора токена.

У *HTTPError есть метод Error(), который делает тип совместимым с error: fmt.Sprintf("code=%d, message=%v", he.Code, he.Message), а при непустом Internal — "code=%d, message=%v, internal=%v". Это формат для машин, а не для клиентов: именно его напечатают e.Logger.Error и slog, когда получат такую ошибку. Форматирование %v сквозное: строка напечатается как строка, error — через свой Error(), структура — Go-представлением. Разделение труда такое: Error() — для логов и терминала, switch по Message — для клиента, и это два разных представления одной ошибки.

Причина кладётся в Internal двумя методами, и разница между ними — источник самых тихих багов. SetInternal(err error) HTTPError мутирует приёмник и возвращает его же для цепочки: he := echo.NewHTTPError(500, "внутренняя ошибка").SetInternal(err). WithInternal(err error) HTTPError возвращает КЛОН с теми же Code и Message, но с новой причиной — исходное значение не трогает.

Почему клон важен, станет ясно в следующем блоке — Err* из echo — общие экземпляры. А пока зафиксируйте третий метод: Unwrap() error возвращает he.Internal и удовлетворяет интерфейс обёрток Go 1.13. Отсюда способность, которой мы будем пользоваться в своём ErrorHandler: errors.Is и errors.As видят сквозь HTTPError — errors.Is(err, sql.ErrNoRows) докопается до причины, даже если сверху три этажа обёрток.

Читаем штатную функцию как конвейер из шести ступеней. Первая — guard Committed: ответ уже уехал — выходим молча. Вторая — распознавание: err.(HTTPError) — type assertion, не errors.As; HTTPError, завёрнутая в fmt.Errorf, здесь распознается как обычная ошибка и станет 500-й — обёртки над HTTPError дефолт не разворачивает. Если assertion сработал и у ошибки есть Internal, который сам является HTTPError, он заменяет текущую ошибку целиком: he = herr. Это разворот ровно на один этаж — сквозь два вложенных Internal дефолт уже не полезет.

Третья ступень — ошибка не HTTPError: собирается заглушка &HTTPError{Code: 500, Message: http.StatusText(500)}. Любая чужая ошибка — из базы, из парсера, из вашего кода — получает 500 «Internal Server Error»; в теле ответа её текста нет, и это правильно: текст ошибки не должен утекать клиенту без вашего решения. Над этой заглушкой в исходнике висит комментарий Issue #1426 — багфикс, благодаря которому нестроковый Message (структура, echo.Map) доезжает до ответа как есть, без пересборки. Четвёртая — switch по типу Message: строка превращается в Map{"message": m}, а при включённом e.Debug — в Map{"message": m, "error": err.Error()}; json.Marshaler отдаётся как есть; error — в Map{"message": m.Error()}; остальные значения (структура, echo.Map) остаются собой и маршалатся своими тегами. Пятая — отправка: для HEAD-запроса c.NoContent(he.Code) без тела — Issue #608; для остальных c.JSON(code, message). Шестая — если отправить не удалось, ошибка отправки уходит в e.Logger.Error(err) — тот самый логгер из девятого урока, на который влияет SetOutput.

Отдельно честность про Debug: в дефолтном обработчике нет стека вызовов — только текст ошибки в поле "error". Никакой магии трассировки Echo при Debug не добавляет, ни в ответ, ни в лог.

Поле e.Debug bool включает в дефолтном обработчике одну добавку: для строкового Message ответ собирается как Map{"message": m, "error": err.Error()}. В поле "error" уезжает полный текст he.Error() — то есть «code=404, message=нет задачи, internal=...». Смотрите, что это значит: если причина лежала в Internal, Debug вытащит её наружу через err.Error() — вместе с внутренностями вроде текстов SQL-ошибок. Второй эффект e.Debug вы уже знаете из девятого урока: configureServer поднимает уровень e.Logger до log.DEBUG. Стека вызовов нет ни там, ни там — только тексты.

Практический вывод двоякий. В разработке Debug включать стоит: поле "error" в ответе экономит поездки в терминал. В продакшене — выключать: err.Error() становится телом ответа, а значит, публичным интерфейсом. Это тот же урок, что мы разбирали в fiber: там дефолтный ErrorHandler отвечал text/plain с err.Error() напрямую, и мы строили конверт, который прячет причину за человекочитаемым текстом. Echo дефолтом честнее — err.Error() у клиента только при Debug, — но принцип один: наружу — Message, внутрь лога — Internal. И следите за текстами, которые кладёте в Message: они уезжают клиенту при любом режиме.

Echo держит наготове каталог готовых ошибок: echo.go определяет полсотни пакетных переменных от ErrBadRequest до ErrNetworkAuthenticationRequired — ErrNotFound, ErrUnauthorized, ErrTooManyRequests, ErrTeapot и так далее. Каждая — echo.NewHTTPError(соответствующий код) без сообщения, то есть с текстом StatusText. Ими удобно пользоваться как sentinel-значениями: return echo.ErrNotFound короче, чем конструктор, и сравнение ошибок по идентичности работает.

С каталогом связаны два штатных обработчика, о которых шестой урок сказал вскользь: «404 в Echo это тоже обработчик, просто штатный». Развяжем: NotFoundHandler — пакетная переменная, тело которой целиком return ErrNotFound, — подставляется роутером, когда путь не нашёлся; MethodNotAllowedHandler — return ErrMethodNotAllowed — когда путь есть, а метода среди его маршрутов нет: роутер в этом случае отдаёт 405, а не 404, и кладёт в контекст строку допустимых методов (ctx.Set(ContextKeyHeaderAllow, ...)), откуда обработчик достаёт её c.Get-ом и ставит заголовок Allow — так требует RFC 7231, раздел 7.4.1. Обе ошибки едут наверх как обычные и оформляются дефолтным обработчиком: клиент получает 404 {"message":"Not Found"} или 405 с заголовком Allow.

Хотите свой 404 — не патчьте обработчик, а зарегистрируйте маршрут-перехватчик: e.RouteNotFound("/*", func(c echo.Context) error { return c.NoContent(http.StatusNotFound) }). Внутри это обычный e.Add со специальным методом-маркером "echo_route_not_found"; роутер выполняет такой маршрут вместо штатного NotFoundHandler, и ваш брендированный JSON-конверт поедет и на несуществующие пути.

Замена — присвоение в поле: e.HTTPErrorHandler = вашаФункция с той же подписью func(err error, c Context). Никаких конфигов и промежуточных режимов: поле перезаписано — дефолта больше нет, и вместе с ним исчезают его заботы. Их три, и повторить их обязан ваш обработчик. Первое — guard Committed: if c.Response().Committed { return } — без него двойной ответ не случится (net/http защитит сам), но e.Logger получит Warn «response already committed» на каждом таком случае. Второе — обязанность ответить ВСЕГДА: обработчик получает каждую ошибку приложения, и путь «молча выйти» есть только у Committed-ветки. Третье — логирование: дефолт пишет в e.Logger только неудачу отправки; вашу возможность логировать каждую ошибку с причиной никто, кроме вас, не реализует.

Зато взамен вы получаете главный приз: единый формат. Конверт {"error": текст, "code": статус} для всех ошибок API — тот же Envelope-стиль, что мы собирали в fiber: там ErrorHandler из конфига строил {error, code} и HTML-страницу для браузера, и аргументы там те же: фронтенд пишет один catch, в конверт добавляются новые поля без миграции клиентов, а обработчик ошибок — единственное место, где формат enforced. Дефолт echo говорит на ключе "message" — выбирая конверт, выбирайте один и держите его во всех ответах, включая 404 и 405 от роутера: они тоже приедут в ваш обработчик, потому что 404/405 — тоже обработчики, и их ошибки пойдут общим потоком.

Разделение API и HTML делается по пути запроса: strings.HasPrefix(c.Request().URL.Path, "/api") — JSON-конверт, иначе — HTML-страница «что-то сломалось». Тот же приём, что у fiber; путь берите из запроса, а не из c.Path(): на 404 шаблон маршрута пуст.

Мы закрыли вертикаль ошибок: HTTPError с трио Code/Message/Internal и конструктором NewHTTPError, дефолтный конвейер с guard-ом Committed и Debug-полем error, каталог Err* с правилом «не мутировать», 404/405 как штатные обработчики с Allow и RouteNotFound, и собственный ErrorHandler, который собирает единый формат {error, code} для /api, HTML для страниц и структурный лог с причиной и request_id. bearerAuth из восьмого урока в этом main по-прежнему кладёт пользователя под ctxUserKey — доменные APIError можно обогащать им в ErrorHandler, если контракт ошибки требует автора запроса.

Следующая тема прячет в себе то, чем мы пользовались четыре урока подряд: e.Group("/api", ...) был заглушкой, а на деле — целый слой организации маршрутов. Одиннадцатый урок соберёт группы и версии API: общие middleware на поддерево маршрутов, префиксы /v1 и /v2 рядом с одной базой обработчиков, изоляция конфигов между версиями и типичные ловушки сквозных зависимостей. Пока проверьте себя карточками, соберите fill и order ещё раз и проведите ErrorHandler через боевые сценарии: bearerAuth с неверным токеном должен дать в конверте "error": "Unauthorized" и code 401, /api/tasks/abc — 400 с текстом про числовой id, а /api/tasks/999 — 404 task_not_found с причиной от хранилища в логе. Навигация по курсу — на странице курса Echo, звенья и c.Set/c.Get — в уроке про кастомные middleware, HandleError и RequestID — в уроке про логирование, конверт {error, code} и его аргументы — в уроке fiber про ошибки.