ValidationErrors: что именно сломалось

err, который возвращает validate.Struct, — один из двух типов, и различать их нужно на уровне кода. Первый — validator.ValidationErrors: срез FieldError, по записи на каждое провалившееся поле; это нормальный рабочий сценарий — данные не прошли правила, отвечаем 400 по полям. Второй — *validator.InvalidValidationError: валидатору передали не структуру — nil, число, срез; это ошибка программиста, и её место в логах или панике на старте, а не в ответе клиенту. Оба типа — конкретные значения, реализующие error, поэтому достают их через errors.As с указателем на нужный тип: это безопаснее прямого приведения типов, потому что err может быть завёрнут другим слоем. Порядок веток имеет значение по соображениям читаемости: сначала узкая InvalidValidationError, потом широкая ValidationErrors — формально они не пересекаются, но такой порядок читается как чек-лист: баг кода, отказ данных, всё остальное. Стандартный паттерн — в блоке ниже.

FieldError — маленькая, но говорящая структура. Field() возвращает имя поля структуры: Password; для элементов среза после dive — имя с индексом, вроде Tags[2]. Tag() — тег, на котором проверка споткнулась: required, min, email. Param() — параметр этого тега строкой: «8» для min=8, «admin user» для oneof, пустая строка для required — у него параметров нет. Value() — само значение поля, которое не прошло: удобно для логов, но не для ответа клиенту. Namespace() — полный путь с точками: SignupForm.Address.City; он оживёт в уроке про вложенные структуры, а пока запомните сам факт. ActualTag() возвращает реальный тег без алиасов — на простых тегах совпадает с Tag(), разница появляется с RegisterAlias, когда одному правилу придумывают своё имя. Kind() и Type() — reflect-категория и тип поля, если хочется ветвиться по ним: строка это или число, int или time.Time; так, каталог сообщений может для числовых полей говорить «минимум N», а для строковых — «минимум N символов», не заводя отдельные теги. И метод Error(), который собирает ту самую простыню Key: '...' — теперь понятно, из каких частей. Для сообщений на русском нужны первые три — Field, Tag и Param — плюс словарь; остальное пригодится в специфических сценариях. И ещё разница, которую полезно понимать заранее: Field() и Namespace() отдают имена по настоящим полям структуры, без переименований по json-меткам — валидатор про сериализацию не знает, у него свой взгляд на имена; будем помнить при маппинге.

Важное свойство исполнения: поле проверяется по правилам слева направо, и первый провалившийся тег завершает проверку этого поля. Password string с тегом required,min=8 и значением «» вернёт одну запись с тегом required — до min дело не дойдёт, пустая строка уже провалила первый тег. Из этого два следствия. Первое: не рассчитывайте увидеть в ValidationErrors все причины по одному полю — полный список причин по полю валидатор не соберёт; если бизнесу нужен пошаговый диалог, проверяйте повторно после каждого исправления или делите форму на шаги, где каждая валидация отвечает только про текущий шаг. Второе: порядок правил в теге управляет тем, какое сообщение получит пользователь: required первым даёт «укажите поле», а min первым — «слишком коротко» даже для пустой строки. В курсе мы ставим required первым — это договорённость между тегом и текстом подсказки, которая делает сообщения предсказуемыми. На практике из этого свойства вырастает целая дисциплина UX: длинная форма с десятью ошибками не должна возвращать все десять, если девять из них — следствия одной пустой строки; пошаговые формы с валидацией текущего шага дают клиенту короткий список и держат сообщения осмысленными. А если продукт требует показать все проблемы разом, собирайте их отдельным проходом по полям — правила слева направо это механика валидатора, а не закон интерфейса. При этом сами поля независимы: три сломанных поля дадут три записи, и клиент получит весь список разом — это и есть преимущество собирающей валидации перед стоп-на-первой-ошибке. И последнее свойство, которое стоит прочувствовать: порядок записей в срезе следует порядку полей структуры — Password раньше Age. Не полагайтесь на это в логике ответа, но для чтения логов знание полезное: запись с незнакомым полем значит, что смотрят не ту версию структуры.

*InvalidValidationError заслуживает отдельного блока, потому что его появление почти всегда означает баг в вашем коде, а не в данных. Валидатор возвращает его, когда в Struct передали nil, не-указатель, указатель на не-структуру. Типичные сценарии из жизни: функция принимает any и доходит до validate.Struct(data) с числом внутри; тест передаёт nil «а вдруг сработает»; рефакторинг сменил сигнатуру, и вместо структуры поехала ошибка предыдущего шага. Обращение однообразное: это не пользовательская история — логируйте с контекстом или паникуйте на старте, чтобы баг всплыл при первом же прогоне, а не жил годами в тёмной ветке. Практика с паникой на старте выглядит жёстко, но у неё есть обоснование: InvalidValidationError возможен только там, где потерян тип данных — после рефакторинга или в generic-обёртке; такие места всплывают на первом интеграционном тесте, и лучше упасть в тестовом окружении с внятной причиной, чем молча пропускать проверку в проде. Если паника в вашем сервисе недопустима, логируйте на уровне error и возвращайте 500 — главное, не превращайте её в 400: пользователь не виноват в том, что код передал валидатору не структуру. Отсюда же правило для обёрток: функция-помощник validateOf(data any) error обязана различать оба типа и документировать, что InvalidValidationError наружу не отдаётся. В тестах правил — отдельный урок про тесты — InvalidValidationError проверяют явно: подают nil и ожидают именно этот тип, а не ValidationErrors; это фиксирует контракт проверки в коде.

Соберём практику урока в принципы ответа клиенту. Не отдавайте err.Error() как есть: английская простыня, утечка внутренних имён полей и структуры — и всё это вместо двух слов по-русски. Не отдавайте и Value() провалившихся значений: в ошибке уедет то, что ввёл пользователь, включая пароли и паспорта; значение — для логов, и не для всех полей. Отвечайте списком Details: по записи на каждое сломанное поле, собранной из Field, Tag, Param и словаря сообщений, — так фронтенд подсвечивает инпуты один к одному. Этот конверт — тема двух уроков: шестой соберёт каталог русских текстов, двадцать четвёртый оформит единый формат ошибок API с кодами и полем. А если вы работаете в Gin, тот же паттерн уже разобран в двенадцатом уроке — с тегами binding и ShouldBindJSON; механика FieldError при этом идентична. Практическая проверка принципов простая: откройте любой свой ответ 400 и посчитайте, сколько в нём утечёк из прошлого — технических имён, английских тегов, значений полей. Каждая утечка — это ровно то, что мы сегодня разложили по методам.