当前位置：首页 > ai >正文

validator - Go 结构体验证库

ai 2025/5/14 13:07:20

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

一、关于 validator

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

关键功能特性

具有以下独特功能：
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())

字段验证

标签	描述
eqcsfield	等于另一个相对字段
eqfield	等于另一个字段
fieldcontains	字段包含指定字符
fieldexcludes	字段不包含指定字符
gtcsfield	大于另一个相对字段
gtecsfield	大于等于另一个相对字段
gtefield	大于等于另一个字段
gtfield	大于另一个字段
ltcsfield	小于另一个相对字段
ltecsfield	小于等于另一个相对字段
ltefield	小于等于另一个字段
ltfield	小于另一个字段
necsfield	不等于另一个相对字段
nefield	不等于另一个字段

网络验证

标签	描述
cidr	无类别域间路由 CIDR
cidrv4	IPv4 CIDR
cidrv6	IPv6 CIDR
datauri	数据 URL
fqdn	完全限定域名
hostname	主机名 (RFC 952)
hostname_port	主机端口
hostname_rfc1123	主机名 (RFC 1123)
ip	IP 地址
ip4_addr	IPv4 地址
ip6_addr	IPv6 地址
ip_addr	IP 地址
ipv4	IPv4 地址
ipv6	IPv6 地址
mac	MAC 地址
tcp4_addr	TCPv4 地址
tcp6_addr	TCPv6 地址
tcp_addr	TCP 地址
udp4_addr	UDPv4 地址
udp6_addr	UDPv6 地址
udp_addr	UDP 地址
unix_addr	Unix 域套接字地址
uri	URI 字符串
url	URL 字符串
http_url	HTTP URL 字符串
url_encoded	URL 编码字符串
urn_rfc2141	URN (RFC 2141) 字符串

字符串验证

标签	描述
alpha	仅字母
alphanum	字母数字
alphanumunicode	Unicode 字母数字
alphaunicode	Unicode 字母
ascii	ASCII 字符
boolean	布尔值
contains	包含指定字符串
containsany	包含任意指定字符
containsrune	包含指定 rune
endsnotwith	不以指定字符串结尾
endswith	以指定字符串结尾
excludes	不包含指定字符串
excludesall	不包含任何指定字符
excludesrune	不包含指定 rune
lowercase	小写字母
multibyte	多字节字符
number	数字
numeric	数值
printascii	可打印 ASCII 字符
startsnotwith	不以指定字符串开头
startswith	以指定字符串开头
uppercase	大写字母

格式验证

标签	描述
base64	Base64 字符串
base64url	Base64URL 字符串
base64rawurl	Base64RawURL 字符串
bic	银行标识码 (ISO 9362)
bcp47_language_tag	语言标签 (BCP 47)
btc_addr	比特币地址
btc_addr_bech32	比特币 Bech32 地址 (segwit)
credit_card	信用卡号
mongodb	MongoDB ObjectID
mongodb_connection_string	MongoDB 连接字符串
cron	Cron 表达式
spicedb	SpiceDb ObjectID/权限/类型
datetime	日期时间
e164	E.164 格式电话号码
ein	美国雇主识别号
email	电子邮件地址
eth_addr	以太坊地址
hexadecimal	十六进制字符串
hexcolor	十六进制颜色值
hsl	HSL 颜色值
hsla	HSLA 颜色值
html	HTML 标签
html_encoded	HTML 编码字符串
isbn	国际标准书号
isbn10	国际标准书号 10
isbn13	国际标准书号 13
issn	国际标准期刊号
iso3166_1_alpha2	双字母国家代码 (ISO 3166-1 alpha-2)
iso3166_1_alpha3	三字母国家代码 (ISO 3166-1 alpha-3)
iso3166_1_alpha_numeric	数字国家代码 (ISO 3166-1 numeric)
iso3166_2	国家行政区划代码 (ISO 3166-2)
iso4217	货币代码 (ISO 4217)
json	JSON 字符串
jwt	JSON Web Token
latitude	纬度
longitude	经度
luhn_checksum	Luhn 算法校验和
postcode_iso3166_alpha2	邮政编码
postcode_iso3166_alpha2_field	邮政编码字段
rgb	RGB 颜色值
rgba	RGBA 颜色值
ssn	社会安全号码
timezone	时区
uuid	通用唯一标识符
uuid3	UUID v3
uuid3_rfc4122	UUID v3 (RFC4122)
uuid4	UUID v4
uuid4_rfc4122	UUID v4 (RFC4122)
uuid5	UUID v5
uuid5_rfc4122	UUID v5 (RFC4122)
uuid_rfc4122	UUID (RFC4122)
md4	MD4 哈希
md5	MD5 哈希
sha256	SHA256 哈希
sha384	SHA384 哈希
sha512	SHA512 哈希
ripemd128	RIPEMD-128 哈希
ripemd128	RIPEMD-160 哈希
tiger128	TIGER128 哈希
tiger160	TIGER160 哈希
tiger192	TIGER192 哈希
semver	语义化版本 2.0.0
ulid	通用唯一字典排序标识符
cve	通用漏洞披露标识符

比较验证

标签	描述
eq	等于
eq_ignore_case	等于（忽略大小写）
gt	大于
gte	大于等于
lt	小于
lte	小于等于
ne	不等于
ne_ignore_case	不等于（忽略大小写）

其他验证

标签	描述
dir	存在的目录
dirpath	目录路径
file	存在的文件
filepath	文件路径
image	图像文件
isdefault	是默认值
len	长度
max	最大值
min	最小值
oneof	属于指定值之一
required	必填字段
required_if	条件必填
required_unless	除非条件否则必填
required_with	关联字段存在时必填
required_with_all	所有关联字段存在时必填
required_without	关联字段不存在时必填
required_without_all	所有关联字段不存在时必填
excluded_if	条件排除
excluded_unless	除非条件否则排除
excluded_with	关联字段存在时排除
excluded_with_all	所有关联字段存在时排除
excluded_without	关联字段不存在时排除
excluded_without_all	所有关联字段不存在时排除
unique	唯一值
validateFn	验证方法不返回错误

别名

标签	描述
iscolor	hexcolor
country_code	iso3166_1_alpha2

七、性能基准

测试环境：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