StructLevel: правила на всю структуру

Регистрация — метод экземпляра: validate.RegisterStructValidation(fn, MyType{}), где fn — функция типа validator.StructLevelFunc, то есть func(sl validator.StructLevel). Типы после функции — вариадические: столько структур, сколько нужно, и указатель не обязателен — валидатор разыменует его сам через reflect.Indirect, поэтому канон из официальных примеров — RegisterStructValidation(fn, User{}) с не-указательным значением. Регистрируйте на старте, рядом с RegisterValidation и RegisterAlias: метод не потокобезопасен, как и все регистрации, — та же дисциплина второго урока. Момент вызова важен и приятен: structlevel validation срабатывает ПОСЛЕ того, как отработали все теги полей структуры, — глубинный обход доходит до конца, и тогда движок зовёт вашу функцию. Из этого следует поведение всего списка ошибок: записи от полей ложатся в ValidationErrors первыми, в порядке полей, а за ними — всё, что вы нарапортовали из структурной функции, в порядке вызовов ReportError. Поля и структура работают в один проход: три сломанных тега и одно структурное правило дадут четыре записи в одном err, и клиент получит полный список разом — никакого второго вызова validate.Struct не нужно. А если структура вложенная, функция зовётся каждый раз, когда обход доходит до экземпляра этого типа: правило на Address сработает для каждого адреса в срезе.

StructLevel — интерфейс с семью методами, но в ежедневной работе живут три. Current() — reflect.Value той самой структуры, для которой вызвана функция: через него читаются поля. Top() — корневая структура вызова: для вложенных правил видно, кто приехал сверху, — на глубокой вложенности путь к корню собирается через Parent(), родителя текущего уровня. Validator() возвращает сам экземпляр *Validate — из функции можно позвать validate.Var или свои теги, не замыкаясь на глобальную переменную. Чтение полей — на выбор: Interface().(RegistrationForm) с приведением типа или sl.Current().FieldByName("Password").String() по имени — первый путь даёт читаемый код, второй не зависит от типа и не паникует с лишними полями. ReportError принимает пять аргументов, и раскладка такая: field — само значение, fieldName — имя, которое попадёт в Namespace() и Field() ошибки, structFieldName — имя из объявления структуры, tag — ваш тег (можно выдуманный с нуля, можно существующий), param — строка-параметр, пустая или подсказка вроде имени пары-поля. Без RegisterTagNameFunc оба имени совпадают; с ним fieldName — альтернативное, например json-имя. Запомните: ReportError ничего не проверяет — он только дописывает готовую запись об ошибке; вся логика решения — ваша. Оставшиеся методы не для красоты. Validator() открывает дверь к обычному API экземпляра: посчитанную внутри правила сумму можно прогнать через sl.Validator().Var(reflect.ValueOf(sum), "required,min=1") — словарь тегов тот же, что и у полей. А ReportValidationErrors прикрепляет готовый срез ValidationErrors с префиксом пути: пригодится, когда внутри структурной функции вы проверили вложенную структуру отдельным вызовом и хотите, чтобы её записи легли в общий список с правильным Namespace(), а не болтались отдельной ошибкой. В ежедневной работе почти всё закрывает ReportError, оба метода ждут своего часа — но знать о них стоит до того, как придётся выдумывать обходные пути.

Разберём два правила, для которых тегов не существует. Первое — заказ: Items []Item и Total int64; правило «сумма цен равна итогу» агрегирует срез, и ни один тег поля это не выразит, потому что смотреть нужно на все элементы сразу. Второе — событие: Starts и Ends time.Time; правило «конференция длится минимум три дня» — это не просто сравнение полей, а арифметика с AddDate, и gtfield здесь бессилен. Оба правила — обычный Go внутри структурной функции: посчитали, сравнили, нарапортовали. Заметьте, как выбирается имя тега: summatch и minduration — это названия бизнес-инвариантов, и именно они появятся в FieldError.Tag(). Не называйте правило именем встроенного тега: если summatch однажды переедет в RegisterValidation как настоящий тег, сообщения и тесты останутся совместимыми, а вот путаницы «тот же Tag() — разная механика» лучше избегать с первого дня. И держите функцию структурного уровня такой же чистой, как теговые функции из десятого урока: чтение полей, вычисление, ReportError — без сети, без времени, без изменения данных.

Честности ради: пара полей закрывается встроенными тегами, и структурный уровень нужен не всегда. eqfield=Password проверит равенство подтверждения, gtfield=StartDate — что дата конца позже начала, required_without_all из урока про условные теги — «хотя бы один из трёх». Когда правило — сравнение двух полей без вычислений, берите тег: он короче, дешевле и уже покрыт каталогом сообщений. StructLevel берите, когда правило не выражается тегом: агрегаты по срезам, три и более поля, арифметика с датами, сравнение вычисленных значений, и когда ошибке нужно собственное имя тега с собственным сообщением вместо «failed on the eqfield tag». Вторая граница — природа проверки: структурная функция, как и теговая, не ходит в сеть и не проверяет живое состояние; «промокод существует» остаётся бизнес-слою, о чём договорились ещё в десятом уроке. И третья — не сваливайте туда то, что можно было оставить у поля: если правило трогает одно поле, ему место в теге, а структурная функция — для инвариантов целого.

Запись из ReportError — полноценный FieldError: Field() вернёт ваше fieldName, Namespace() соберёт путь вида Order.Total с учётом вложенности, Value() — переданное значение, ActualTag() — тот же ваш тег, алиасов здесь нет. Каталог сообщений из урока про русские тексты обслуживает структурные теги на общих основаниях: ключ — Tag(), шаблон — ваш текст, Param() подставляет детали. Тесты структурных правил строятся как обычные тесты валидации: собираете структуру с расхождением, зовёте validate.Struct, ждёте ValidationErrors с вашим тегом; пятёрка значений из урока про теги превращается здесь в пятёрку комбинаций — совпало, не совпало, пустые поля, пограничная сумма, сумма из одного элемента. Регистрации держите на старте и в одном месте: RegisterStructValidation подчиняется тем же ограничениям потокобезопасности, что и RegisterValidation, — после первых проверок регистрировать новое правило значит гоняться за гонкой данных. Тот же контракт замены действует и здесь: повторная регистрация функции на том же типе молча заменит предыдущую, как и у теговых функций. Есть и нюанс кэша: структурная функция попадает в разбор типа в момент первого validate.Struct — план структуры сохраняет ссылку на неё, поэтому правило, зарегистрированное после того, как тип уже проверялся, не увидят даже новые вызовы. Ещё одна причина держать все регистрации до первой проверки. Если проект живёт в Gin или Echo, структурные правила переезжают без изменений: там тот же экземпляр движка, и RegisterStructValidation вызывается один раз при инициализации — как именно, покажут следующие два урока.