validator - Go 结构体验证库

本文翻译整理自：https://github.com/go-playground/validator

一、关于 validator

validator 包实现了基于标签的结构体和字段值验证功能。

相关链接资源

• github : https://github.com/go-playground/validator
• 官方文档：https://pkg.go.dev/github.com/go-playground/validator/v10
• License : MIT

关键功能特性

具有以下独特功能：
1、通过验证标签或自定义验证器实现跨字段和跨结构体验证
2、支持切片、数组和映射的多层级嵌套验证
3、可同时验证映射的键和值
4、验证前自动识别接口的实际类型
5、支持自定义字段类型（如实现了 sql.driver.Valuer 接口的类型）
6、别名验证标签，可将多个验证映射到单个标签以简化结构体定义
7、可提取自定义字段名（如提取 JSON 字段名用于错误提示）
8、支持可定制的国际化错误消息
9、作为 gin 框架的默认验证器（从 v8 升级到 v9 的指南见 https://github.com/go-playground/validator/tree/master/_examples/gin-upgrading-overriding）

二、维护者招募

有意参与维护本项目的开发者请阅读 https://github.com/go-playground/validator/discussions/1330 中的讨论。

三、安装

使用 go get 安装：

go get github.com/go-playground/validator/v10

然后在代码中导入：

import "github.com/go-playground/validator/v10"

四、错误返回值

验证函数返回 error 类型，这种设计避免了以下讨论中提到的问题（err 总是 != nil）：

• http://stackoverflow.com/a/29138676/3158232
• https://github.com/go-playground/validator/issues/134

验证器仅对错误的验证输入返回 InvalidValidationError，正常情况下返回 nil 或 ValidationErrors。因此代码中只需检查返回的 error 是否为 nil，必要时可将其转换为 ValidationErrors 类型：

err := validate.Struct(mystruct)
validationErrors := err.(validator.ValidationErrors)

五、使用文档

详细用法请参考：https://pkg.go.dev/github.com/go-playground/validator/v10

示例代码

• 基础用法
• 自定义字段类型
• 结构体层级验证
• 多语言与自定义错误
• Gin 框架验证器升级/覆盖
• 完整示例应用 wash

六、内置验证规则

特别说明

对于新用户，强烈建议使用 WithRequiredStructEnabled 选项初始化验证器，该选项启用了将在 v11+ 版本成为默认行为的新特性：

validate := validator.New(validator.WithRequiredStructEnabled())

字段验证

网络验证

字符串验证

格式验证

比较验证

其他验证

别名

七、性能基准

测试环境：MacBook Pro Max M3

go version go1.23.3 darwin/arm64
goos: darwin
goarch: arm64
cpu: Apple M3 Max
pkg: github.com/go-playground/validator/v10
BenchmarkFieldSuccess-16                                                42461943                27.88 ns/op            0 B/op          0 allocs/op
BenchmarkFieldSuccessParallel-16                                        486632887                2.289 ns/op           0 B/op          0 allocs/op
BenchmarkFieldFailure-16                                                 9566167               121.3 ns/op           200 B/op          4 allocs/op
BenchmarkFieldFailureParallel-16                                        17551471                83.68 ns/op          200 B/op          4 allocs/op
BenchmarkFieldArrayDiveSuccess-16                                        7602306               155.6 ns/op            97 B/op          5 allocs/op
BenchmarkFieldArrayDiveSuccessParallel-16                               20664610                59.80 ns/op           97 B/op          5 allocs/op
BenchmarkFieldArrayDiveFailure-16                                        4659756               252.9 ns/op           301 B/op         10 allocs/op
BenchmarkFieldArrayDiveFailureParallel-16                                8010116               152.9 ns/op           301 B/op         10 allocs/op
BenchmarkFieldMapDiveSuccess-16                                          2834575               421.2 ns/op           288 B/op         14 allocs/op
BenchmarkFieldMapDiveSuccessParallel-16                                  7179700               171.8 ns/op           288 B/op         14 allocs/op
BenchmarkFieldMapDiveFailure-16                                          3081728               384.4 ns/op           376 B/op         13 allocs/op
BenchmarkFieldMapDiveFailureParallel-16                                  6058137               204.0 ns/op           377 B/op         13 allocs/op
BenchmarkFieldMapDiveWithKeysSuccess-16                                  2544975               464.8 ns/op           288 B/op         14 allocs/op
BenchmarkFieldMapDiveWithKeysSuccessParallel-16                          6661954               181.4 ns/op           288 B/op         14 allocs/op
BenchmarkFieldMapDiveWithKeysFailure-16                                  2435484               490.7 ns/op           553 B/op         16 allocs/op
BenchmarkFieldMapDiveWithKeysFailureParallel-16                          4249617               282.0 ns/op           554 B/op         16 allocs/op
BenchmarkFieldCustomTypeSuccess-16                                      14943525                77.35 ns/op           32 B/op          2 allocs/op
BenchmarkFieldCustomTypeSuccessParallel-16                              64051954                20.61 ns/op           32 B/op          2 allocs/op
BenchmarkFieldCustomTypeFailure-16                                      10721384               107.1 ns/op           184 B/op          3 allocs/op
BenchmarkFieldCustomTypeFailureParallel-16                              18714495                69.77 ns/op          184 B/op          3 allocs/op
BenchmarkFieldOrTagSuccess-16                                            4063124               294.3 ns/op            16 B/op          1 allocs/op
BenchmarkFieldOrTagSuccessParallel-16                                   31903756                41.22 ns/op           18 B/op          1 allocs/op
BenchmarkFieldOrTagFailure-16                                            7748558               146.8 ns/op           216 B/op          5 allocs/op
BenchmarkFieldOrTagFailureParallel-16                                   13139854                92.05 ns/op          216 B/op          5 allocs/op
BenchmarkStructLevelValidationSuccess-16                                16808389                70.25 ns/op           16 B/op          1 allocs/op
BenchmarkStructLevelValidationSuccessParallel-16                        90686955                14.47 ns/op           16 B/op          1 allocs/op
BenchmarkStructLevelValidationFailure-16                                 5818791               200.2 ns/op           264 B/op          7 allocs/op
BenchmarkStructLevelValidationFailureParallel-16                        11115874               107.5 ns/op           264 B/op          7 allocs/op
BenchmarkStructSimpleCustomTypeSuccess-16                                7764956               151.9 ns/op            32 B/op          2 allocs/op
BenchmarkStructSimpleCustomTypeSuccessParallel-16                       52316265                30.37 ns/op           32 B/op          2 allocs/op
BenchmarkStructSimpleCustomTypeFailure-16                                4195429               277.2 ns/op           416 B/op          9 allocs/op
BenchmarkStructSimpleCustomTypeFailureParallel-16                        7305661               164.6 ns/op           432 B/op         10 allocs/op
BenchmarkStructFilteredSuccess-16                                        6312625               186.1 ns/op           216 B/op          5 allocs/op
BenchmarkStructFilteredSuccessParallel-16                               13684459                93.42 ns/op          216 B/op          5 allocs/op
BenchmarkStructFilteredFailure-16                                        6751482               171.2 ns/op           216 B/op          5 allocs/op
BenchmarkStructFilteredFailureParallel-16                               14146070                86.93 ns/op          216 B/op          5 allocs/op
BenchmarkStructPartialSuccess-16                                         6544448               177.3 ns/op           224 B/op          4 allocs/op
BenchmarkStructPartialSuccessParallel-16                                13951946                88.73 ns/op          224 B/op          4 allocs/op
BenchmarkStructPartialFailure-16                                         4075833               287.5 ns/op           440 B/op          9 allocs/op
BenchmarkStructPartialFailureParallel-16                                 7490805               161.3 ns/op           440 B/op          9 allocs/op
BenchmarkStructExceptSuccess-16                                          4107187               281.4 ns/op           424 B/op          8 allocs/op
BenchmarkStructExceptSuccessParallel-16                                 15979173                80.86 ns/op          208 B/op          3 allocs/op
BenchmarkStructExceptFailure-16                                          4434372               264.3 ns/op           424 B/op          8 allocs/op
BenchmarkStructExceptFailureParallel-16                                  808136