跳到主要内容
版本：2.3.x

以下常用方法列表，文档更新可能滞后于代码新特性，更多的方法及示例请参考代码文档： https://pkg.go.dev/github.com/gogf/gf/v2/util/gvalid

New​

  • 说明： New 创建并返回一个 Validator 的新对象。

  • 格式：

New() *Validator
  • 示例：
func ExampleNew() {
      validator := gvalid.New()

      if err := validator.Data(16).Rules("min:18").Run(context.Background()); err != nil {
          fmt.Print(err)
      }

      // Output:
      // The value `16` must be equal or greater than 18
}

Run​

  • 说明： Run 对给定规则和信息的数据进行校验操作。

  • 格式：

Run(ctx context.Context) Error
  • 示例：
func ExampleValidator_Run() {
      // check value mode
      if err := g.Validator().Data(16).Rules("min:18").Run(context.Background()); err != nil {
          fmt.Println("check value err:", err)
      }
      // check map mode
      data := map[string]interface{}{
          "passport":  "",
          "password":  "123456",
          "password2": "1234567",
      }
      rules := map[string]string{
          "passport":  "required|length:6,16",
          "password":  "required|length:6,16|same:password2",
          "password2": "required|length:6,16",
      }
      if err := g.Validator().Data(data).Rules(rules).Run(context.Background()); err != nil {
          fmt.Println("check map err:", err)
      }
      // check struct mode
      type Params struct {
          Page      int    `v:"required|min:1"`
          Size      int    `v:"required|between:1,100"`
          ProjectId string `v:"between:1,10000"`
      }
      rules = map[string]string{
          "Page":      "required|min:1",
          "Size":      "required|between:1,100",
          "ProjectId": "between:1,10000",
      }
      obj := &Params{
          Page: 0,
          Size: 101,
      }
      if err := g.Validator().Data(obj).Run(context.Background()); err != nil {
          fmt.Println("check struct err:", err)
      }

      // May Output:
      // check value err: The value `16` must be equal or greater than 18
      // check map err: The passport field is required; The passport value `` length must be between 6 and 16; The password value `123456` must be the same as field password2
      // check struct err: The Page value `0` must be equal or greater than 1; The Size value `101` must be between 1 and 100
}

Clone​

  • 说明：Clone创建并返回一个当前Validator的值拷贝对象。

  • 格式：

(v *Validator) Clone() *Validator
  • 示例：
func ExampleValidator_Clone() {
      if err := g.Validator().Data(16).Rules("min:18").Run(context.Background()); err != nil {
          fmt.Println(err)
      }

      if err := g.Validator().Clone().Data(20).Run(context.Background()); err != nil {
          fmt.Println(err)
      } else {
          fmt.Println("Check Success!")
      }

      // Output:
      // The value `16` must be equal or greater than 18
      // Check Success!
}

I18n​

  • 说明： I18n 方法用于设置当前校验对象的 I18N 国际化组件。默认情况下，校验组件使用的是框架全局默认的 i18n 组件对象。

  • 格式：

I18n(i18nManager *gi18n.Manager) *Validator
  • 示例：
func ExampleValidator_I18n() {
      var (
          i18nManager = gi18n.New()
          ctxCn       = gi18n.WithLanguage(context.Background(), "cn")
          validator   = gvalid.New()
      )

      validator = validator.Data(16).Rules("min:18")

      if err := validator.Run(context.Background()); err != nil {
          fmt.Println(err)
      }

      if err := validator.I18n(i18nManager).Run(ctxCn); err != nil {
          fmt.Println(err)
      }

      // Output:
      // The value `16` must be equal or greater than 18
      // 字段值`16`字段最小值应当为18
}

Bail​

  • 说明： Bail 方法用于设定只要后续的多个校验中有一个规则校验失败则停止校验立即返回错误结果。

  • 格式：

Bail() *Validator
  • 示例：
func ExampleValidator_Bail() {
      type BizReq struct {
          Account   string `v:"required|length:6,16|same:QQ"`
          QQ        string
          Password  string `v:"required|same:Password2"`
          Password2 string `v:"required"`
      }
      var (
          ctx = context.Background()
          req = BizReq{
              Account:   "gf",
              QQ:        "123456",
              Password:  "goframe.org",
              Password2: "goframe.org",
          }
      )

      if err := g.Validator().Bail().Data(req).Run(ctx); err != nil {
          fmt.Println("Use Bail Error:", err)
      }

      if err := g.Validator().Data(req).Run(ctx); err != nil {
          fmt.Println("Not Use Bail Error:", err)
      }

      // output:
      // Use Bail Error: The Account value `gf` length must be between 6 and 16
      // Not Use Bail Error: The Account value `gf` length must be between 6 and 16; The Account value `gf` must be the same as field QQ
}

Ci​

  • 说明： Ci 方法用于设置需要比较数值的规则时，不区分字段的大小写。

  • 格式：

Ci() *Validator
  • 示例：
func ExampleValidator_Ci() {

      type BizReq struct {
          Account   string `v:"required"`
          Password  string `v:"required|same:Password2"`
          Password2 string `v:"required"`
      }

      var (
          ctx = context.Background()
          req = BizReq{
              Account:   "gf",
              Password:  "Goframe.org", // Diff from Password2, but because of "ci", rule check passed
              Password2: "goframe.org",
          }
      )

      if err := g.Validator().Data(req).Run(ctx); err != nil {
          fmt.Println("Not Use CI Error:", err)
      }

      if err := g.Validator().Ci().Data(req).Run(ctx); err == nil {
          fmt.Println("Use CI Passed!")
      }

      // output:
      // Not Use CI Error: The Password value `Goframe.org` must be the same as field Password2
      // Use CI Passed!
}

Data​

  • 说明： Data 方法用于传递需要联合校验的数据。

  • 格式：

Data(data interface{}) *Validator
  • 示例：
func ExampleValidator_Data() {
      type BizReq struct {
          Password1 string `v:"password"`
          Password2 string `v:"password"`
      }

      var (
          ctx = context.Background()
          req = BizReq{
              Password1: "goframe",
              Password2: "gofra", // error length between 6 and 18
          }
      )
      if err := g.Validator().Data(req).Run(ctx); err != nil {
          fmt.Print(err)
      }

      // Output:
      // The Password2 value `gofra` is not a valid password format
}

Assoc​

  • 说明：Assoc 是一个链式操作函数，为当前 Validator 设置验证的数据。参数 assoc 的类型通常是 map，指定了 union validator 中的 map 的值。

  • 注意：使用非 nil 的 assoc 参数，会将 useDataInsteadOfObjectAttributes 属性设置为 true。

  • 格式：

Assoc(assoc interface{}) *Validator
  • 示例：
func ExampleValidator_Assoc() {

      type User struct {
          Name string `v:"required"`
          Type int    `v:"required"`
      }

      data := g.Map{
          "name": "john",
      }

      user := User{}

      if err := gconv.Scan(data, &user); err != nil {
          panic(err)
      }

      if err := g.Validator().Data(user).Assoc(data).Run(context.Background()); err != nil {
          fmt.Print(err)
      }

      // Output:
      // The Type field is required
}

Rules​

  • 说明： Rules 方法用于传递当前链式操作校验的自定义校验规则。

  • 格式：

Rules(rules interface{}) *Validator
  • 示例：
func ExampleValidator_Rules() {

      if err := g.Validator().Data(16).Rules("min:18").Run(context.Background()); err != nil {
          fmt.Println(err)
      }

      // Output:
      // The value `16` must be equal or greater than 18
}

Message​

  • 说明： Messages 方法用于传递当前链式操作校验的自定义错误提示信息。

  • 格式：

Messages(messages interface{}) *Validator
  • 示例：
func ExampleValidator_Messages() {
      if err := g.Validator().Data(16).Rules("min:18").Messages("Can not regist, Age is less then 18!").Run(context.Background()); err != nil {
          fmt.Println(err)
      }

      // Output:
      // Can not regist, Age is less then 18!
}

RuleFunc​

  • 说明：RuleFunc 向当前的 Validator 注册一个自定义校验规则的函数。

  • 格式：

RuleFunc(rule string, f RuleFunc) *Validator
  • 示例：
func ExampleValidator_RuleFunc() {
      var (
          ctx             = context.Background()
          lenErrRuleName  = "LenErr"
          passErrRuleName = "PassErr"
          lenErrRuleFunc  = func(ctx context.Context, in gvalid.RuleFuncInput) error {
              pass := in.Value.String()
              if len(pass) != 6 {
                  return errors.New(in.Message)
              }
              return nil
          }
          passErrRuleFunc = func(ctx context.Context, in gvalid.RuleFuncInput) error {
              pass := in.Value.String()
              if m := in.Data.Map(); m["data"] != pass {
                  return errors.New(in.Message)
              }
              return nil
          }
      )

      type LenErrStruct struct {
          Value string `v:"uid@LenErr#Value Length Error!"`
          Data  string `p:"data"`
      }

      st := &LenErrStruct{
          Value: "123",
          Data:  "123456",
      }
      // single error sample
      if err := g.Validator().RuleFunc(lenErrRuleName, lenErrRuleFunc).Data(st).Run(ctx); err != nil {
          fmt.Println(err)
      }

      type MultiErrorStruct struct {
          Value string `v:"uid@LenErr|PassErr#Value Length Error!|Pass is not Same!"`
          Data  string `p:"data"`
      }

      multi := &MultiErrorStruct{
          Value: "123",
          Data:  "123456",
      }
      // multi error sample
      if err := g.Validator().RuleFunc(lenErrRuleName, lenErrRuleFunc).RuleFunc(passErrRuleName, passErrRuleFunc).Data(multi).Run(ctx); err != nil {
          fmt.Println(err)
      }

      // Output:
      // Value Length Error!
      // Value Length Error!; Pass is not Same!
}

RuleFuncMap​

  • 说明：RuleFuncMap 向当前的 Validator 注册多个自定义校验规则的函数。

  • 格式：

RuleFuncMap(m map[string]RuleFunc) *Validator
  • 示例：
func ExampleValidator_RuleFuncMap() {
      var (
          ctx             = context.Background()
          lenErrRuleName  = "LenErr"
          passErrRuleName = "PassErr"
          lenErrRuleFunc  = func(ctx context.Context, in gvalid.RuleFuncInput) error {
              pass := in.Value.String()
              if len(pass) != 6 {
                  return errors.New(in.Message)
              }
              return nil
          }
          passErrRuleFunc = func(ctx context.Context, in gvalid.RuleFuncInput) error {
              pass := in.Value.String()
              if m := in.Data.Map(); m["data"] != pass {
                  return errors.New(in.Message)
              }
              return nil
          }
          ruleMap = map[string]gvalid.RuleFunc{
              lenErrRuleName:  lenErrRuleFunc,
              passErrRuleName: passErrRuleFunc,
          }
      )

      type MultiErrorStruct struct {
          Value string `v:"uid@LenErr|PassErr#Value Length Error!|Pass is not Same!"`
          Data  string `p:"data"`
      }

      multi := &MultiErrorStruct{
          Value: "123",
          Data:  "123456",
      }

      if err := g.Validator().RuleFuncMap(ruleMap).Data(multi).Run(ctx); err != nil {
          fmt.Println(err)
      }

      // Output:
      // Value Length Error!; Pass is not Same!
}