Go 每日一庫之 validator

簡介

今天我們來介紹一個非常實用的庫——validator。validator用於對資料進行校驗。在 Web 開發中，對使用者傳過來的資料我們都需要進行嚴格校驗，防止使用者的惡意請求。例如日期格式，使用者年齡，性別等必須是正常的值，不能隨意設定。

快速使用

先安裝：

$ go get gopkg.in/go-playground/validator.v10
複製程式碼

後使用：

package main

import (
  "fmt"

  "gopkg.in/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，故返回錯誤：

<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。

大部分還是比較直觀的，我們通過一個例子看看其中幾個約束如何使用：

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 個欄位都非法，通過輸出資訊很好定錯誤位置：

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=ConfirmPassword
eqcsfield=InnerStructField.Field
複製程式碼

看示例：

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約束其兩次輸入的密碼必須相等。第一個物件滿足約束，第二個物件兩次密碼明顯不等。程式輸出：

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。

看示例：

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指定這個欄位名。

例如：

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。程式輸出：

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限制欄位必須是郵件格式：

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欄位必須是郵件的格式，第一個物件滿足約束，第二個物件不滿足，程式輸出：

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()方法，我們只需要傳入要驗證的兩個變數和約束即可

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

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

  fmt.Println(validate.VarWithValue(name1, name2, "nefield"))
}
複製程式碼

自定義約束

除了使用validator提供的約束外，還可以定義自己的約束。例如現在有個奇葩的需求，產品同學要求使用者必須使用迴文串作為使用者名稱，我們可以自定義這個約束：

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，輸出：

Key: 'RegisterForm.Name' Error:Field validation for 'Name' failed on the 'palindrome' tag
複製程式碼

錯誤處理

在上面的例子中，校驗失敗時我們僅僅只是輸出返回的錯誤。其實，我們可以進行更精準的處理。validator返回的錯誤實際上只有兩種，一種是引數錯誤，一種是校驗錯誤。引數錯誤時，返回InvalidValidationError型別；校驗錯誤時返回ValidationErrors，它們都實現了error介面。而且ValidationErrors是一個錯誤切片，它儲存了每個欄位違反的每個約束資訊：

// 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以獲取更詳細的資訊：

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功能非常豐富，使用較為簡單方便。本文介紹的約束只是其中的冰山一角。它的應用非常廣泛，建議瞭解一下。

大家如果發現好玩、好用的 Go 語言庫，歡迎到 Go 每日一庫 GitHub 上提交 issue?

參考

1. validator GitHub：github.com/go-playgrou…
2. Go 每日一庫 GitHub：github.com/darjun/go-d…

我

我的部落格：darjun.github.io

歡迎關注我的微信公眾號【GoUpUp】，共同學習，一起進步~