go-playground/validator
GitHub: go-playground/validator
Go 语言高性能结构体验证库，通过标签实现声明式字段校验，支持跨字段、嵌套结构和国际化错误消息。
Stars: 19792 | Forks: 1410
# Package 验证器
[](https://github.com/go-playground/validator/releases)
[](https://github.com/go-playground/validator/actions)
[](https://coveralls.io/github/go-playground/validator?branch=master)
[](https://goreportcard.com/report/github.com/go-playground/validator)
[](https://pkg.go.dev/github.com/go-playground/validator/v10)
Package validator 基于标签为结构体和单个字段实现值验证。
它具有以下**独特**功能：
- 通过使用验证标签或自定义验证器，支持跨字段和跨结构体验证。
- Slice、Array 和 Map 深入（diving），允许验证多维字段的任意或所有层级。
- 能够深入 map 的键和值进行验证。
- 通过在验证前确定底层类型来处理接口类型。
- 处理自定义字段类型，例如 sql driver [Valuer](https://golang.org/src/database/sql/driver/types.go?s=1210:1293#L29) 和 [Valuer interface](https://github.com/go-playground/validator/blob/master/_examples/valuer/main.go)
- 别名验证标签，允许将多个验证映射到单个标签，以便更轻松地在结构体上定义验证。
- 提取自定义定义的字段名，例如，可以指定在验证时提取 JSON 名称，并使其在生成的 FieldError 中可用。
- 可定制的 i18n 感知错误消息。
- [gin](https://github.com/gin-gonic/gin) web 框架的默认验证器；在 gin 中从 v8 升级到 v9 请参见[此处](https://github.com/go-playground/validator/tree/master/_examples/gin-upgrading-overriding)
## 维护者招募
如果您有兴趣贡献或帮助维护此 package，请阅读[此处](https://github.com/go-playground/validator/discussions/1330)开始的讨论。
## 安装
使用 go get。
```
go get github.com/go-playground/validator/v10
```
然后将 validator package 导入您自己的代码中。
```
import "github.com/go-playground/validator/v10"
```
## 错误返回值
验证函数返回 error 类型。
它们返回 error 类型是为了避免以下讨论的问题，即 err 总是 != nil：
* http://stackoverflow.com/a/29138676/3158232
* https://github.com/go-playground/validator/issues/134
Validator 仅针对错误的验证输入返回 InvalidValidationError，nil 或 ValidationErrors 作为 error 类型；因此，在您的代码中，您只需要检查返回的 error 是否不为 nil，如果不为 nil，再检查 error 是否为 InvalidValidationError（如有必要，大多数情况下不需要），将其类型断言为 ValidationErrors 类型，如下所示：
```
err := validate.Struct(mystruct)
validationErrors := err.(validator.ValidationErrors)
```
## 用法和文档
详细的使用文档请参阅 https://pkg.go.dev/github.com/go-playground/validator/v10。
##### 示例：
- [简单示例](https://github.com/go-playground/validator/blob/master/_examples/simple/main.go)
- [自定义字段类型](https://github.com/go-playground/validator/blob/master/_examples/custom/main.go)
- [结构体级别](https://github.com/go-playground/validator/blob/master/_examples/struct-level/main.go)
- [翻译与自定义错误](https://github.com/go-playground/validator/blob/master/_examples/translations/main.go)
- [Gin 升级和/或覆盖 validator](https://github.com/go-playground/validator/tree/v9/_examples/gin-upgrading-overriding)
- [wash - 一个将其整合在一起的示例应用](https://github.com/bluesuncorp/wash)
## 内置验证
### 特别说明：
- 如果初次使用 validator，强烈建议使用 `WithRequiredStructEnabled` 选项进行初始化，该选项是 v11+ 版本中将称为默认行为的新特性的可选启用。详情请参阅文档。
```
validate := validator.New(validator.WithRequiredStructEnabled())
```
### 字段：
| Tag | Description |
| - | - |
| eqcsfield | 字段等于另一个字段（相对）|
| eqfield | 字段等于另一个字段 |
| fieldcontains | 检查字段中是否存在指定的字符 |
| fieldexcludes | 检查字段中是否不存在指定的字符 |
| gtcsfield | 字段大于另一个相对字段 |
| gtecsfield | 字段大于或等于另一个相对字段 |
| gtefield | 字段大于或等于另一个字段 |
| gtfield | 字段大于另一个字段 |
| ltcsfield | 小于另一个相对字段 |
| ltecsfield | 小于或等于另一个相对字段 |
| ltefield | 小于或等于另一个字段 |
| ltfield | 小于另一个字段 |
| necsfield | 字段不等于另一个字段（相对）|
| nefield | 字段不等于另一个字段 |
### 网络：
| Tag | Description |
| - | - |
| cidr | 无类别域间路由 CIDR |
| cidrv4 | 无类别域间路由 CIDRv4 |
| cidrv6 | 无类别域间路由 CIDRv6 |
| datauri | Data URL |
| fqdn | 完全限定域名 (FQDN) |
| hostname | 主机名 RFC 952 |
| hostname_rfc1123 | 主机名 RFC 1123 |
| hostname_port | 主机端口 |
| port | 端口号 |
| 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 域套接字端点地址 |
| uds_exists | Unix 域套接字存在（检查文件系统套接字和 Linux 抽象套接字）|
| uri | URI 字符串 |
| url | URL 字符串 |
| http_url | HTTP(s) URL 字符串 |
| https_url | 仅 HTTPS URL 字符串 |
| url_encoded | URL 编码 |
| urn_rfc2141 | Urn RFC 2141 字符串 |
### 字符串：
| Tag | Description |
| - | - |
| alpha | 仅字母 |
| alphaspace | 字母空格 |
| alphanum | 字母数字 |
| alphanumspace | 字母数字空格 |
| 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 | 大写 |
### 格式：
| Tag | Description |
| - | - |
| base64 | Base64 字符串 |
| base64url | Base64URL 字符串 |
| base64rawurl | Base64RawURL 字符串 |
| bic_iso_9362_2014 | 业务标识符代码 (ISO 9362:2014) |
| bic | 业务标识符代码 (ISO 9362:2022) |
| 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/Permission/Type |
| datetime | 日期时间 |
| e164 | e164 格式电话号码 |
| ein | 美国雇主识别号 |
| email | 电子邮件字符串
| eth_addr | 以太坊地址 |
| hexadecimal | 十六进制字符串 |
| hexcolor | 十六进制颜色字符串 |
| hsl | HSL 字符串 |
| hsla | HSLA 字符串 |
| cmyk | CMYK 字符串 |
| 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 (JWT) |
| latitude | 纬度 |
| longitude | 经度 |
| luhn_checksum | Luhn 算法校验和（用于字符串和 (u)int）|
| postcode_iso3166_alpha2 | 邮政编码 |
| postcode_iso3166_alpha2_field | 邮政编码 |
| rgb | RGB 字符串 |
| rgba | RGBA 字符串 |
| ssn | 社会保障号 SSN |
| timezone | 时区 |
| uuid | 通用唯一识别码 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 | 通用唯一字典排序标识符 ULID |
| cve | 通用漏洞披露标识符 (CVE id) |
### 比较：
| Tag | Description |
| - | - |
| eq | 等于 |
| eq_ignore_case | 等于（忽略大小写）|
| gt | 大于|
| gte | 大于或等于 |
| lt | 小于 |
| lte | 小于或等于 |
| ne | 不等于 |
| ne_ignore_case | 不等于（忽略大小写）|
### 其他：
| Tag | Description |
| - | - |
| 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 | 验证方法 `Validate() error` 是否未返回错误（或任何指定的方法）|
#### 别名：
| Tag | Description |
| - | - |
| iscolor | hexcolor\|rgb\|rgba\|hsl\|hsla\|cmyk |
| country_code | iso3166_1_alpha2\|iso3166_1_alpha3\|iso3166_1_alpha_numeric |
## 基准测试
###### 运行于 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 8081367 154.1 ns/op 424 B/op 8 allocs/op
BenchmarkStructSimpleCrossFieldSuccess-16 6459542 183.4 ns/op 56 B/op 3 allocs/op
BenchmarkStructSimpleCrossFieldSuccessParallel-16 41013781 37.95 ns/op 56 B/op 3 allocs/op
BenchmarkStructSimpleCrossFieldFailure-16 4034998 292.1 ns/op 272 B/op 8 allocs/op
BenchmarkStructSimpleCrossFieldFailureParallel-16 11348446 115.3 ns/op 272 B/op 8 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccess-16 4448528 267.7 ns/op 64 B/op 4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccessParallel-16 26813619 48.33 ns/op 64 B/op 4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailure-16 3090646 384.5 ns/op 288 B/op 9 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailureParallel-16 9870906 129.5 ns/op 288 B/op 9 allocs/op
BenchmarkStructSimpleSuccess-16 10675562 109.5 ns/op 0 B/op 0 allocs/op
BenchmarkStructSimpleSuccessParallel-16 131159784 8.932 ns/op 0 B/op 0 allocs/op
BenchmarkStructSimpleFailure-16 4094979 286.6 ns/op 416 B/op 9 allocs/op
BenchmarkStructSimpleFailureParallel-16 7606663 157.9 ns/op 416 B/op 9 allocs/op
BenchmarkStructComplexSuccess-16 2073470 576.0 ns/op 224 B/op 5 allocs/op
BenchmarkStructComplexSuccessParallel-16 7821831 161.3 ns/op 224 B/op 5 allocs/op
BenchmarkStructComplexFailure-16 576358 2001 ns/op 3042 B/op 48 allocs/op
BenchmarkStructComplexFailureParallel-16 1000000 1171 ns/op 3041 B/op 48 allocs/op
BenchmarkOneof-16 22503973 52.82 ns/op 0 B/op 0 allocs/op
BenchmarkOneofParallel-16 8538474 140.4 ns/op 0 B/op 0 allocs/op
```
## 互补软件
以下是在验证之前或之后补充使用此库的软件列表。
* [form](https://github.com/go-playground/form) - 将 url.Values 解码为 Go 值，并将 Go 值编码为 url.Values。支持双数组和完整 map。
* [mold](https://github.com/go-playground/mold) - 一个通用库，用于帮助修改或设置数据结构和其他对象中的数据
## SDK 主要版本的维护和支持
更多详情请参阅[此处](_URL_18/>)之前的讨论。
此 package 与 [Go 发布策略](https://go.dev/doc/devel/release)保持一致，即保证支持
最近的两个主要版本。
这并不意味着该 package 不适用于旧版本的 Go，仅表示我们保留在需要解决安全问题/补丁、操作系统问题和支持
或新引入的功能（将极大地有益于此 package 的维护和/或使用）时
提高 MSGV（最低支持 Go 版本）的权利。
如果并且当提高 MSGV 时，将至少在 `Minor` 版本更新中进行。
## 许可证
根据 MIT 许可证分发，请在代码中的许可证文件中查看更多详细信息。
## 维护者
这个项目已经发展到足够大，需要不止一个人来适当支持社区。
如果您有兴趣成为维护者，请通过 https://github.com/deankarn 联系我
[](https://github.com/go-playground/validator/releases)
[](https://github.com/go-playground/validator/actions)
[](https://coveralls.io/github/go-playground/validator?branch=master)
[](https://goreportcard.com/report/github.com/go-playground/validator)
[](https://pkg.go.dev/github.com/go-playground/validator/v10)
Package validator 基于标签为结构体和单个字段实现值验证。
它具有以下**独特**功能：
- 通过使用验证标签或自定义验证器，支持跨字段和跨结构体验证。
- Slice、Array 和 Map 深入（diving），允许验证多维字段的任意或所有层级。
- 能够深入 map 的键和值进行验证。
- 通过在验证前确定底层类型来处理接口类型。
- 处理自定义字段类型，例如 sql driver [Valuer](https://golang.org/src/database/sql/driver/types.go?s=1210:1293#L29) 和 [Valuer interface](https://github.com/go-playground/validator/blob/master/_examples/valuer/main.go)
- 别名验证标签，允许将多个验证映射到单个标签，以便更轻松地在结构体上定义验证。
- 提取自定义定义的字段名，例如，可以指定在验证时提取 JSON 名称，并使其在生成的 FieldError 中可用。
- 可定制的 i18n 感知错误消息。
- [gin](https://github.com/gin-gonic/gin) web 框架的默认验证器；在 gin 中从 v8 升级到 v9 请参见[此处](https://github.com/go-playground/validator/tree/master/_examples/gin-upgrading-overriding)
## 维护者招募
如果您有兴趣贡献或帮助维护此 package，请阅读[此处](https://github.com/go-playground/validator/discussions/1330)开始的讨论。
## 安装
使用 go get。
```
go get github.com/go-playground/validator/v10
```
然后将 validator package 导入您自己的代码中。
```
import "github.com/go-playground/validator/v10"
```
## 错误返回值
验证函数返回 error 类型。
它们返回 error 类型是为了避免以下讨论的问题，即 err 总是 != nil：
* http://stackoverflow.com/a/29138676/3158232
* https://github.com/go-playground/validator/issues/134
Validator 仅针对错误的验证输入返回 InvalidValidationError，nil 或 ValidationErrors 作为 error 类型；因此，在您的代码中，您只需要检查返回的 error 是否不为 nil，如果不为 nil，再检查 error 是否为 InvalidValidationError（如有必要，大多数情况下不需要），将其类型断言为 ValidationErrors 类型，如下所示：
```
err := validate.Struct(mystruct)
validationErrors := err.(validator.ValidationErrors)
```
## 用法和文档
详细的使用文档请参阅 https://pkg.go.dev/github.com/go-playground/validator/v10。
##### 示例：
- [简单示例](https://github.com/go-playground/validator/blob/master/_examples/simple/main.go)
- [自定义字段类型](https://github.com/go-playground/validator/blob/master/_examples/custom/main.go)
- [结构体级别](https://github.com/go-playground/validator/blob/master/_examples/struct-level/main.go)
- [翻译与自定义错误](https://github.com/go-playground/validator/blob/master/_examples/translations/main.go)
- [Gin 升级和/或覆盖 validator](https://github.com/go-playground/validator/tree/v9/_examples/gin-upgrading-overriding)
- [wash - 一个将其整合在一起的示例应用](https://github.com/bluesuncorp/wash)
## 内置验证
### 特别说明：
- 如果初次使用 validator，强烈建议使用 `WithRequiredStructEnabled` 选项进行初始化，该选项是 v11+ 版本中将称为默认行为的新特性的可选启用。详情请参阅文档。
```
validate := validator.New(validator.WithRequiredStructEnabled())
```
### 字段：
| Tag | Description |
| - | - |
| eqcsfield | 字段等于另一个字段（相对）|
| eqfield | 字段等于另一个字段 |
| fieldcontains | 检查字段中是否存在指定的字符 |
| fieldexcludes | 检查字段中是否不存在指定的字符 |
| gtcsfield | 字段大于另一个相对字段 |
| gtecsfield | 字段大于或等于另一个相对字段 |
| gtefield | 字段大于或等于另一个字段 |
| gtfield | 字段大于另一个字段 |
| ltcsfield | 小于另一个相对字段 |
| ltecsfield | 小于或等于另一个相对字段 |
| ltefield | 小于或等于另一个字段 |
| ltfield | 小于另一个字段 |
| necsfield | 字段不等于另一个字段（相对）|
| nefield | 字段不等于另一个字段 |
### 网络：
| Tag | Description |
| - | - |
| cidr | 无类别域间路由 CIDR |
| cidrv4 | 无类别域间路由 CIDRv4 |
| cidrv6 | 无类别域间路由 CIDRv6 |
| datauri | Data URL |
| fqdn | 完全限定域名 (FQDN) |
| hostname | 主机名 RFC 952 |
| hostname_rfc1123 | 主机名 RFC 1123 |
| hostname_port | 主机端口 |
| port | 端口号 |
| 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 域套接字端点地址 |
| uds_exists | Unix 域套接字存在（检查文件系统套接字和 Linux 抽象套接字）|
| uri | URI 字符串 |
| url | URL 字符串 |
| http_url | HTTP(s) URL 字符串 |
| https_url | 仅 HTTPS URL 字符串 |
| url_encoded | URL 编码 |
| urn_rfc2141 | Urn RFC 2141 字符串 |
### 字符串：
| Tag | Description |
| - | - |
| alpha | 仅字母 |
| alphaspace | 字母空格 |
| alphanum | 字母数字 |
| alphanumspace | 字母数字空格 |
| 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 | 大写 |
### 格式：
| Tag | Description |
| - | - |
| base64 | Base64 字符串 |
| base64url | Base64URL 字符串 |
| base64rawurl | Base64RawURL 字符串 |
| bic_iso_9362_2014 | 业务标识符代码 (ISO 9362:2014) |
| bic | 业务标识符代码 (ISO 9362:2022) |
| 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/Permission/Type |
| datetime | 日期时间 |
| e164 | e164 格式电话号码 |
| ein | 美国雇主识别号 |
| email | 电子邮件字符串
| eth_addr | 以太坊地址 |
| hexadecimal | 十六进制字符串 |
| hexcolor | 十六进制颜色字符串 |
| hsl | HSL 字符串 |
| hsla | HSLA 字符串 |
| cmyk | CMYK 字符串 |
| 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 (JWT) |
| latitude | 纬度 |
| longitude | 经度 |
| luhn_checksum | Luhn 算法校验和（用于字符串和 (u)int）|
| postcode_iso3166_alpha2 | 邮政编码 |
| postcode_iso3166_alpha2_field | 邮政编码 |
| rgb | RGB 字符串 |
| rgba | RGBA 字符串 |
| ssn | 社会保障号 SSN |
| timezone | 时区 |
| uuid | 通用唯一识别码 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 | 通用唯一字典排序标识符 ULID |
| cve | 通用漏洞披露标识符 (CVE id) |
### 比较：
| Tag | Description |
| - | - |
| eq | 等于 |
| eq_ignore_case | 等于（忽略大小写）|
| gt | 大于|
| gte | 大于或等于 |
| lt | 小于 |
| lte | 小于或等于 |
| ne | 不等于 |
| ne_ignore_case | 不等于（忽略大小写）|
### 其他：
| Tag | Description |
| - | - |
| 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 | 验证方法 `Validate() error` 是否未返回错误（或任何指定的方法）|
#### 别名：
| Tag | Description |
| - | - |
| iscolor | hexcolor\|rgb\|rgba\|hsl\|hsla\|cmyk |
| country_code | iso3166_1_alpha2\|iso3166_1_alpha3\|iso3166_1_alpha_numeric |
## 基准测试
###### 运行于 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 8081367 154.1 ns/op 424 B/op 8 allocs/op
BenchmarkStructSimpleCrossFieldSuccess-16 6459542 183.4 ns/op 56 B/op 3 allocs/op
BenchmarkStructSimpleCrossFieldSuccessParallel-16 41013781 37.95 ns/op 56 B/op 3 allocs/op
BenchmarkStructSimpleCrossFieldFailure-16 4034998 292.1 ns/op 272 B/op 8 allocs/op
BenchmarkStructSimpleCrossFieldFailureParallel-16 11348446 115.3 ns/op 272 B/op 8 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccess-16 4448528 267.7 ns/op 64 B/op 4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldSuccessParallel-16 26813619 48.33 ns/op 64 B/op 4 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailure-16 3090646 384.5 ns/op 288 B/op 9 allocs/op
BenchmarkStructSimpleCrossStructCrossFieldFailureParallel-16 9870906 129.5 ns/op 288 B/op 9 allocs/op
BenchmarkStructSimpleSuccess-16 10675562 109.5 ns/op 0 B/op 0 allocs/op
BenchmarkStructSimpleSuccessParallel-16 131159784 8.932 ns/op 0 B/op 0 allocs/op
BenchmarkStructSimpleFailure-16 4094979 286.6 ns/op 416 B/op 9 allocs/op
BenchmarkStructSimpleFailureParallel-16 7606663 157.9 ns/op 416 B/op 9 allocs/op
BenchmarkStructComplexSuccess-16 2073470 576.0 ns/op 224 B/op 5 allocs/op
BenchmarkStructComplexSuccessParallel-16 7821831 161.3 ns/op 224 B/op 5 allocs/op
BenchmarkStructComplexFailure-16 576358 2001 ns/op 3042 B/op 48 allocs/op
BenchmarkStructComplexFailureParallel-16 1000000 1171 ns/op 3041 B/op 48 allocs/op
BenchmarkOneof-16 22503973 52.82 ns/op 0 B/op 0 allocs/op
BenchmarkOneofParallel-16 8538474 140.4 ns/op 0 B/op 0 allocs/op
```
## 互补软件
以下是在验证之前或之后补充使用此库的软件列表。
* [form](https://github.com/go-playground/form) - 将 url.Values 解码为 Go 值，并将 Go 值编码为 url.Values。支持双数组和完整 map。
* [mold](https://github.com/go-playground/mold) - 一个通用库，用于帮助修改或设置数据结构和其他对象中的数据
## SDK 主要版本的维护和支持
更多详情请参阅[此处](_URL_18/>)之前的讨论。
此 package 与 [Go 发布策略](https://go.dev/doc/devel/release)保持一致，即保证支持
最近的两个主要版本。
这并不意味着该 package 不适用于旧版本的 Go，仅表示我们保留在需要解决安全问题/补丁、操作系统问题和支持
或新引入的功能（将极大地有益于此 package 的维护和/或使用）时
提高 MSGV（最低支持 Go 版本）的权利。
如果并且当提高 MSGV 时，将至少在 `Minor` 版本更新中进行。
## 许可证
根据 MIT 许可证分发，请在代码中的许可证文件中查看更多详细信息。
## 维护者
这个项目已经发展到足够大，需要不止一个人来适当支持社区。
如果您有兴趣成为维护者，请通过 https://github.com/deankarn 联系我标签：API密钥检测, Gin, Gin框架, Go, Golang, Go-playground, i18n, Map验证, Ruby工具, Slice验证, Struct Tag, Struct Validator, Syscall, Web开发, 参数验证, 反射, 后端开发, 国际化, 安全编程, 安全过滤, 开源库, 搜索引擎爬虫, 数据校验, 数据清洗, 日志审计, 跨字段验证, 输入验证, 错误处理