必须在init()或main()开头调用validate.RegisterValidation("tag", fn, false),fn签名须为func(fl validator.FieldLevel) bool,且tag名需与struct tag完全一致。

怎么注册字段级自定义 validator 函数
Kratos 本身不自带校验逻辑,底层用的是 github.com/go-playground/validator/v10,所以自定义 validator 的写法和原生 validator 一致,关键在 RegisterValidation 调用时机和函数签名。
常见错误是把注册逻辑放在 handler 或 middleware 里反复执行——这会 panic,因为 validator 实例不允许重复注册同名 tag。必须在应用初始化早期(比如 init() 或 main() 开头)只注册一次。
-
RegisterValidation第一个参数是 tag 名(如"phone"),要和 struct tag 里写的完全一致 - 第二个参数是
func(fl validator.FieldLevel) bool类型的验证函数,fl.Field()拿到反射值,fl.Param()可读取 tag 后的参数(如phone=11中的"11") - 第三个参数
callValidationEvenIfNull建议设为false,避免对空字符串、零值字段误触发(比如int字段为0时不该跑手机号校验)
struct tag 怎么写才能传参给自定义 validator
validator 支持带参数的 tag 写法,比如 `validate:"phone=11"`,但前提是你的注册函数能解析 fl.Param()。很多初学者直接写 `validate:"phone"` 却在函数里硬编码长度,导致规则无法复用。
典型场景是手机号校验:国内 11 位、海外可能 12–15 位。用参数可让同一个 validator 适配多地区。
- 注册时别漏掉
fl.Param()解析,例如:length, _ := strconv.Atoi(fl.Param()) - tag 中等号前后不能有空格:
"phone=11"✅,"phone = 11"❌(fl.Param()会返回空) - 若需多个参数,改用逗号分隔并手动拆解,validator 不原生支持键值对,比如
phone="11,86",再用strings.Split(fl.Param(), ",")
为什么自定义 validator 里取不到上下文或依赖?
validator 函数签名固定为 func(fl validator.FieldLevel) bool,它**不接收 context、不访问全局变量、不调用外部服务**——这是设计使然,保证校验纯函数化、无副作用、可并发安全。
常见踩坑是想在 validator 里查数据库判断 ID 是否存在,或调用 Redis 校验 token 有效性。这类逻辑必须上移到业务层(如 service 方法开头),而不是塞进 validator。
- 跨字段校验(比如
end_time > start_time)要用RegisterStructValidation,传入整个 struct 的reflect.Value - 需要依赖注入的复杂校验,建议封装成独立函数,在 handler 或 service 里显式调用,而非绑定到 tag
- validator 里 panic 会导致整个请求失败且堆栈不友好,务必用
defer func() { recover() }()包裹外部调用(但不推荐这么做)
中文错误提示怎么绑定到自定义 validator
validator 默认错误是英文,要支持中文得靠 ut.Translator 和 RegisterTranslation。但注意:内置翻译器(如 zh_translations.RegisterDefaultTranslations)只覆盖标准 tag(required、min 等),**不会自动翻译你注册的自定义 tag**。
必须手动为每个自定义 tag 注册中文文案,否则 err.Translate(trans) 返回空字符串或原始 tag 名。
- 调用
validate.RegisterTranslation("phone", trans, registrationFunc, translationFunc) -
registrationFunc定义如何提取字段名和参数,translationFunc返回最终提示,例如"{{.FieldName}} 格式不正确" - 字段名来自 struct tag 的
label(需提前用RegisterTagNameFunc绑定),不是 struct 字段名本身
自定义 validator 最容易被忽略的点是:它只负责“格式”和“单字段约束”,所有涉及状态、权限、关联数据的判断,都不该放在这里。放进去看似省事,后续维护、测试、排查都会变重。











