Свой валидатор-функция

Регистрация — метод на экземпляре валидатора: RegisterValidation("phone", fn), где fn — функция типа validator.FieldLevel, возвращающая bool. С этого момента тег phone работает в любой структуре этого экземпляра как встроенный: встанет в цепочку правил, подчинится omitempty и условным тегам, попадёт в FieldError с собственным именем. Регистрировать нужно на старте, до первых проверок: реестр правил не потокобезопасен во время валидации — та же дисциплина второго урока, где один экземпляр живёт на всё приложение. Место регистрации тоже выбирайте один раз: пакет, где создаётся экземпляр, обычно рядом с конструктором — так ревьюер видит весь словарь тегов проекта на одном экране, а тесты собирают тот же набор вызовов без копипасты. Реестр ведёт себя иначе, чем подсказывает интуиция. Повторная регистрация того же имени не падает: документация прямо говорит — если тег уже существует, предыдущая функция заменяется новой. Тихая замена опаснее паники: два пакета, зарегистрировавшие один тег по-разному, дают валидатор, который работает по правилам того, кто инициализировался последним, — поэтому держите все RegisterValidation в одном месте, где конфликт виден на ревью. Жёстко защищены служебные теги: попытка зарегистрировать required, omitempty, dive, keys, endkeys или structonly падает паникой «Tag 'required' either contains restricted characters or is the same as a restricted tag needed for normal operation» — они грамматика разбора тега, и валидатор их не отдаёт. Остальные встроенные — min, max, email — формально перезаписываются без ошибки: не приглашение, а дыра, в которую легко наступить; своё поведение называйте своим именем. Имя тега выбирайте как имя функции: латиница, без пробелов и запятых — грамматика тега не оставляет места для вольностей. И держите функцию чистой: предикат, который берёт значение и отвечает bool, без изменения состояния, без времени и сети — причины разобраны ниже, а пока договорённость.

Тег может нести параметр после знака равенства — это fl.Param() внутри функции, строка без трюков: «5» для multiple=5, перечень через пробел для списка значений. Параметр — способ сделать один тег семейством правил вместо десяти тегов на каждый случай: multiple=5 и multiple=100 обслуживаются одной функцией, а если завтра бизнес попросит кратность двадцати, тег в структуре изменится без правки кода проверки — в этом весь смысл параметризации. Механика чтения честная: Param() приходит строкой, и разбор — ваша работа — strconv.Atoi с честной обработкой ошибки. Ошибка параметра — это ошибка программиста, не данных: тег написали руками, и «5о» в нём обнаружится на первом же тесте; функция возвращает false, и провал всплывает с именем тега. Внутри функции стоит дисциплина отражения: прежде чем звать Int() или String(), проверьте Kind() — тег, повешенный не на то поле, обязан честно провалиться, а не поднять панику reflect. Для значений-перечней держите грамматику из третьего урока: пробел внутри параметра разделяет значения, запятая между правилами — конвейер. И не забывайте Parent() из таблицы: функция видит родительскую структуру, поэтому «сумма кратна номиналу, но не больше остатка» может читаться из соседнего поля — а полноценные кросс-польные контракты это мост к StructLevel из одиннадцатого урока.

У собственных функций есть тихое соглашение, которое проявляется только на указателях и интерфейсах: по умолчанию валидатор НЕ вызывает вашу функцию на nil-поле. Указатель пуст — правило пропускается, поле считается пройденным, и это выглядит логично: проверять нечего. Но молчаливый пропуск — источник недоумений: тег есть, а проверки как будто нет. Если функция обязана видеть даже nil — например, чтобы различать «не указано» и «указано пусто» — у RegisterValidation есть третий вариадический аргумент: RegisterValidation("phone", fn, true) вызывает функцию и на нулевых полях, и внутри вы сами решаете, что с ними делать, через fl.Field().IsNil(). Комбинации с остальными тегами при этом обычные: required перед вашим тегом отловит nil и не пустит выполнение дальше, omitempty пропустит пустоту по договору опциональности. Практический вывод: свой тег на указателе — всегда случай из трёх, и тест должен показать, какой из них ваш: nil пропущен, nil проваливается, nil передаётся в функцию. Третий аргумент выручает там, где nil — легитимное значение с собственным смыслом: «не указано» в полях отчётности, дата без времени, опциональная ссылка на документ. Без теста разница живёт только в голове автора, а после рефакторинга живёт там неправильно.

Прежде чем писать функцию, спросите: а не собирается ли мой тег из существующих правил? RegisterAlias регистрирует новое имя для готовой комбинации: RegisterAlias("phone", "e164") — и тег phone означает встроенный формат E.164, без единой строки логики. Значение алиаса — готовая строка правил: с параметрами и с разделителем | для варианта «любое из», как в классическом примере с цветовыми форматами. Алиас не проверяет ничего сам — он словарь имён, и в этом его сила: правило меняется в одном месте, а теги по проекту остаются. С алиасами связана тонкость из пятого урока: Tag() вернёт ваше имя — phone, а ActualTag() — реальный тег e164; каталог сообщений ключуйте по Tag(), чтобы сообщение «телефон в формате +7...» жило под именем, которое видит ревьюер. Регистрация алиасов — на том же старте и с той же не-потокобезопасностью, что у RegisterValidation. Правило выбора простое: комбинация существующих правил — алиас; новая логика, которой нет среди встроенных тегов — функция. Если валидатору можно объяснить телефон через e164 — не пишите регулярку, форматы из четвёртого урока уже проверены сообществом.

Свой тег попадает в FieldError со своим именем — и каталог из шестого урока должен его знать: ветка case "phone" в tagTexts с формулировкой «телефон в формате +7XXXXXXXXXX». Без ветки сообщение уедет в default с технической строкой — тот же признак дыры в каталоге, что и у встроенных тегов. Тесты правил — вторая половина дисциплины: тег — строка в структуре, компилятор его не проверяет, а ваша функция проверяет только то, что ей дали. Пятёрка значений из третьего урока здесь работает в полный рост: валидное значение, валидное на границе, невалидный формат, пустое, nil для указателей — и к ним стоит добавить случай «тег повешен не на тот тип», если функция проверяет Kind. Табличные тесты для правил — готовый каркас из девятнадцатого урока, а регистрация в тестах использует тот же экземпляр, что и приложение. Имена тегов и ветки каталога стоит проверять одной связкой: тест, который прогоняет все зарегистрированные теги через пустую форму, заодно проверяет и полноту каталога — две защиты одной строкой. Отдельный тест на Param() не повредит: битый параметр сегодня — это false на всех полях сразу, и лучше узнать об этом в CI, чем в тикете «всё сломалось с обновлением».