Единый формат ошибок API

Формат описывается один раз как DTO: наверху error с машинным кодом и общим сообщением, ниже details — срез по полям: field, rule, param, message. Собирает конверт одна функция BuildValidationResponse, принимающая validator.ValidationErrors и возвращающая DTO; она тестируется отдельно от фреймворка — табличный каркас из девятнадцатого урока ложится на неё напрямую. Хендлеры больше не пишут JSON руками: получили ValidationErrors — вызвали функцию, отдали результат фреймворку. Выигрыш виден на втором маршруте: форма профиля и форма заказа возвращают конверт одинаковой формы, и фронтенд пишет разбор один. Запасной путь тоже один: незнакомый тег получает нейтральный текст, но поле и правило в деталях всё равно точны — формат не разваливается от опечатки в словаре. Имя функции — не украшение: BuildValidationResponse читается в хендлере как команда, и на ревью достаточно взгляда — ответ собран централизованно. Возвращаемый тип — не map и не интерфейс, а описанный DTO: поля задокументированы компилятором, а не комментарием, и правка формата ломает компиляцию там, где она нужна. Ёмкость под len(errs) и готовый срез details — мелочь, которую приятно оставить в тесте: пустой ValidationErrors сериализуется пустым массивом, и клиентский цикл не падает на null.

Три метода FieldError закрывают весь разбор. Field() возвращает имя поля — для плоских структур этого достаточно; для вложенных и срезов с dive честнее Namespace(): он отдаёт полный путь вида Users[0].Email, тогда как Field() оставит только Email, и два разных адресата неразличимы. Это стык пятого урока про разбор ValidationErrors — там каркас, здесь договорённость: если в API есть вложенные DTO, кладите в field Namespace(), если плоские — Field(), но везде одинаково. Tag() — имя правила: eqfield, oneof, datetime; это ключ для словаря сообщений и для логов. Param() — параметр: у min=8 это 8, у eqfield — имя второго поля, у oneof — перечисление вариантов; у тегов без параметра — пустая строка. Параметр приходит строкой, и «5» из min=5 кладётся в details как есть. У пары Tag() и ActualTag() разница проявляется на алиасах: Tag() вернёт имя алиаса, ActualTag() — реальный тег внутри него; для словаря и логов обычно нужен Tag(), согласованный с тем, что клиент видит в details. Три метода плюс Namespace() — весь бюджет разбора: больше валидатор ничего не обязан сообщать, остальное — забота словаря и конвенции проекта.

Детали дают клиенту машину, а человеку нужен текст: «минимум 8 символов», «адрес почты некорректен». Словарь тег → шаблон — тот же двухуровневый каталог из шестого урока, свёрнутый до одной функции: по Tag() достали шаблон, подставили Param() или имя поля, вернули строку. Незнакомый тег получает запасной текст: формат не ломается, ведь поле и правило в деталях уже точны. Разделение обязанностей простое и полезное на ревью: теги — в логи для разработчика, сообщения — клиенту. Лог пишет поле, тег и параметр — по ним дежурный находит правило; клиент получает текст без тегов вообще. Дубли этого правила распознаются мгновенно: если в каком-то хендлере текст ошибки склеен руками, а не из словаря, — формат уже пошёл вразнос. Шаблоны держите рядом с кодом сборки: словарь — часть кодовой базы и меняется пулл-реквестом с тестом. Если понадобится второй язык — это второй словарь и тот же разбор: детали field, rule, param общие для любой локали, меняется только message.

Функция сборки независима от фреймворка: она про данные, а доставка — слой ниже. В Gin хендлер отвечает AbortWithStatusJSON с кодом 400 и DTO: ответ уходит, цепочка прерывается, и после этого места код работает с валидными данными. В Echo два равных пути: вернуть ошибку из хендлера и разобрать её в своём HTTPErrorHandler или сразу написать c.JSON(400, dto); оба ведут к одному конверту, если errorHandler знает DTO. Стык тринадцатого урока про хуки Echo: там настройка, здесь — дисциплина одного конверта на все маршруты. Порядок проверки в хендлере тоже стоит зафиксировать: сначала InvalidValidationError — это ошибка кода, 500 и лог; потом ValidationErrors — 400 и конверт. Перепутанная ветка отправляет опечатку пользователя в алерты дежурного, а реальный баг кода — в молчаливый 400. Доставка повторяется в каждом хендлере — и ровно поэтому собирается в одну строчку: ответ уже готов, хендлер только отдаёт его фреймворку. Таблица ниже показывает, что именно видит клиент и откуда приходит каждое поле, — на ревью удобно сверять реальный ответ по ней.

Статус — часть формата. 400 говорит «запрос некорректен» и честно описывает ветку валидатора: теги не прошли, details заполнены по ValidationErrors. 422 — «запрос понят, но не принят по смыслу»: форма корректна, а правило домена — возраст, лимит, промокод — не сложилось; материал для details тот же, источник — доменные ошибки. С разметкой правил по слоям связан предыдущий урок: она подсказывает, какой статус отдавать. Выбор между 400 и 422 менее важен, чем его постоянство: клиент пишет разбор один раз, тесты сверяют код один раз. Итоговый проект курса собирает конвейер целиком: конверт, статусы, 409 на занятую почту — и тестирует ответы как контракт API. Слова споров здесь короткие: 400 закрывает синтаксис и формат, 422 — семантические проблемы — оба варианта легальны, и спор о выборе дешевле закрыть конвенцией, чем выиграть раз за разом в пулл-реквестах. В конвенции удобно записать и исключения: что 409 используется только для конфликтов состояния, а ошибки аутентификации вообще мимо этого конверта — у них свой код и свой разбор.