Централизованные ошибки: errorHandler и NotFound

Формат обязуется быть одним и тем же для любого провала: обёртка error, внутри машинный code и человеческий message. Обёртка — не украшение: однажды рядом появятся поля details для ошибок валидации или request_id для поддержки, и обёртка даст им место, не ломая существующих клиентов. code — строковый идентификатор вида not_found или validation_failed: его читает машина и ветвит логику — unauthorized ведёт на страницу логина, rate_limited показывает таймер. message — текст для человека, его показывают в тосте и парсить его нельзя: формулировки меняются вместе с локализацией. Content-Type: application/json обязателен и для ошибок: ошибка — такой же JSON-ответ, как и успех, и фронтенд вызывает res.json() без предварительного чтения заголовка. Правило error handling в go, которое здесь работает: формат фиксируется тестом, а не договорённостью в чате — тест на каждый статус проверяет и Content-Type тоже.

Канала ошибки нет — значит, его эмулируют. Первый путь — renderError в месте и return: простой, но разбросан по хендлерам. Второй — свой тип apiError и middleware-обработчик: хендлер передаёт ошибку паникой значением этого типа, а errorHandler ловит её в defer через recover(). Паника как управление потоком — приём спорный, но у него есть честное оправдание: механизм уже есть, работает сквозь все слои и не требует менять сигнатуры хендлеров. Критично не перепутать свою ошибку с настоящей паникой: errorHandler перехватывает только *apiError, чужое значение обрабатывает отдельно — стек в журнал через debug.PrintStack и 500 с code internal. http.ErrAbortHandler — служебная паника, которой net/http рвёт соединение, — пропускается, ровно как это делает Recoverer из урока про встроенные middleware. Слой ставится в начале стека, сразу после RequestID и RealIP и до Logger: каждая его ошибка проходит через обёртку лога, и строка показывает честный 404, а не 200. Стандартный Recoverer при этом снимается со стека — его работу errorHandler берёт на себя, только с ответом в формате API.

Статус-код и code — два уровня одного сообщения: код несёт класс, код-строка — точную причину. 400 Bad Request — синтаксический мусор: битый JSON, тело не декодируется. 401 Unauthorized — нет или просрочен токен; 403 Forbidden — токен есть, прав нет. 404 Not Found — ресурса не существует, и сюда же попадает роутинг через r.NotFound. 405 Method Not Allowed — путь есть, метод не тот. 409 Conflict — конфликт состояния: заметка уже существует, версия устарела. 422 Unprocessable Entity — тело синтаксически валидно, но поля не прошли проверку: пустой title, отрицательная цена. 500 — наша вина: паника или упавшая зависимость. Живое место из начала урока как раз про 422: статус был честный, а формат — нет. Споры «422 против 400 на валидации» в командах вечны — выбирайте один вариант один раз и записывайте его в таблицу-контракт ниже: клиент должен знать ответ заранее, а не угадывать по релизным заметкам.

По умолчанию chi отвечает на несуществующий маршрут через http.NotFound: статус 404, тело «404 page not found», Content-Type text/plain; charset=utf-8 и заголовок X-Content-Type-Options: nosniff. Для curl терпимо, для фронтенда — тот же сломанный res.json(), что и в истории в начале урока. Не лучше выглядит 405: в исходниках chi v5 дефолтный хендлер — две строки, WriteHeader(405) и w.Write(nil), то есть пустое тело и даже без заголовка Allow, который RFC 7231 рекомендует заполнять списком разрешённых методов. Обе точки подменяются на роутере: r.NotFound(...) и r.MethodNotAllowed(...) принимают обычный func(w, r). Деталь из устройства chi: эти хендлеры вызываются внутри routeHTTP, а вся цепочка middleware оборачивает именно routeHTTP — значит, NotFound и MethodNotAllowed выполняются после всех слоёв: Logger залогирует статус, а в контексте лежит RequestID. Подмена — три строки, и системные ответы говорят тем же языком, что и ваши.

Проверка согласованности выглядит со стороны фронтенда так: обработчик на все не-2xx читает resp.json(), ветвит по e.error.code — unauthorized отправляет на логин, validation_failed подсвечивает поле, rate_limited показывает таймер — и показывает e.error.message в тосте. Один обработчик, одна структура, ноль сюрпризов. Хрупкое место — любая ветка, отвечающая не в формате: текстовый вывод в body, пустое 405, text/plain 404 — res.json() падает до того, как код доберётся до ветвления. Поэтому контракт закрепляется тестом: на каждый статус проверяются код ответа, Content-Type и наличие error.code. Полезное дополнение — request_id из middleware.GetReqID(r.Context()) в теле ошибки: пользователь присылает id из тоста, вы находите запрос в логе за секунды. Связь «ошибка и строка лога» — то, за что поддержка скажет спасибо, а chi уже положил id в контекст: осталось только достать.