Обработка ошибок

Начнём с проблемы, которую решаем. Представьте хендлер GetNote, который возвращает nil и errors.New("заметка не найдена") — выглядит честно, работает даже. Но по проводу эта ошибка превращается в кашу: протокол обязан передать её как-то стандартизованно, а передавать нечего — ни кода, ни типа, только сообщение. Клиент получит internal-error с вложенной строкой и не сможет принять ни одного решения: скрыть ли кнопку редактирования (not_found), показать ли капчу (resource_exhausted), ретраить ли через секунду (unavailable) или через минуту (deadline_exceeded). Проблема не в строках как таковых — они отлично годятся для человека, который читает лог. Проблема в границе процесса: строка не пересекает границу сервисов как сигнал, годный для ветвления. Поэтому в gRPC-мире приняли стандарт: каждая ошибка несёт один из фиксированных кодов — перечисление, известное обоим концам провода заранее. Код — это контракт: он стабилен между версиями, одинаков для Go, TypeScript и Kotlin клиентов, и именно по нему пишется логика отказов. Сообщение при коде — уже для человека, для логов и всплывающих подсказок. Connect принимает эту модель без изменений: те же коды, та же семантика, только дорога другая — не трейлеры HTTP/2, а честные статусы HTTP-ответа, как мы видели ещё в уроке про протоколы.

Всего кодов шестнадцать — перечисление connect.CodeCanceled, CodeUnknown и далее по списку; пользовательских кодов в protobuf-RPC не бывает, и это сознательное решение спецификации: маленький стабильный словарь лучше большого изменчивого. Запоминать их удобно группами. Группа «виноват запрос»: invalid_argument (запрос некорректен сам по себе), out_of_range (значение за пределами допустимого), failed_precondition (запрос корректен, но система не в нужном состоянии), unauthenticated (нет валидных учётных данных), permission_denied (учётные данные есть, права — нет). Группа «виновато состояние»: not_found, already_exists, resource_exhausted, aborted (чаще всего откат транзакции), deadline_exceeded. Группа «виноват сервер или сеть»: unavailable (временно недоступен, стоит ретраить), internal (нарушен инвариант), data_loss, unknown. Отдельные две: unimplemented (метод не реализован или не включён — Connect-хендлер возвращает его сам для Unimplemented-заглушек) и canceled (вызов отменил сам клиент). Важно, что canceled и unauthenticated — не синонимы: первый говорит «сессия прервана», второй — «привет не предъявлен». Этот словарь вы уже видели в таблице первого урока — теперь идём глубже: полный маппинг на HTTP-статусы и правила выбора.

Коды — конечный словарь, и споры «какой выбрать» случаются в каждой команде. Спецификация даёт подсказку, как рассуждать, и она сводится к трём вопросам. Первый: виноват сам запрос независимо от состояния системы? Ставьте invalid_argument — пустой id, отрицательная страница, битый формат. Второй: запрос корректен, но система не в том состоянии? Тогда failed_precondition — например, создание заметки в архивированном проекте; здесь же out_of_range, если суть в границах значения (страница 9999 из трёх). Спецификация прямо инструктирует выбирать между invalid_argument, failed_precondition и out_of_range именно так: первый — для ошибок, независимых от состояния, второй и третий — для зависимых от состояния и диапазона. Третий вопрос: это вообще про текущий момент или навсегда? not_found и already_exists описывают текущее состояние (может, через минуту заметка появится — ошибки не будет), а permission_denied — устойчивый вердикт. Отдельная дисциплина — у unavailable и internal: первый обещает «повтор может помочь» и разрешает ретраи, второй говорит «нарушили свой же инвариант, повтор без разбора полётов бессмыслен». Перепутаете — и нагрузочный ретрай-цикл сам устроит вам вторую аварию. Такой мини-алгоритм из трёх вопросов стоит написать в командную вики: он снимает 90 процентов споров.

Теперь дисциплина на стороне сервера — три правила, которые спасут вам недели отладки. Правило первое: домен объявляет sentinel-ошибки, репозиторий их возвращает, а хендлер переводит в коды RPC. var ErrNotFound = errors.New(...) в пакете домена; FindByID возвращает её; хендлер ловит через errors.Is и оборачивает в connect.NewError(CodeNotFound, ...). Так же раскладывались бы ошибки в Gin- и Echo-проектах — мы делали ровно это в курсах по фреймворкам, меняется только тип конверта. Правило второе: сохраняйте цепочку через %w в fmt.Errorf — connect.NewError оборачивает вашу ошибку как есть, и весь контекст («note "n1": no rows») остаётся на месте; раскопать оригинал можно через errors.Is и errors.As, потому что *connect.Error поддерживает стандартный unwrap-протокол Go. Правило третье, самое частое нарушение: не отдавайте наружу внутренние детали. Ошибка драйвера базы со строкой подключения или таблицей в тексте — подарок атакующему. Внутренние ошибки логируйте целиком на сервере, а наружу — generic-сообщение и код internal. Заметьте, что сообщение ошибки едет по проводу как есть — для not_found это прекрасно (пользователь имеет право знать), для internal — только sanitized-текст. Граница «что говорить наружу» — то же решение, что в HTTP-мире: 404 с телом и 500 без объяснений.

Перейдём на другой конец провода. Клиенту Connect обещает одно: любая неудача вызова приходит как connect.Error — тип с методами Code() (код), Message() (сообщение от сервера) и Details() (структурированные приложения, о них ниже). Разбирать её можно двумя способами, и оба стоит держать в голове. Первый — прямой: errors.As(err, &connectErr), после чего connectErr.Code() == connect.CodeNotFound решает судьбу ветки. errors.As здесь работает, потому что connect.Error поддерживает стандартное разворачивание цепочки. Второй — короче: connect.CodeOf(err) возвращает код ошибки без ручного объявления переменной, удобно для быстрых проверок и логов. Плюс отдельная ветка — отмена: прерванный вызов доезжает кодом CodeCanceled, и его отличают от unavailable простым сравнением Code() — ниже увидим это в коде. Практический шаблон клиента: проверять err первым делом, ветвиться по кодам, а не по строкам сообщения (сообщение — для человека, оно меняется), и не ретраить всё подряд: ретраи уместны на unavailable и, с осторожностью, на aborted; not_found и invalid_argument не станут другим от повтора. Разбор ошибок по коду — та же культура, что и в gRPC-клиенте из курса по gRPC, только тип ошибки здесь один и он всегда локальный.

Два кода ведут себя особняком, и о них стоит поговорить отдельно, потому что они приходят не из бизнес-логики, а из контекста — вспомните таймауты и отмену из предыдущего урока. CodeDeadlineExceeded (HTTP 504) означает, что дедлайн истёк до завершения вызова: клиент мог выставить его сам через context.WithTimeout, мог получить унаследованный дедлайн от вышестоящего запроса, мог сервер — на проводе это одна и та же ошибка. CodeCanceled (HTTP 499) — вызов отменили: пользователь закрыл вкладку, upstream-запрос умер, кто-то вызвал cancel(). Цифра 499 не из стандартного реестра HTTP — это традиция nginx «client closed request», которую Connect-протокол унаследовал: логично, что статус для «клиент ушёл» не должен быть настоящей 5xx-ошибкой сервера. Клиентская разница между ними проста: deadline_exceeded допускает ретрай с большим таймаутом, canceled — нет, вы же сами отменили. Серверная разница важнее: в хендлере ctx.Done() надо уважать — перестать считать, откатить транзакцию, не писать полузаписи. И ещё нюанс для потоков между сервисами: если ваш хендлер дёргает другой RPC и отменяется, отмена должна распространяться вниз по цепочке контекстов — тогда 499 честно доехает до самого края, а не превратится в висящую горутину.

Иногда одного кода и сообщения мало. Хочется приложить к ошибке машиночитаемые подробности: какие именно поля формы не прошли валидацию, какая квота исчерпана и когда обновится, какой id конфликтует. Для этого в модели ошибок gRPC есть details — массив структурированных приложений, и Connect поддерживает их нативно. Механика такая: детали — это обычные protobuf-сообщения, объявленные в схеме (например, InvalidFields с повторяющимся полем path); сервер собирает их и добавляет к *connect.Error, клиент читает список через err.Details() и декодирует каждое приложение в конкретный тип по его типу сообщения. По проводу, в JSON-формате Connect-протокола, детали приезжают массивом details рядом с code и message — то есть даже curl увидит их без специальных клиентов. Куда это применят? Валидация с перечнем полей — классика; нештатные ответы с подсказками ретрая; мультитенантные проверки с перечнем нарушенных политик. Но держите умеренность: детали — это часть контракта API, они требуют схемы и версионирования, а не произвольного текста на ходу. Что-то меняется в детали — это breaking change точно так же, как изменение message-типа. Для большинства сервисов честный набор «код + сообщение + два-три details-типа» закрывает все реальные потребности, а экзотика вроде потоковых частичных ошибок ждёт нас в уроке про стриминг.

Теперь наши сервисы говорят об отказах на общем языке: хендлер ставит коды, клиент ветвится по ним, HTTP-статусы честно отражают итог. Следующая ступень — делать это красиво и в одном месте: перехватчики. Логирование каждого вызова с процедурой и длительностью, проверка токенов на всех рутах разом, метрики для Prometheus — всё это живёт в interceptors, о которых седьмой урок расскажет от обёртки UnaryFunc до цепочек на сервере и клиенте. Дальше по курсу — стриминг, где у ошибок появляется потоковое измерение, браузерные клиенты на TypeScript, которые читают те же коды, и buf-тулчейн, который не даст контракту разъехаться. Программа всех двадцати пяти уроков — на странице курса. А для контраста полезно вспомнить, как те же решения выглядели в чистом gRPC: разбор статусов и таймаутов мы делали в уроке про unary-вызовы — положите оба подхода рядом, и вы увидите, что культура обработки ошибок пережила смену транспорта без единой правки в ветвлениях.