Установка и первая валидация

Установка validator — одна команда go get в каталоге с go.mod. Если модуля ещё нет, сначала go mod init demo: современные версии Go не подтягивают зависимости молча. Путь импорта включает мажорную версию: github.com/go-playground/validator/v10 — так требуют Go-модули для версий со второй и выше, поэтому «голый» импорт без /v10 не скомпилируется. Пакет, несмотря на длинный путь, называется просто validator: в коде вы пишете validator.New(), а не playground.New(). Девятая версия — легаси с другим набором функций и без развития; в старых туториалах встречается путь github.com/go-playground/validator без суффикса — это она и есть, не перепутайте. После go get в go.mod появится строка require с версией вида v10.x.x: минорные обновления внутри десятой ветки ставятся через go get -u и не ломают код — API v10 стабилен годами. Про vendor и CI: если проект собирается в изолированном окружении без сети, добавьте зависимость в каталог vendor через go mod vendor или положитесь на кэш модулей в пайплайне — валидатор чистая библиотека без транзитивных зависимостей, поэтому весит неприлично мало. И проверьте версию Go в go.mod: библиотека требует не самый свежий Go, но новые версии языка иногда открывают в ней новые опции.

validate := validator.New() — короткая строка с солидным содержимым. Конструктор возвращает *Validate — объект, который при первом прогоне каждой структуры парсит её теги через reflect и складывает план проверки во внутренний кэш. Кэш индексируется по reflect.Type, поэтому стоимость разбора платится один раз на каждую структуру за жизнь процесса: тысяча разных структур — тысяча разборов, но не тысяча на каждый запрос. Повторные вызовы Struct на той же структуре работают по готовому плану, без повторного отражения. Первые проверки после старта медленнее последующих: планы собираются лениво, при первом появлении структуры, — если сервис чувствителен к задержкам, прогрейте валидатор на старте, прогнав основные структуры через Struct с тестовыми значениями, иначе первый пользователь оплатит разогрев. Экземпляр потокобезопасен для проверок — параллельные запросы спокойно делят один валидатор, — а вот регистрация новых функций и алиасов через RegisterValidation и RegisterAlias потокобезопасной не является: её делают на старте, до первых проверок, иначе конкурирующая запись в реестр во время параллельной валидации — гонка, которую поймает не каждый тест. Из этого следует правило курса: валидатор создаётся один раз на приложение — пакетной переменной или полем сервиса. Если вы пришли из Gin, там ровно та же схема — один движок на весь фреймворк с переключённым словарём тегов, как мы разбирали в уроке про валидацию в Gin.

Контракт вызова простой, но двухслойный. Если всё прошло — Struct возвращает nil, и код не делает ничего: err != nil — единственная проверка, которая нужна в счастливом пути. Если правила не выполнились — возвращается validator.ValidationErrors, срез FieldError: одна запись на провалившееся поле с именем, тегом и параметром; структуру разберём по косточкам в уроке про ValidationErrors. Третий случай особый: если в Struct передали не структуру — nil, число, срез — возвращается validator.InvalidValidationError. Типы разные, и обрабатывают их по-разному: ValidationErrors — нормальный рабочий сценарий, InvalidValidationError — ошибка программиста, её пишут в лог или паникуют на старте, но не отдают пользователю. И последний сюрприз: неизвестный или битый тег не возвращается ошибкой — он паникует при первом прогоне структуры. Опечатка в validate:"requred" обнаружится не компилятором, а на живом вызове — тест с валидным значением обязателен. Практическая схема обработки в хендлере выглядит так: сначала errors.As на validator.InvalidValidationError — если сработало, это баг кода, а не данные; затем errors.As на validator.ValidationErrors — рабочий отказ, собираем ответ по полям; всё остальное — неожиданное, уходим в общий обработчик ошибок. Таких три ветки достаточно для девяноста девяти процентов проектов.

go mod init и go get из блока выше, сохранить main.go — и go run main.go в терминале. На печать выйдут две строки, начинающиеся с Key: 'SignupForm.Email' Error:Field validation... и запись про Password. Это дефолтный формат ValidationErrors: подробный, английский и людям не предназначенный — мы его приручим в уроке про русские сообщения, где соберём каталог понятных текстов, и в уроке про единый формат ошибок API, где он станет вежливым 400-ответом. Для практики здесь важнее другое: запустите программу, поменяйте значения полей и убедитесь, что набор записей в выводе меняется вместе с данными — это самое быстрое закрепление контракта из прошлого блока. Заодно прочувствуйте цену первого вызова: разбор тегов через reflect при первом прогоне — самая дорогая операция в библиотеке; второй прогон той же структуры заметно быстрее, потому что план уже в кэше. Именно поэтому в бенчмарках валидатора кэш прогревают заранее: сравнивать холодный первый вызов с горячими бессмысленно. Строку вывода вы получите только на локальной машине: песочница сайта валидатор не исполняет, поэтому примеры живут в терминале, а в браузере мы тренируемся на интерактивах и программах на чистом Go. Если после запуска захочется посмотреть на границу больше — добавьте в форму третье сломанное поле и убедитесь, что число записей в выводе равно числу провалившихся полей, а не числу тегов: это наблюдение станет ключом к уроку про структуру ошибок.

Структура есть не всегда: проверяемый возраст пришёл аргументом функции, значение — из query-параметра, элемент — из цикла по срезу. Для таких случаев у валидатора есть Var: одно значение и строка правил. Грамматика та же, что в тегах: required, min, max, email, gte — весь словарь доступен и поодиночке. Var хорош в утилитах и конвертерах, где хочется сохранить единый словарь правил с остальным проектом, а не плодить локальные if-ы: CLI-утилита и миграция проверяют аргументы тем же словарём, что и структуры основного сервиса, и правило не расползается на две реализации. В тестах Var тоже удобен: проверка граничного значения не требует заводить обёрточную структуру ради одного числа. Для сравнения двух значений существует VarWithValue — например, пароль и его подтверждение; в структурах та же задача решается тегом eqfield, о котором поговорим в уроке про условные теги. Таблица ниже — шпаргалка по методам проверки, которые пригодятся в первые недели; полный список богаче, но эти пять закрывают большую часть повседневных задач. Отдельный плюс Var — проверка на лету в тестах и утилитах командной строки: не нужно городить структуру ради одного значения, а словарь правил остаётся единым с остальным проектом. Помните только, что Var возвращает тот же контракт ошибок, что и Struct: не-структуры тут по определению не бывает, поэтому отдельная ветка с InvalidValidationError не нужна.