简介

今天我们来介绍一个非常实用的库——validatorvalidator用于对数据进行校验。在 Web 开发中,对用户传过来的数据我们都需要进行严格校验,防止用户的恶意请求。例如日期格式,用户年龄,性别等必须是正常的值,不能随意设置。

快速使用

先安装:

  1. $ go get gopkg.in/go-playground/validator.v10

后使用:

  1. package main
  2. import (
  3. "fmt"
  4. "gopkg.in/go-playground/validator.v10"
  5. )
  6. type User struct {
  7. Name string `validate:"min=6,max=10"`
  8. Age int `validate:"min=1,max=100"`
  9. }
  10. func main() {
  11. validate := validator.New()
  12. u1 := User{Name: "lidajun", Age: 18}
  13. err := validate.Struct(u1)
  14. fmt.Println(err)
  15. u2 := User{Name: "dj", Age: 101}
  16. err = validate.Struct(u2)
  17. fmt.Println(err)
  18. }

validator在结构体标签(struct tag)中定义字段的约束。使用validator验证数据之前,我们需要调用validator.New()创建一个验证器,这个验证器可以指定选项、添加自定义约束,然后通过调用它的Struct()方法来验证各种结构对象的字段是否符合定义的约束。

在上面代码中,我们定义了一个结构体UserUser有名称Name字段和年龄Age字段。通过minmax约束,我们设置Name的字符串长度为[6,10]之间,Age的范围为[1,100]

第一个对象NameAge字段都满足约束,故Struct()方法返回nil错误。第二个对象的Name字段值为dj,长度 2,小于最小值minAge字段值为 101,大于最大值max,故返回错误:

  1. <nil>
  2. Key: 'User.Name' Error:Field validation for 'Name' failed on the 'min' tag
  3. Key: 'User.Age' Error:Field validation for 'Age' failed on the 'max' tag

错误信息比较好理解,User.Name违反了min约束,User.Age违反了max约束,一眼就能看出问题所在。

注意:

  • validator已经更新迭代了很多版本,当前最新的版本是v10,各个版本之间有一些差异,大家平时在使用和阅读代码时要注意区分。我这里使用最新的版本v10作为演示版本;
  • 字符串长度和数值的范围都可以通过minmax来约束。

约束

validator提供了非常丰富的约束可供使用,下面依次来介绍。

范围约束

我们上面已经看到了使用minmax来约束字符串的长度或数值的范围,下面再介绍其它的范围约束。范围约束的字段类型有以下几种:

  • 对于数值,则约束其值;
  • 对于字符串,则约束其长度;
  • 对于切片、数组和map,则约束其长度。

下面如未特殊说明,则是根据上面各个类型对应的值与参数值比较。

  • len:等于参数值,例如len=10
  • max:小于等于参数值,例如max=10
  • min:大于等于参数值,例如min=10
  • eq:等于参数值,注意与len不同。对于字符串,eq约束字符串本身的值,而len约束字符串长度。例如eq=10
  • ne:不等于参数值,例如ne=10
  • gt:大于参数值,例如gt=10
  • gte:大于等于参数值,例如gte=10
  • lt:小于参数值,例如lt=10
  • lte:小于等于参数值,例如lte=10
  • oneof:只能是列举出的值其中一个,这些值必须是数值或字符串,以空格分隔,如果字符串中有空格,将字符串用单引号包围,例如oneof=red green

大部分还是比较直观的,我们通过一个例子看看其中几个约束如何使用:

  1. type User struct {
  2. Name string `validate:"ne=admin"`
  3. Age int `validate:"gte=18"`
  4. Sex string `validate:"oneof=male female"`
  5. RegTime time.Time `validate:"lte"`
  6. }
  7. func main() {
  8. validate := validator.New()
  9. u1 := User{Name: "dj", Age: 18, Sex: "male", RegTime: time.Now().UTC()}
  10. err := validate.Struct(u1)
  11. if err != nil {
  12. fmt.Println(err)
  13. }
  14. u2 := User{Name: "admin", Age: 15, Sex: "none", RegTime: time.Now().UTC().Add(1 * time.Hour)}
  15. err = validate.Struct(u2)
  16. if err != nil {
  17. fmt.Println(err)
  18. }
  19. }

上面例子中,我们定义了User对象,为它的 4 个字段分别设置了约束:

  • Name:字符串不能是admin
  • Age:必须大于等于 18,未成年人禁止入内
  • Sex:性别必须是malefemale其中一个;
  • RegTime:注册时间必须小于当前的 UTC 时间,注意如果字段类型是time.Time,使用gt/gte/lt/lte等约束时不用指定参数值,默认与当前的 UTC 时间比较。

同样地,第一个对象的字段都是合法的,校验通过。第二个对象的 4 个字段都非法,通过输出信息很好定错误位置:

  1. Key: 'User.Name' Error:Field validation for 'Name' failed on the 'ne' tag
  2. Key: 'User.Age' Error:Field validation for 'Age' failed on the 'gte' tag
  3. Key: 'User.Sex' Error:Field validation for 'Sex' failed on the 'oneof' tag
  4. Key: 'User.RegTime' Error:Field validation for 'RegTime' failed on the 'lte' tag

跨字段约束

validator允许定义跨字段的约束,即该字段与其他字段之间的关系。这种约束实际上分为两种,一种是参数字段就是同一个结构中的平级字段,另一种是参数字段为结构中其他字段的字段。约束语法很简单,要想使用上面的约束语义,只需要稍微修改一下。例如相等约束eq),如果是约束同一个结构中的字段,则在后面添加一个field,使用eqfield定义字段间的相等约束。如果是更深层次的字段,在field之前还需要加上cs(可以理解为cross-struct),eq就变为eqcsfield。它们的参数值都是需要比较的字段名,内层的还需要加上字段的类型:

  1. eqfield=ConfirmPassword
  2. eqcsfield=InnerStructField.Field

看示例:

  1. type RegisterForm struct {
  2. Name string `validate:"min=2"`
  3. Age int `validate:"min=18"`
  4. Password string `validate:"min=10"`
  5. Password2 string `validate:"eqfield=Password"`
  6. }
  7. func main() {
  8. validate := validator.New()
  9. f1 := RegisterForm{
  10. Name: "dj",
  11. Age: 18,
  12. Password: "1234567890",
  13. Password2: "1234567890",
  14. }
  15. err := validate.Struct(f1)
  16. if err != nil {
  17. fmt.Println(err)
  18. }
  19. f2 := RegisterForm{
  20. Name: "dj",
  21. Age: 18,
  22. Password: "1234567890",
  23. Password2: "123",
  24. }
  25. err = validate.Struct(f2)
  26. if err != nil {
  27. fmt.Println(err)
  28. }
  29. }

我们定义了一个简单的注册表单结构,使用eqfield约束其两次输入的密码必须相等。第一个对象满足约束,第二个对象两次密码明显不等。程序输出:

  1. Key: 'RegisterForm.Password2' Error:Field validation for 'Password2' failed on the 'eqfield' tag

字符串

validator中关于字符串的约束有很多,这里介绍几个:

  • contains=:包含参数子串,例如contains=email
  • containsany:包含参数中任意的 UNICODE 字符,例如containsany=abcd
  • containsrune:包含参数表示的 rune 字符,例如containsrune=☻
  • excludes:不包含参数子串,例如excludes=email
  • excludesall:不包含参数中任意的 UNICODE 字符,例如excludesall=abcd
  • excludesrune:不包含参数表示的 rune 字符,excludesrune=☻
  • startswith:以参数子串为前缀,例如startswith=hello
  • endswith:以参数子串为后缀,例如endswith=bye

看示例:

  1. type User struct {
  2. Name string `validate:"containsrune=☻"`
  3. Age int `validate:"min=18"`
  4. }
  5. func main() {
  6. validate := validator.New()
  7. u1 := User{"d☻j", 18}
  8. err := validate.Struct(u1)
  9. if err != nil {
  10. fmt.Println(err)
  11. }
  12. u2 := User{"dj", 18}
  13. err = validate.Struct(u2)
  14. if err != nil {
  15. fmt.Println(err)
  16. }
  17. }

限制Name字段必须包含 UNICODE 字符

唯一性

使用unqiue来指定唯一性约束,对不同类型的处理如下:

  • 对于数组和切片,unique约束没有重复的元素;
  • 对于mapunique约束没有重复的
  • 对于元素类型为结构体的切片,unique约束结构体对象的某个字段不重复,通过unqiue=field指定这个字段名。

例如:

  1. type User struct {
  2. Name string `validate:"min=2"`
  3. Age int `validate:"min=18"`
  4. Hobbies []string `validate:"unique"`
  5. Friends []User `validate:"unique=Name"`
  6. }
  7. func main() {
  8. validate := validator.New()
  9. f1 := User{
  10. Name: "dj2",
  11. Age: 18,
  12. }
  13. f2 := User{
  14. Name: "dj3",
  15. Age: 18,
  16. }
  17. u1 := User{
  18. Name: "dj",
  19. Age: 18,
  20. Hobbies: []string{"pingpong", "chess", "programming"},
  21. Friends: []User{f1, f2},
  22. }
  23. err := validate.Struct(u1)
  24. if err != nil {
  25. fmt.Println(err)
  26. }
  27. u2 := User{
  28. Name: "dj",
  29. Age: 18,
  30. Hobbies: []string{"programming", "programming"},
  31. Friends: []User{f1, f1},
  32. }
  33. err = validate.Struct(u2)
  34. if err != nil {
  35. fmt.Println(err)
  36. }
  37. }

我们限制爱好Hobbies中不能有重复元素,好友Friends的各个元素不能有同样的名字Name。第一个对象满足约束,第二个对象的Hobbies字段包含了重复的"programming"Friends字段中两个元素的Name字段都是dj2。程序输出:

  1. Key: 'User.Hobbies' Error:Field validation for 'Hobbies' failed on the 'unique' tag
  2. Key: 'User.Friends' Error:Field validation for 'Friends' failed on the 'unique' tag

邮件

通过email限制字段必须是邮件格式:

  1. type User struct {
  2. Name string `validate:"min=2"`
  3. Age int `validate:"min=18"`
  4. Email string `validate:"email"`
  5. }
  6. func main() {
  7. validate := validator.New()
  8. u1 := User{
  9. Name: "dj",
  10. Age: 18,
  11. Email: "dj@example.com",
  12. }
  13. err := validate.Struct(u1)
  14. if err != nil {
  15. fmt.Println(err)
  16. }
  17. u2 := User{
  18. Name: "dj",
  19. Age: 18,
  20. Email: "djexample.com",
  21. }
  22. err = validate.Struct(u2)
  23. if err != nil {
  24. fmt.Println(err)
  25. }
  26. }

上面我们约束Email字段必须是邮件的格式,第一个对象满足约束,第二个对象不满足,程序输出:

  1. Key: 'User.Email' Error:Field validation for 'Email' failed on the 'email' tag

特殊

有一些比较特殊的约束:

  • -:跳过该字段,不检验;
  • |:使用多个约束,只需要满足其中一个,例如rgb|rgba
  • required:字段必须设置,不能为默认值;
  • omitempty:如果字段未设置,则忽略它。

其他

validator提供了大量的、各个方面的、丰富的约束,如ASCII/UNICODE字母、数字、十六进制、十六进制颜色值、大小写、RBG 颜色值,HSL 颜色值、HSLA 颜色值、JSON 格式、文件路径、URL、base64 编码串、ip 地址、ipv4、ipv6、UUID、经纬度等等等等等等等等等等等。限于篇幅这里就不一一介绍了。感兴趣自行去文档中挖掘。

VarWithValue方法

在一些很简单的情况下,我们仅仅想对两个变量进行比较,如果每次都要先定义结构和tag就太繁琐了。validator提供了VarWithValue()方法,我们只需要传入要验证的两个变量和约束即可

  1. func main() {
  2. name1 := "dj"
  3. name2 := "dj2"
  4. validate := validator.New()
  5. fmt.Println(validate.VarWithValue(name1, name2, "eqfield"))
  6. fmt.Println(validate.VarWithValue(name1, name2, "nefield"))
  7. }

自定义约束

除了使用validator提供的约束外,还可以定义自己的约束。例如现在有个奇葩的需求,产品同学要求用户必须使用回文串作为用户名,我们可以自定义这个约束:

  1. type RegisterForm struct {
  2. Name string `validate:"palindrome"`
  3. Age int `validate:"min=18"`
  4. }
  5. func reverseString(s string) string {
  6. runes := []rune(s)
  7. for from, to := 0, len(runes)-1; from < to; from, to = from+1, to-1 {
  8. runes[from], runes[to] = runes[to], runes[from]
  9. }
  10. return string(runes)
  11. }
  12. func CheckPalindrome(fl validator.FieldLevel) bool {
  13. value := fl.Field().String()
  14. return value == reverseString(value)
  15. }
  16. func main() {
  17. validate := validator.New()
  18. validate.RegisterValidation("palindrome", CheckPalindrome)
  19. f1 := RegisterForm{
  20. Name: "djd",
  21. Age: 18,
  22. }
  23. err := validate.Struct(f1)
  24. if err != nil {
  25. fmt.Println(err)
  26. }
  27. f2 := RegisterForm{
  28. Name: "dj",
  29. Age: 18,
  30. }
  31. err = validate.Struct(f2)
  32. if err != nil {
  33. fmt.Println(err)
  34. }
  35. }

首先定义一个类型为func (validator.FieldLevel) bool的函数检查约束是否满足,可以通过FieldLevel取出要检查的字段的信息。然后,调用验证器的RegisterValidation()方法将该约束注册到指定的名字上。最后我们就可以在结构体中使用该约束。上面程序中,第二个对象不满足约束palindrome,输出:

  1. Key: 'RegisterForm.Name' Error:Field validation for 'Name' failed on the 'palindrome' tag

错误处理

在上面的例子中,校验失败时我们仅仅只是输出返回的错误。其实,我们可以进行更精准的处理。validator返回的错误实际上只有两种,一种是参数错误,一种是校验错误。参数错误时,返回InvalidValidationError类型;校验错误时返回ValidationErrors,它们都实现了error接口。而且ValidationErrors是一个错误切片,它保存了每个字段违反的每个约束信息:

  1. // src/gopkg.in/validator.v10/errors.go
  2. type InvalidValidationError struct {
  3. Type reflect.Type
  4. }
  5. // Error returns InvalidValidationError message
  6. func (e *InvalidValidationError) Error() string {
  7. if e.Type == nil {
  8. return "validator: (nil)"
  9. }
  10. return "validator: (nil " + e.Type.String() + ")"
  11. }
  12. type ValidationErrors []FieldError
  13. func (ve ValidationErrors) Error() string {
  14. buff := bytes.NewBufferString("")
  15. var fe *fieldError
  16. for i := 0; i < len(ve); i++ {
  17. fe = ve[i].(*fieldError)
  18. buff.WriteString(fe.Error())
  19. buff.WriteString("\n")
  20. }
  21. return strings.TrimSpace(buff.String())
  22. }

所以validator校验返回的结果只有 3 种情况:

  • nil:没有错误;
  • InvalidValidationError:输入参数错误;
  • ValidationErrors:字段违反约束。

我们可以在程序中判断err != nil时,依次将err转换为InvalidValidationErrorValidationErrors以获取更详细的信息:

  1. func processErr(err error) {
  2. if err == nil {
  3. return
  4. }
  5. invalid, ok := err.(*validator.InvalidValidationError)
  6. if ok {
  7. fmt.Println("param error:", invalid)
  8. return
  9. }
  10. validationErrs := err.(validator.ValidationErrors)
  11. for _, validationErr := range validationErrs {
  12. fmt.Println(validationErr)
  13. }
  14. }
  15. func main() {
  16. validate := validator.New()
  17. err := validate.Struct(1)
  18. processErr(err)
  19. err = validate.VarWithValue(1, 2, "eqfield")
  20. processErr(err)
  21. }

总结

validator功能非常丰富,使用较为简单方便。本文介绍的约束只是其中的冰山一角。它的应用非常广泛,建议了解一下。

大家如果发现好玩、好用的 Go 语言库,欢迎到 Go 每日一库 GitHub 上提交 issue😄

参考

  1. validator GitHub:https://github.com/go-playground/validator
  2. Go 每日一库 GitHub:https://github.com/go-quiz/go-daily-lib