Documentation
¶
Overview ¶
Package validator 提供统一的参数验证能力。
基于 go-playground/validator，封装为面向接口的验证门面。 支持 struct tag 验证、自定义规则和结构体验证错误格式化。 HTTP 框架相关的绑定逻辑位于 hertz/validatorh。
用法:
type CreateUserReq struct {
Name string `json:"name" validate:"required,min=1,max=100"`
Email string `json:"email" validate:"required,email"`
Age int `json:"age" validate:"gte=0,lte=150"`
}
// 直接验证结构体
err := validator.Validate(&req)
Index ¶
- Variables
- func IsValidationError(err error) bool
- func RegisterTranslation(locale, tag, msg string) error
- func RegisterValidation(tag string, fn Func) error
- func SetDefault(v Validator)
- func Validate(obj any) error
- func ValidateVar(field any, tag string) error
- func ValidateVarNamed(field any, fieldName string, tag string) error
- type FieldError
- type Func
- type PlaygroundValidator
- func (pv *PlaygroundValidator) RegisterTranslation(locale, tag, msg string) error
- func (pv *PlaygroundValidator) RegisterValidation(tag string, fn Func) error
- func (pv *PlaygroundValidator) Validate(obj any) error
- func (pv *PlaygroundValidator) ValidateVar(field any, tag string) error
- func (pv *PlaygroundValidator) ValidateVarNamed(field any, fieldName string, tag string) error
- func (pv *PlaygroundValidator) Validate_() *validator.Validate
- type ValidationError
- type Validator
- type VarValidatorWithName
Constants ¶
This section is empty.
Variables ¶
var ErrTranslationNotSupported = errors.New("validator: translation not supported; messages are built-in via formatMessage")
ErrTranslationNotSupported 表示当前验证器不支持错误消息翻译。 PlaygroundValidator 的错误消息已通过 formatMessage 内置英文提示， 如需自定义消息请扩展 formatMessage 或实现自定义 Validator。
Functions ¶
func IsValidationError ¶
IsValidationError 检查错误是否为 ValidationError 类型。
func RegisterTranslation ¶
RegisterTranslation 注册验证错误的翻译。
func RegisterValidation ¶
RegisterValidation 注册自定义验证规则。 ⚠️ 必须在 init 阶段（任何 Struct 校验开始前）调用：底层 go-playground/validator 的注册写内部 map 与校验读并发不安全， 运行期（流量中）注册会构成数据竞争。
func SetDefault ¶
func SetDefault(v Validator)
SetDefault 设置全局默认验证器。
v 为 nil 时**直接 panic**：存进去之后，Default() 会返回 nil 接口， 后续每一次 Default().Validate(obj) 都是空指针崩溃——崩在调用方、栈里只看 得到「validator.Default().Validate」这一行，完全看不出是这里存了个 nil。 快速失败比静默埋雷好。
func ValidateVar ¶
ValidateVar 验证单个变量。
底层校验器在单变量路径上给不出字段名 ⇒ 错误消息里的主语是兜底的 "value"。需要真实字段名（逐字段校验请求参数时）请用 ValidateVarNamed。
Types ¶
type FieldError ¶
type FieldError struct {
Field string `json:"field"` // 字段名
Tag string `json:"tag"` // 验证标签
Param string `json:"param,omitempty"` // 标签参数
Message string `json:"message"` // 错误消息
}
FieldError 表示单个字段的验证错误。
type PlaygroundValidator ¶
type PlaygroundValidator struct {
// contains filtered or unexported fields
}
PlaygroundValidator 是基于 go-playground/validator 的验证器实现。
func (*PlaygroundValidator) RegisterTranslation ¶
func (pv *PlaygroundValidator) RegisterTranslation(locale, tag, msg string) error
RegisterTranslation 注册验证错误的翻译。
当前实现不支持翻译引擎：错误消息已通过 formatMessage English prompts via formatMessage。 调用将始终返回 ErrTranslationNotSupported，避免调用方误以为翻译已注册成功。 如需自定义消息，请扩展 formatMessage 或实现自定义 Validator。
func (*PlaygroundValidator) RegisterValidation ¶
func (pv *PlaygroundValidator) RegisterValidation(tag string, fn Func) error
RegisterValidation 注册自定义验证规则。
func (*PlaygroundValidator) Validate ¶
func (pv *PlaygroundValidator) Validate(obj any) error
Validate 验证结构体。
func (*PlaygroundValidator) ValidateVar ¶
func (pv *PlaygroundValidator) ValidateVar(field any, tag string) error
ValidateVar 验证单个变量。
**没有字段名可用**：底层 go-playground/validator 的 Var 路径不提供字段名 （fe.Field() 为空串）⇒ 此前错误消息是 " is required"（前导空格、没有主语）， ValidationError.Map() 还会多出一个空字符串键 ""。这里用 "value" 作兜底主语； 需要真实字段名请用 ValidateVarNamed。
func (*PlaygroundValidator) ValidateVarNamed ¶ added in v0.3.3
func (pv *PlaygroundValidator) ValidateVarNamed(field any, fieldName string, tag string) error
ValidateVarNamed 验证单个变量并带上字段名。
错误消息的主语与 ValidationError.Map() 的键都用 fieldName—— 单变量校验最常见的用法（逐字段校验请求参数）需要知道是**哪个**字段没过。
func (*PlaygroundValidator) Validate_ ¶
func (pv *PlaygroundValidator) Validate_() *validator.Validate
Validate_ 返回底层验证器实例，供高级用户直接使用。
type ValidationError ¶
type ValidationError struct {
// contains filtered or unexported fields
}
ValidationError 包含多个字段验证错误。 实现 BizError 接口（code=400），handler 层的 Fail 会自动识别为 400 Bad Request。
func AsValidationError ¶
func AsValidationError(err error) (*ValidationError, bool)
AsValidationError 从错误链中提取 ValidationError（支持 errors.As 链式匹配）。
func NewFieldValidationError ¶
func NewFieldValidationError(errors []FieldError) *ValidationError
NewFieldValidationError 创建包含指定字段错误的验证错误。 供 handler/validatorh 等外部包构造 ValidationError。
func (*ValidationError) Error ¶
func (e *ValidationError) Error() string
Error 实现 error 接口，返回第一个错误消息。
func (*ValidationError) Map ¶
func (e *ValidationError) Map() map[string]string
Map 返回 field→message 映射，适用于 JSON 响应。
func (*ValidationError) Unwrap ¶
func (e *ValidationError) Unwrap() error
Unwrap 返回底层的 BizError（BizCode=400, HTTPCode=400），使 errors.As 能识别为 BizError。 这样 handler 层的 Fail 会自动返回 400 Bad Request，而非 500。
type Validator ¶
type Validator interface {
// Validate 验证结构体（基于 struct tag）。
Validate(obj any) error
// ValidateVar 验证单个变量。
ValidateVar(field any, tag string) error
// RegisterValidation 注册自定义验证规则。
RegisterValidation(tag string, fn Func) error
// RegisterTranslation 注册验证错误的翻译。
RegisterTranslation(locale, tag, msg string) error
}
Validator 是参数验证接口。
type VarValidatorWithName ¶ added in v0.3.3
type VarValidatorWithName interface {
// ValidateVarNamed 验证单个变量，错误消息与结构化错误里带上 fieldName。
ValidateVarNamed(field any, fieldName string, tag string) error
}
VarValidatorWithName 是支持「带字段名」的单变量验证器（**可选接口**）。
放在包级而不塞进 Validator 接口：给 Validator 加方法是破坏性变更 （仓外自定义实现会被迫改），而这是加法——实现方实现了它， ValidateVarNamed 就用它；没实现就退回 ValidateVar（字段名退化为 "value"）。
Source Files