Валидация в Gin: binding

Вызов c.ShouldBindJSON(&dto) делает две вещи подряд: декодирует JSON-тело в структуру и прогоняет её через валидатор. Вторая половина — не магия gin, а наш validator v10: пакетная переменная binding.Validator указывает на реализацию интерфейса StructValidator из двух методов — ValidateStruct(obj any) error и Engine() any. Дефолтная реализация держит *validator.Validate, который создаётся лениво под sync.Once, и в тот же момент вызывает SetTagName("binding") — вот почему правила в gin-проектах пишутся в теге binding, а не validate: словарь движка переключён, и теги validate он молча не читает. Gin validator кэширует разбор структур так же, как «голый» валидатор из второго урока, — один экземпляр на всё приложение gin создаёт и греет сам. Errors по-прежнему идут типом validator.ValidationErrors, и доставать их положено errors.As с указателем на срез — ровно та дисциплина пятого урока. Два отличия, о которых стоит помнить заранее: стат ShouldBindJSON за вас никто не ставит — ошибку в 400 превращает ваш хендлер, и массив верхнего уровня gin валидирует собственным циклом с типом binding.SliceValidationError — про него есть подробный разбор в уроке про валидацию курса Gin. Пропускная способность у ValidateStruct широкая, но выборочная: nil вернёт nil, указатель на структуру уедет в движок, срез или массив верхнего уровня — в цикл по элементам, а всё остальное — карта, строка, число — пройдёт молча без ошибки: движок проверяет только структуры. Отсюда правило DTO-дизайна: на вход принимайте указатель на структуру — единственный вид, для которого binding вообще что-то проверяет.

Семейство ShouldBind устроено как розетки одного валидатора: сначала раскладка, затем проверка. ShouldBind выбирает источник сам: у GET — query-параметры, у остальных методов — JSON-тело, поэтому DELETE при таком подходе обязан прислать тело, как POST; удобно для общих хендлеров, но в явных API точечные вызовы читаются честнее. ShouldBindJSON — только тело по Content-Type json. ShouldBindQuery разбирает query-строку по тегу form, ShouldBindHeader — заголовки по тегу header, ShouldBindUri — параметры маршрута по тегу uri. Рядом живут и служебные точки входа, о которых туториалы молчат: ShouldBindXML и ShouldBindYAML читают соответствующие форматы, а ShouldBindBodyForRepeatableRead буферизует тело и позволяет привязать его второй раз — например, когда после валидации нужно перечитать сырой JSON для лога или подписи. Все они заканчиваются одним и тем же: валидация по тегам binding тем самым движком, поэтому ошибки и обработка не различаются от ветки к ветке. Синтаксис правил — весь курс целиком: min, max, oneof, dive по срезам, условные required_if, ваши RegisterValidation и StructLevel — ничего переучивать не нужно. Единственный нюанс раскладки, который бьёт по валидации: конвертация строк в числа происходит при привязке, и «abc» для int-поля — ошибка декодера, а не провал тега; в ответе это тот же 400, но без записей ValidationErrors, и вашей ошибке-обёртке лучше об этом честно сказать клиенту.

Параметры пути — самое незащищённое место типичного gin-проекта: c.Param("id") отдаёт строку, и до базы доезжает всё, что вписали в URL. ShouldBindUri закрывает дыру структурой: gin собирает c.Params в карту, поля заполняются по тегу uri, и дальше — стандартная валидация binding. Тип конвертируется сам: ID int64 снимет strconv, а для строковых идентификаторов пригодится uuid из четвёртого урока. required на uri-поле обычно бессмыслен: сегмент, не подходящий под :id, просто не сматчит маршрут, — зато oneof, min и uuid работают в полный рост и отсекают мусор до бизнес-логики. Ошибки — те же ValidationErrors, и обработка не отличается от тела запроса: та же ветка errors.As, тот же каталог сообщений. Учтите и обратную сторону: значения из пути приходят строками, конвертация в числа происходит при раскладке, и «abc» в int-поле вернёт ошибку конвертера — она приедет из ShouldBindUri как bind-ошибка, без записей ValidationErrors, и обработчик у неё общий с «битым телом». Полезная привычка — держать структурки параметров рядом с маршрутом и не тащить в них json-теги: источник данных у параметров один, и двойной словарь тегов только путает ревьюера.

respondFields — та самая функция из пятого и шестого уроков, и в gin ей живётся спокойнее всего: единственная точка оборачивания ValidationErrors в ответ, один формат на все ShouldBind-ветки. Помните про два имени поля: Field() возвращает имя структуры, фронтенд подсвечивает json-имя — маппинг из пятого урока нужен здесь нисколько не меньше. Для массивов верхнего уровня не забывайте вторую ветку: gin соберёт ошибки элементов в binding.SliceValidationError со строками вида [1]: ..., и errors.As на ValidationErrors мимо — элементу ответа лучше указать индекс виновника. Если ответ уезжает в JSON, не отдавайте err.Error() целиком: это склейка английских простыней, которую клиент не разберёт, а лог — наоборот, увидит её с благодарностью: одна строка с полным списком провалов делает запись о 400 самодостаточной. PATCH-обновлениям в gin тоже есть место: через Engine() доступен StructPartial с перечнем пришедших полей — проверяются только они, и клиент не обязан присылать форму целиком; вызов встаёт после декода и до записи в базу, ошибки — те же ValidationErrors. И не пытайтесь перехватывать валидацию раньше времени: даже если поле пришло, проверку остановит первый провалившийся тег — те же правила порядка, что вы видели на чистом движке.

Всё из уроков десять и одиннадцать работает в gin через официальную дверь — метод Engine() интерфейса StructValidator, который возвращает внутренний validator.Validate. Приведение типа any к validator.Validate с проверкой ok — и дальше обычный API: RegisterValidation для своих тегов, RegisterStructValidation для правил на всю структуру, RegisterTagNameFunc, если хотите видеть в ошибках json-имена. Регистрируйте до запуска сервера: регистрации не потокобезопасны, а движок общий на все запросы — это тот же контракт, что у одинокого экземпляра из второго урока. RegisterTagNameFunc уместен и здесь: json-имена в FieldError понадобятся respondFields, чтобы ключи конверта совпали с тем, что видит фронтенд, — регистрируйте его на том же экземпляре из Engine(), вместе со своими тегами. Отдельно решите, где живут ваши теги: если движок достаётся из binding.Validator, теги видны и ShouldBindJSON, и структурным правилам, и всему, что вы проверяете руками; если создаёте второй экземпляр через validator.New() — это отдельный мир со своим словарём, и его пересечение с gin-овским равно нулю. Про цену второго экземпляра и про то, почему валидатор один на приложение, — целиком следующий урок, там и продолжим.