快速使用

先安装：

1

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

package main

import (
  "fmt"

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

type User struct {
  Name string `validate:"min=6,max=10"`
  Age  int    `validate:"min=1,max=100"`
}

func main() {
  validate := validator.New()

  u1 := User{Name: "lidajun", Age: 18}
  err := validate.Struct(u1)
  fmt.Println(err)

  u2 := User{Name: "dj", Age: 101}
  err = validate.Struct(u2)
  fmt.Println(err)
}

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

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

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

1
2
3

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

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

注意：

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

约束

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

范围约束

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

  • 对于数值，则约束其值；
  • 对于字符串，则约束其长度；
  • 对于切片、数组和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
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

type User struct {
  Name    string    `validate:"ne=admin"`
  Age     int       `validate:"gte=18"`
  Sex     string    `validate:"oneof=male female"`
  RegTime time.Time `validate:"lte"`
}

func main() {
  validate := validator.New()

  u1 := User{Name: "dj", Age: 18, Sex: "male", RegTime: time.Now().UTC()}
  err := validate.Struct(u1)
  if err != nil {
    fmt.Println(err)
  }

  u2 := User{Name: "admin", Age: 15, Sex: "none", RegTime: time.Now().UTC().Add(1 * time.Hour)}
  err = validate.Struct(u2)
  if err != nil {
    fmt.Println(err)
  }
}

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

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

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

1
2
3
4

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

跨字段约束

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

主要有：

  • eqfield=Field: 必须等于 Field 的值；
  • nefield=Field: 必须不等于 Field 的值；
  • gtfield=Field: 必须大于 Field 的值；
  • gtefield=Field: 必须大于等于 Field 的值；
  • ltfield=Field: 必须小于 Field 的值；
  • ltefield=Field: 必须小于等于 Field 的值；
  • eqcsfield=Other.Field: 必须等于 struct Other 中 Field 的值；
  • necsfield=Other.Field: 必须不等于 struct Other 中 Field 的值；
  • gtcsfield=Other.Field: 必须大于 struct Other 中 Field 的值；
  • gtecsfield=Other.Field: 必须大于等于 struct Other 中 Field 的值；
  • ltcsfield=Other.Field: 必须小于 struct Other 中 Field 的值；
  • ltecsfield=Other.Field: 必须小于等于 struct Other 中 Field 的值；

比较符号就只有 6 种：

  • eq: Equal，等于；
  • ne: Non Equal，不等于；
  • gt: Great than，大于；
  • gte: Great than equal，大于等于；
  • lt: Less than，小于；
  • lte: Less than equal，小于等于；

它的用法也是简单明了，直接在后面加上要比较的字段即可：

1
2
3
4

type Test struct {
	StartAt time.Time `validate:"required"`
	EndAt   time.Time `validate:"required,gtfield=StartAt"`
}

另外还有几个挺有用的 Tag：

  • required_with=Field1 Field2: 在 Field1 或者 Field2 存在时，必须；
  • required_with_all=Field1 Field2: 在 Field1 与 Field2 都存在时，必须；
  • required_without=Field1 Field2: 在 Field1 或者 Field2 不存在时，必须；
  • required_without_all=Field1 Field2: 在 Field1 与 Field2 都存在时，必须；

看示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

type RegisterForm struct {
  Name      string `validate:"min=2"`
  Age       int    `validate:"min=18"`
  Password  string `validate:"min=10"`
  Password2 string `validate:"eqfield=Password"`
}

func main() {
  validate := validator.New()

  f1 := RegisterForm{
    Name:      "dj",
    Age:       18,
    Password:  "1234567890",
    Password2: "1234567890",
  }
  err := validate.Struct(f1)
  if err != nil {
    fmt.Println(err)
  }

  f2 := RegisterForm{
    Name:      "dj",
    Age:       18,
    Password:  "1234567890",
    Password2: "123",
  }
  err = validate.Struct(f2)
  if err != nil {
    fmt.Println(err)
  }
}

我们定义了一个简单的注册表单结构，使用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
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

type User struct {
  Name string `validate:"containsrune=☻"`
  Age  int    `validate:"min=18"`
}

func main() {
  validate := validator.New()

  u1 := User{"d☻j", 18}
  err := validate.Struct(u1)
  if err != nil {
    fmt.Println(err)
  }

  u2 := User{"dj", 18}
  err = validate.Struct(u2)
  if err != nil {
    fmt.Println(err)
  }
}

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

唯一性

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

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

例如：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

type User struct {
  Name    string   `validate:"min=2"`
  Age     int      `validate:"min=18"`
  Hobbies []string `validate:"unique"`
  Friends []User   `validate:"unique=Name"`
}

func main() {
  validate := validator.New()

  f1 := User{
    Name: "dj2",
    Age:  18,
  }
  f2 := User{
    Name: "dj3",
    Age:  18,
  }

  u1 := User{
    Name:    "dj",
    Age:     18,
    Hobbies: []string{"pingpong", "chess", "programming"},
    Friends: []User{f1, f2},
  }
  err := validate.Struct(u1)
  if err != nil {
    fmt.Println(err)
  }

  u2 := User{
    Name:    "dj",
    Age:     18,
    Hobbies: []string{"programming", "programming"},
    Friends: []User{f1, f1},
  }
  err = validate.Struct(u2)
  if err != nil {
    fmt.Println(err)
  }
}

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

1
2

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

邮件

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

type User struct {
  Name  string `validate:"min=2"`
  Age   int    `validate:"min=18"`
  Email string `validate:"email"`
}

func main() {
  validate := validator.New()

  u1 := User{
    Name:  "dj",
    Age:   18,
    Email: "dj@example.com",
  }
  err := validate.Struct(u1)
  if err != nil {
    fmt.Println(err)
  }

  u2 := User{
    Name:  "dj",
    Age:   18,
    Email: "djexample.com",
  }
  err = validate.Struct(u2)
  if err != nil {
    fmt.Println(err)
  }
}

上面我们约束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
2
3
4
5
6
7
8
9

func main() {
  name1 := "dj"
  name2 := "dj2"

  validate := validator.New()
  fmt.Println(validate.VarWithValue(name1, name2, "eqfield"))

  fmt.Println(validate.VarWithValue(name1, name2, "nefield"))
}

自定义约束

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

type RegisterForm struct {
  Name string `validate:"palindrome"`
  Age  int    `validate:"min=18"`
}

func reverseString(s string) string {
  runes := []rune(s)
  for from, to := 0, len(runes)-1; from < to; from, to = from+1, to-1 {
    runes[from], runes[to] = runes[to], runes[from]
  }

  return string(runes)
}

func CheckPalindrome(fl validator.FieldLevel) bool {
  value := fl.Field().String()
  return value == reverseString(value)
}

func main() {
  validate := validator.New()
  validate.RegisterValidation("palindrome", CheckPalindrome)

  f1 := RegisterForm{
    Name: "djd",
    Age:  18,
  }
  err := validate.Struct(f1)
  if err != nil {
    fmt.Println(err)
  }

  f2 := RegisterForm{
    Name: "dj",
    Age:  18,
  }
  err = validate.Struct(f2)
  if err != nil {
    fmt.Println(err)
  }
}

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

1

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

自定义类型验证

除了validator支持的基础类型外,我们也可以自定义类型,并注册相应的验证函数

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

package main

import (
	"database/sql"
	"database/sql/driver"
	"fmt"
	"reflect"

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

// DbBackedUser User struct
type DbBackedUser struct {
	Name sql.NullString `validate:"required"`
	Age  sql.NullInt64  `validate:"required"`
}

// use a single instance of Validate, it caches struct info
var validate *validator.Validate

func main() {

	validate = validator.New()

	// register all sql.Null* types to use the ValidateValuer CustomTypeFunc
	validate.RegisterCustomTypeFunc(ValidateValuer, sql.NullString{}, sql.NullInt64{}, sql.NullBool{}, sql.NullFloat64{})

	// build object for validation
	x := DbBackedUser{Name: sql.NullString{String: "", Valid: true}, Age: sql.NullInt64{Int64: 0, Valid: false}}

	err := validate.Struct(x)

	if err != nil {
		fmt.Printf("Err(s):\n%+v\n", err)
	}
}

// ValidateValuer implements validator.CustomTypeFunc
func ValidateValuer(field reflect.Value) interface{} {

	if valuer, ok := field.Interface().(driver.Valuer); ok {

		val, err := valuer.Value()
		if err == nil {
			return val
		}
		// handle the error how you want
	}

	return nil
}

嵌套验证

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

package main

import (
	"fmt"

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

// Test ...
type Test struct {
	Array []string          `validate:"required,gt=0,dive,required"`
	Map   map[string]string `validate:"required,gt=0,dive,keys,keymax,endkeys,required,max=1000"`
}

// use a single instance of Validate, it caches struct info
var validate *validator.Validate

func main() {

	validate = validator.New()

	// registering alias so we can see the differences between
	// map key, value validation errors
	validate.RegisterAlias("keymax", "max=10")

	var test Test

	val(test)

	test.Array = []string{""}
	test.Map = map[string]string{"test > than 10": ""}
	val(test)
}

func val(test Test) {
	fmt.Println("testing")
	err := validate.Struct(test)
	fmt.Println(err)
}

整体演示

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109

package main

import (
	"fmt"

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

// User contains user information
type User struct {
	FirstName      string     `json:"fname"`
	LastName       string     `json:"lname"`
	Age            uint8      `validate:"gte=0,lte=130"`
	Email          string     `validate:"required,email"`
	FavouriteColor string     `validate:"hexcolor|rgb|rgba"`
	Addresses      []*Address `validate:"required,dive,required"` // a person can have a home and cottage...
}

// Address houses a users address information
type Address struct {
	Street string `validate:"required"`
	City   string `validate:"required"`
	Planet string `validate:"required"`
	Phone  string `validate:"required"`
}

// use a single instance of Validate, it caches struct info
var validate *validator.Validate

func main() {

	validate = validator.New()

	// register validation for 'User'
	// NOTE: only have to register a non-pointer type for 'User', validator
	// interanlly dereferences during it's type checks.
	validate.RegisterStructValidation(UserStructLevelValidation, User{})

	// build 'User' info, normally posted data etc...
	address := &Address{
		Street: "Eavesdown Docks",
		Planet: "Persphone",
		Phone:  "none",
		City:   "Unknown",
	}

	user := &User{
		FirstName:      "",
		LastName:       "",
		Age:            45,
		Email:          "Badger.Smith@gmail.com",
		FavouriteColor: "#000",
		Addresses:      []*Address{address},
	}

	// returns InvalidValidationError for bad validation input, nil or ValidationErrors ( []FieldError )
	err := validate.Struct(user)
	if err != nil {

		// this check is only needed when your code could produce
		// an invalid value for validation such as interface with nil
		// value most including myself do not usually have code like this.
		if _, ok := err.(*validator.InvalidValidationError); ok {
			fmt.Println(err)
			return
		}

		for _, err := range err.(validator.ValidationErrors) {

			fmt.Println(err.Namespace())
			fmt.Println(err.Field())
			fmt.Println(err.StructNamespace()) // can differ when a custom TagNameFunc is registered or
			fmt.Println(err.StructField())     // by passing alt name to ReportError like below
			fmt.Println(err.Tag())
			fmt.Println(err.ActualTag())
			fmt.Println(err.Kind())
			fmt.Println(err.Type())
			fmt.Println(err.Value())
			fmt.Println(err.Param())
			fmt.Println()
		}

		// from here you can create your own error messages in whatever language you wish
		return
	}

	// save user to database
}

// UserStructLevelValidation contains custom struct level validations that don't always
// make sense at the field validation level. For Example this function validates that either
// FirstName or LastName exist; could have done that with a custom field validation but then
// would have had to add it to both fields duplicating the logic + overhead, this way it's
// only validated once.
//
// NOTE: you may ask why wouldn't I just do this outside of validator, because doing this way
// hooks right into validator and you can combine with validation tags and still have a
// common error output format.
func UserStructLevelValidation(sl validator.StructLevel) {

	user := sl.Current().Interface().(User)

	if len(user.FirstName) == 0 && len(user.LastName) == 0 {
		sl.ReportError(user.FirstName, "FirstName", "fname", "fnameorlname", "")
		sl.ReportError(user.LastName, "LastName", "lname", "fnameorlname", "")
	}

	// plus can do more, even with different tag than "fnameorlname"
}

错误处理

validator返回的错误实际上只有两种，一种是参数错误，一种是校验错误。参数错误时，返回InvalidValidationError类型；校验错误时返回ValidationErrors，它们都实现了error接口。而且ValidationErrors是一个错误切片，它保存了每个字段违反的每个约束信息：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// src/gopkg.in/validator.v10/errors.go
type InvalidValidationError struct {
  Type reflect.Type
}

// Error returns InvalidValidationError message
func (e *InvalidValidationError) Error() string {
  if e.Type == nil {
    return "validator: (nil)"
  }

  return "validator: (nil " + e.Type.String() + ")"
}

type ValidationErrors []FieldError

func (ve ValidationErrors) Error() string {
  buff := bytes.NewBufferString("")
  var fe *fieldError

  for i := 0; i < len(ve); i++ {
    fe = ve[i].(*fieldError)
    buff.WriteString(fe.Error())
    buff.WriteString("\n")
  }
  return strings.TrimSpace(buff.String())
}

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

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

我们可以在程序中判断err != nil时，依次将err转换为InvalidValidationError和ValidationErrors以获取更详细的信息：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

func processErr(err error) {
  if err == nil {
    return
  }

  invalid, ok := err.(*validator.InvalidValidationError)
  if ok {
    fmt.Println("param error:", invalid)
    return
  }

  validationErrs := err.(validator.ValidationErrors)
  for _, validationErr := range validationErrs {
    fmt.Println(validationErr)
  }
}

func main() {
  validate := validator.New()

  err := validate.Struct(1)
  processErr(err)

  err = validate.VarWithValue(1, 2, "eqfield")
  processErr(err)
}

validator与gin结合

翻译校验错误提示信息

validator库本身是支持国际化的，借助相应的语言包可以实现校验错误提示信息的自动翻译。下面的示例代码演示了如何将错误提示信息翻译成中文，翻译成其他语言的方法类似。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

package main

import (
	"fmt"
	"net/http"

	"github.com/gin-gonic/gin"
	"github.com/gin-gonic/gin/binding"
	"github.com/go-playground/locales/en"
	"github.com/go-playground/locales/zh"
	ut "github.com/go-playground/universal-translator"
	"github.com/go-playground/validator/v10"
	enTranslations "github.com/go-playground/validator/v10/translations/en"
	zhTranslations "github.com/go-playground/validator/v10/translations/zh"
)

// 定义一个全局翻译器T
var trans ut.Translator

// InitTrans 初始化翻译器
func InitTrans(locale string) (err error) {
	// 修改gin框架中的Validator引擎属性，实现自定制
	if v, ok := binding.Validator.Engine().(*validator.Validate); ok {

		zhT := zh.New() // 中文翻译器
		enT := en.New() // 英文翻译器

		// 第一个参数是备用（fallback）的语言环境
		// 后面的参数是应该支持的语言环境（支持多个）
		// uni := ut.New(zhT, zhT) 也是可以的
		uni := ut.New(enT, zhT, enT)

		// locale 通常取决于 http 请求头的 'Accept-Language'
		var ok bool
		// 也可以使用 uni.FindTranslator(...) 传入多个locale进行查找
		trans, ok = uni.GetTranslator(locale)
		if !ok {
			return fmt.Errorf("uni.GetTranslator(%s) failed", locale)
		}

		// 注册翻译器
		switch locale {
		case "en":
			err = enTranslations.RegisterDefaultTranslations(v, trans)
		case "zh":
			err = zhTranslations.RegisterDefaultTranslations(v, trans)
		default:
			err = enTranslations.RegisterDefaultTranslations(v, trans)
		}
		return
	}
	return
}

type SignUpParam struct {
	Age        uint8  `json:"age" binding:"gte=1,lte=130"`
	Name       string `json:"name" binding:"required"`
	Email      string `json:"email" binding:"required,email"`
	Password   string `json:"password" binding:"required"`
	RePassword string `json:"re_password" binding:"required,eqfield=Password"`
}

func main() {
	if err := InitTrans("zh"); err != nil {
		fmt.Printf("init trans failed, err:%v\n", err)
		return
	}

	r := gin.Default()

	r.POST("/signup", func(c *gin.Context) {
		var u SignUpParam
		if err := c.ShouldBind(&u); err != nil {
			// 获取validator.ValidationErrors类型的errors
			errs, ok := err.(validator.ValidationErrors)
			if !ok {
				// 非validator.ValidationErrors类型错误直接返回
				c.JSON(http.StatusOK, gin.H{
					"msg": err.Error(),
				})
				return
			}
			// validator.ValidationErrors类型错误则进行翻译
			c.JSON(http.StatusOK, gin.H{
				"msg":errs.Translate(trans),
			})
			return
		}
		// 保存入库等具体业务逻辑代码...

		c.JSON(http.StatusOK, "success")
	})

	_ = r.Run(":8999")
}

发出请求：

1
2


curl -H "Content-type: application/json" -X POST -d '{"name":"q1mi","age":18,"email":"123.com"}' <http://127.0.0.1:8999/signup>

输出结果如下：

1

{"msg":{"SignUpParam.Email":"Email必须是一个有效的邮箱","SignUpParam.Password":"Password为必填字段","SignUpParam.RePassword":"RePassword为必填字段"}}

自定义错误提示信息的字段名

上面的错误提示看起来是可以了，但是还是差点意思，首先是错误提示中的字段并不是请求中使用的字段，例如：RePassword是我们后端定义的结构体中的字段名，而请求中使用的是re_password字段。如何是错误提示中的字段使用自定义的名称，例如jsontag指定的值呢？

只需要在初始化翻译器的时候像下面一样添加一个获取json tag的自定义方法即可。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// InitTrans 初始化翻译器
func InitTrans(locale string) (err error) {
	// 修改gin框架中的Validator引擎属性，实现自定制
	if v, ok := binding.Validator.Engine().(*validator.Validate); ok {

		// 注册一个获取json tag的自定义方法
		v.RegisterTagNameFunc(func(fld reflect.StructField) string {
			name := strings.SplitN(fld.Tag.Get("json"), ",", 2)[0]
			if name == "-" {
				return ""
			}
			return name
		})

		zhT := zh.New() // 中文翻译器
		enT := en.New() // 英文翻译器

		// 第一个参数是备用（fallback）的语言环境
		// 后面的参数是应该支持的语言环境（支持多个）
		// uni := ut.New(zhT, zhT) 也是可以的
		uni := ut.New(enT, zhT, enT)

		// ... liwenzhou.com ...
}

再尝试发请求，看一下效果：

1

{"msg":{"SignUpParam.email":"email必须是一个有效的邮箱","SignUpParam.password":"password为必填字段","SignUpParam.re_password":"re_password为必填字段"}}

可以看到现在错误提示信息中使用的就是我们结构体中jsontag设置的名称了。

但是还是有点瑕疵，那就是最终的错误提示信息中心还是有我们后端定义的结构体名称——SignUpParam，这个名称其实是不需要随错误提示返回给前端的，前端并不需要这个值。我们需要想办法把它去掉。

这里参考https://github.com/go-playground/validator/issues/633#issuecomment-654382345提供的方法，定义一个去掉结构体名称前缀的自定义方法：

1
2
3
4
5
6
7

func removeTopStruct(fields map[string]string) map[string]string {
	res := map[string]string{}
	for field, err := range fields {
		res[field[strings.Index(field, ".")+1:]] = err
	}
	return res
}

我们在代码中使用上述函数将翻译后的errors做一下处理即可：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

if err := c.ShouldBind(&u); err != nil {
	// 获取validator.ValidationErrors类型的errors
	errs, ok := err.(validator.ValidationErrors)
	if !ok {
		// 非validator.ValidationErrors类型错误直接返回
		c.JSON(http.StatusOK, gin.H{
			"msg": err.Error(),
		})
		return
	}
	// validator.ValidationErrors类型错误则进行翻译
	// 并使用removeTopStruct函数去除字段名中的结构体名称标识
	c.JSON(http.StatusOK, gin.H{
		"msg": removeTopStruct(errs.Translate(trans)),
	})
	return
}

看一下最终的效果：

1

{"msg":{"email":"email必须是一个有效的邮箱","password":"password为必填字段","re_password":"re_password为必填字段"}}

这一次看起来就比较符合我们预期的标准了。

自定义结构体校验方法

上面的校验还是有点小问题，就是当涉及到一些复杂的校验规则，比如re_password字段需要与password字段的值相等这样的校验规则，我们的自定义错误提示字段名称方法就不能很好解决错误提示信息中的其他字段名称了。

1

curl -H "Content-type: application/json" -X POST -d '{"name":"q1mi","age":18,"email":"123.com","password":"123","re_password":"321"}' <http://127.0.0.1:8999/signup>

最后输出的错误提示信息如下：

1

{"msg":{"email":"email必须是一个有效的邮箱","re_password":"re_password必须等于Password"}}

可以看到re_password字段的提示信息中还是出现了Password这个结构体字段名称。这有点小小的遗憾，毕竟自定义字段名称的方法不能影响被当成param传入的值。

此时如果想要追求更好的提示效果，将上面的Password字段也改为和json tag一致的名称，就需要我们自定义结构体校验的方法。

例如，我们为SignUpParam自定义一个校验方法如下：

1
2
3
4
5
6
7
8
9

// SignUpParamStructLevelValidation 自定义SignUpParam结构体校验函数
func SignUpParamStructLevelValidation(sl validator.StructLevel) {
	su := sl.Current().Interface().(SignUpParam)

	if su.Password != su.RePassword {
		// 输出错误提示信息，最后一个参数就是传递的param
		sl.ReportError(su.RePassword, "re_password", "RePassword", "eqfield", "password")
	}
}

然后在初始化校验器的函数中注册该自定义校验方法即可：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

func InitTrans(locale string) (err error) {
	// 修改gin框架中的Validator引擎属性，实现自定制
	if v, ok := binding.Validator.Engine().(*validator.Validate); ok {

		// ... liwenzhou.com ...

		// 为SignUpParam注册自定义校验方法
		v.RegisterStructValidation(SignUpParamStructLevelValidation, SignUpParam{})

		zhT := zh.New() // 中文翻译器
		enT := en.New() // 英文翻译器

		// ... liwenzhou.com ...
}

最终再请求一次，看一下效果：

1

{"msg":{"email":"email必须是一个有效的邮箱","re_password":"re_password必须等于password"}}

这一次re_password字段的错误提示信息就符合我们预期了。

自定义字段校验方法

除了上面介绍到的自定义结构体校验方法，validator还支持为某个字段自定义校验方法，并使用RegisterValidation()注册到校验器实例中。

接下来我们来为SignUpParam添加一个需要使用自定义校验方法checkDate做参数校验的字段Date。

1
2
3
4
5
6
7
8
9

type SignUpParam struct {
	Age        uint8  `json:"age" binding:"gte=1,lte=130"`
	Name       string `json:"name" binding:"required"`
	Email      string `json:"email" binding:"required,email"`
	Password   string `json:"password" binding:"required"`
	RePassword string `json:"re_password" binding:"required,eqfield=Password"`
	// 需要使用自定义校验方法checkDate做参数校验的字段Date
	Date       string `json:"date" binding:"required,datetime=2006-01-02,checkDate"`
}

其中datetime=2006-01-02是内置的用于校验日期类参数是否满足指定格式要求的tag。 如果传入的date参数不满足2006-01-02这种格式就会提示如下错误：

1

{"msg":{"date":"date的格式必须是2006-01-02"}}

针对date字段除了内置的datetime=2006-01-02提供的格式要求外，假设我们还要求该字段的时间必须是一个未来的时间（晚于当前时间），像这样针对某个字段的特殊校验需求就需要我们使用自定义字段校验方法了。

首先我们要在需要执行自定义校验的字段后面添加自定义tag，这里使用的是checkDate，注意使用英文分号分隔开。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// customFunc 自定义字段级别校验方法
func customFunc(fl validator.FieldLevel) bool {
	date, err := time.Parse("2006-01-02", fl.Field().String())
	if err != nil {
		return false
	}
	if date.Before(time.Now()) {
		return false
	}
	return true
}

定义好了字段及其自定义校验方法后，就需要将它们联系起来并注册到我们的校验器实例中。

1
2
3
4

// 在校验器注册自定义的校验方法
if err := v.RegisterValidation("checkDate", customFunc); err != nil {
	return err
}

这样，我们就可以对请求参数中date字段执行自定义的checkDate进行校验了。 我们发送如下请求测试一下：

1

curl -H "Content-type: application/json" -X POST -d '{"name":"q1mi","age":18,"email":"123@qq.com","password":"123", "re_password": "123", "date":"2020-01-02"}' <http://127.0.0.1:8999/signup>

此时得到的响应结果是：

1

{"msg":{"date":"Key: 'SignUpParam.date' Error:Field validation for 'date' failed on the 'checkDate' tag"}}

这…自定义字段级别的校验方法的错误提示信息很“简单粗暴”，和我们上面的中文提示风格有出入，必须想办法搞定它呀！

自定义翻译方法

我们现在需要为自定义字段校验方法提供一个自定义的翻译方法，从而实现该字段错误提示信息的自定义显示。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

// registerTranslator 为自定义字段添加翻译功能
func registerTranslator(tag string, msg string) validator.RegisterTranslationsFunc {
	return func(trans ut.Translator) error {
		if err := trans.Add(tag, msg, false); err != nil {
			return err
		}
		return nil
	}
}

// translate 自定义字段的翻译方法
func translate(trans ut.Translator, fe validator.FieldError) string {
	msg, err := trans.T(fe.Tag(), fe.Field())
	if err != nil {
		panic(fe.(error).Error())
	}
	return msg
}

定义好了相关翻译方法之后，我们在InitTrans函数中通过调用RegisterTranslation()方法来注册我们自定义的翻译方法。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// InitTrans 初始化翻译器
func InitTrans(locale string) (err error) {
	// ...liwenzhou.com...

		// 注册翻译器
		switch locale {
		case "en":
			err = enTranslations.RegisterDefaultTranslations(v, trans)
		case "zh":
			err = zhTranslations.RegisterDefaultTranslations(v, trans)
		default:
			err = enTranslations.RegisterDefaultTranslations(v, trans)
		}
		if err != nil {
			return err
		}
		// 注意！因为这里会使用到trans实例
		// 所以这一步注册要放到trans初始化的后面
		if err := v.RegisterTranslation(
			"checkDate",
			trans,
			registerTranslator("checkDate", "{0}必须要晚于当前日期"),
			translate,
		); err != nil {
			return err
		}
		return
	}
	return
}

这样再次尝试发送请求，就能得到想要的错误提示信息了。

1

{"msg":{"date":"date必须要晚于当前日期"}}

参考: https://blog.xizhibei.me/2019/06/16/an-introduction-to-golang-validator/ https://www.yuque.com/mingzibaliao/golang/eawcpc Go 每日一库之 validator validator库参数校验若干实用技巧