binding

binding 中间件为 Flame 实例提供请求数据绑定和验证服务，支持的数据格式包括 Form、Multipart Form、JSON 和 YAML。

你可以在 GitHubbinding - 图1在新窗口打开 上阅读该中间件的源码或通过 pkg.go.devbinding - 图2在新窗口打开 查看 API 文档。

下载安装

Go 语言的最低版本要求为 1.16。

  1. go get github.com/flamego/binding

用法示例

提示

本小结仅展示 binding 中间件的相关用法，如需了解验证模块的用法请移步 validatorbinding - 图3在新窗口打开 的文档。

绑定对象自身会被注入到请求上下文中以供后续的处理器使用，并额外提供 binding.Errorsbinding - 图4在新窗口打开 用于错误传递。

警告

禁止传递绑定对象的指针以确保每个处理器都能够获得对象的全新副本，以及避免潜在的副作用而导致的意外错误。

Form

binding.Formbinding - 图5在新窗口打开 会将请求数据以 application/x-www-form-urlencoded 的编码格式将其解析到绑定对象上，binding.Optionsbinding - 图6在新窗口打开 可以被用于配置该函数的行为。

绑定对象内的字段需要使用结构体标签 form 来表示与请求数据之间的绑定关系：

  • main.go
  • templates/home.tmpl
  1. package main
  3. import (
  4.     "fmt"
  5.     "net/http"
  7.     "github.com/flamego/binding"
  8.     "github.com/flamego/flamego"
  9.     "github.com/flamego/template"
  10.     "github.com/flamego/validator"
  11. )
  13. type User struct {
  14.     FirstName string   `form:"first_name" validate:"required"`
  15.     LastName  string   `form:"last_name" validate:"required"`
  16.     Age       int      `form:"age" validate:"gte=0,lte=130"`
  17.     Email     string   `form:"email" validate:"required,email"`
  18.     Hashtags  []string `form:"hashtag"`
  19. }
  21. func main() {
  22.     f := flamego.Classic()
  23.     f.Use(template.Templater())
  24.     f.Get("/", func(t template.Template) {
  25.         t.HTML(http.StatusOK, "home")
  26.     })
  27.     f.Post("/", binding.Form(User{}), func(w http.ResponseWriter, form User, errs binding.Errors) {
  28.         if len(errs) > 0 {
  29.             var err error
  30.             switch errs[0].Category {
  31.             case binding.ErrorCategoryValidation:
  32.                 err = errs[0].Err.(validator.ValidationErrors)[0]
  33.             default:
  34.                 err = errs[0].Err
  35.             }
  36.             w.WriteHeader(http.StatusBadRequest)
  37.             _, _ = w.Write([]byte(fmt.Sprintf("Oops! Error occurred: %v", err)))
  38.             return
  39.         }
  41.         w.WriteHeader(http.StatusOK)
  42.         w.Write([]byte(fmt.Sprintf("User: %#+v", form)))
  43.     })
  44.     f.Run()
  45. }
  1. <form method="POST">
  2.   <div>
  3.     <label>First name:</label>
  4.     <input type="text" name="first_name" value="John">
  5.   </div>
  6.   <div>
  7.     <label>Last name:</label>
  8.     <input type="text" name="last_name" value="Smith">
  9.   </div>
  10.   <div>
  11.     <label>Age:</label>
  12.     <input type="number" name="age" value="90">
  13.   </div>
  14.   <div>
  15.     <label>Email:</label>
  16.     <input type="email" name="email" value="john@example.com">
  17.   </div>
  18.   <div>
  19.     <label>Hashtags:</label>
  20.     <select name="hashtag" multiple>
  21.       <option value="driver">Driver</option>
  22.       <option value="developer">Developer</option>
  23.       <option value="runner">Runner</option>
  24.     </select>
  25.   </div>
  26.   <input type="submit" name="button" value="Submit">
  27. </form>

Multipart Form

binding.MultipartFormbinding - 图7在新窗口打开 会将请求数据以 multipart/form-data 的编码格式将其解析到绑定对象上，binding.Optionsbinding - 图8在新窗口打开 可以被用于配置该函数的行为。

绑定对象内的字段需要使用结构体标签 form 来表示与请求数据之间的绑定关系，用于存储上传文件的字段则必须声明为 *multipart.FileHeaderbinding - 图9在新窗口打开 类型：

  • main.go
  • templates/home.tmpl
  1. package main
  3. import (
  4.     "fmt"
  5.     "mime/multipart"
  6.     "net/http"
  8.     "github.com/flamego/binding"
  9.     "github.com/flamego/flamego"
  10.     "github.com/flamego/template"
  11.     "github.com/flamego/validator"
  12. )
  14. type User struct {
  15.     FirstName string                `form:"first_name" validate:"required"`
  16.     LastName  string                `form:"last_name" validate:"required"`
  17.     Avatar    *multipart.FileHeader `form:"avatar"`
  18. }
  20. func main() {
  21.     f := flamego.Classic()
  22.     f.Use(template.Templater())
  23.     f.Get("/", func(t template.Template) {
  24.         t.HTML(http.StatusOK, "home")
  25.     })
  26.     f.Post("/", binding.MultipartForm(User{}), func(w http.ResponseWriter, form User, errs binding.Errors) {
  27.         if len(errs) > 0 {
  28.             var err error
  29.             switch errs[0].Category {
  30.             case binding.ErrorCategoryValidation:
  31.                 err = errs[0].Err.(validator.ValidationErrors)[0]
  32.             default:
  33.                 err = errs[0].Err
  34.             }
  35.             w.WriteHeader(http.StatusBadRequest)
  36.             _, _ = w.Write([]byte(fmt.Sprintf("Oops! Error occurred: %v", err)))
  37.             return
  38.         }
  40.         w.WriteHeader(http.StatusOK)
  41.         w.Write([]byte(fmt.Sprintf("User: %#+v", form)))
  42.     })
  43.     f.Run()
  44. }
  1. <form enctype="multipart/form-data" method="POST">
  2.   <div>
  3.     <label>First name:</label>
  4.     <input type="text" name="first_name" value="John">
  5.   </div>
  6.   <div>
  7.     <label>Last name:</label>
  8.     <input type="text" name="last_name" value="Smith">
  9.   </div>
  10.   <div>
  11.     <label>Avatar:</label>
  12.     <input type="file" name="avatar">
  13.   </div>
  14.   <input type="submit" name="button" value="Submit">
  15. </form>

JSON

binding.JSONbinding - 图10在新窗口打开 会将请求数据以 application/json 的编码格式将其解析到绑定对象上，binding.Optionsbinding - 图11在新窗口打开 可以被用于配置该函数的行为。

绑定对象内的字段需要使用结构体标签 json 来表示与请求数据之间的绑定关系：

  1. package main
  3. import (
  4.     "fmt"
  5.     "net/http"
  7.     "github.com/flamego/binding"
  8.     "github.com/flamego/flamego"
  9.     "github.com/flamego/validator"
  10. )
  12. type Address struct {
  13.     Street string `json:"street" validate:"required"`
  14.     City   string `json:"city" validate:"required"`
  15.     Planet string `json:"planet" validate:"required"`
  16.     Phone  string `json:"phone" validate:"required"`
  17. }
  19. type User struct {
  20.     FirstName string     `json:"first_name" validate:"required"`
  21.     LastName  string     `json:"last_name" validate:"required"`
  22.     Age       uint8      `json:"age" validate:"gte=0,lte=130"`
  23.     Email     string     `json:"email" validate:"required,email"`
  24.     Addresses []*Address `json:"addresses" validate:"required,dive,required"`
  25. }
  27. func main() {
  28.     f := flamego.Classic()
  29.     f.Post("/", binding.JSON(User{}), func(w http.ResponseWriter, form User, errs binding.Errors) {
  30.         if len(errs) > 0 {
  31.             var err error
  32.             switch errs[0].Category {
  33.             case binding.ErrorCategoryValidation:
  34.                 err = errs[0].Err.(validator.ValidationErrors)[0]
  35.             default:
  36.                 err = errs[0].Err
  37.             }
  38.             w.WriteHeader(http.StatusBadRequest)
  39.             _, _ = w.Write([]byte(fmt.Sprintf("Oops! Error occurred: %v", err)))
  40.             return
  41.         }
  43.         w.WriteHeader(http.StatusOK)
  44.         w.Write([]byte(fmt.Sprintf("User: %#+v", form)))
  45.     })
  46.     f.Run()
  47. }

YAML

binding.YAMLbinding - 图12在新窗口打开 会将请求数据以 application/yaml 的编码格式将其解析到绑定对象上，binding.Optionsbinding - 图13在新窗口打开 可以被用于配置该函数的行为。

绑定对象内的字段需要使用结构体标签 yaml 来表示与请求数据之间的绑定关系：

  1. package main
  3. import (
  4.     "fmt"
  5.     "net/http"
  7.     "github.com/flamego/binding"
  8.     "github.com/flamego/flamego"
  9.     "github.com/flamego/validator"
  10. )
  12. type Address struct {
  13.     Street string `yaml:"street" validate:"required"`
  14.     City   string `yaml:"city" validate:"required"`
  15.     Planet string `yaml:"planet" validate:"required"`
  16.     Phone  string `yaml:"phone" validate:"required"`
  17. }
  19. type User struct {
  20.     FirstName string     `yaml:"first_name" validate:"required"`
  21.     LastName  string     `yaml:"last_name" validate:"required"`
  22.     Age       uint8      `yaml:"age" validate:"gte=0,lte=130"`
  23.     Email     string     `yaml:"email" validate:"required,email"`
  24.     Addresses []*Address `yaml:"addresses" validate:"required,dive,required"`
  25. }
  27. func main() {
  28.     f := flamego.Classic()
  29.     f.Post("/", binding.YAML(User{}), func(w http.ResponseWriter, form User, errs binding.Errors) {
  30.         if len(errs) > 0 {
  31.             var err error
  32.             switch errs[0].Category {
  33.             case binding.ErrorCategoryValidation:
  34.                 err = errs[0].Err.(validator.ValidationErrors)[0]
  35.             default:
  36.                 err = errs[0].Err
  37.             }
  38.             w.WriteHeader(http.StatusBadRequest)
  39.             _, _ = w.Write([]byte(fmt.Sprintf("Oops! Error occurred: %v", err)))
  40.             return
  41.         }
  43.         w.WriteHeader(http.StatusOK)
  44.         w.Write([]byte(fmt.Sprintf("User: %#+v", form)))
  45.     })
  46.     f.Run()
  47. }

本地化验证错误消息

如果你的 Web 应用支持多语言，那么必然也希望能够提供本地化的错误消息给你的用户。

下面提供了一个可以在浏览器中把玩的示例来帮助你实现独居一格的本地化错误消息：

  • Directory
  • main.go
  • templates/home.tmpl
  • locale_en-US.ini
  • locale_zh-CN.ini
  1. $ tree .
  2. .
  3. ├── locales
  4. │   ├── locale_en-US.ini
  5. │   └── locale_zh-CN.ini
  6. ├── templates
  7. │   └── home.tmpl
  8. ├── go.mod
  9. ├── go.sum
  10. └── main.go
  1. package main
  3. import (
  4.     "errors"
  5.     "fmt"
  6.     "net/http"
  8.     "github.com/flamego/binding"
  9.     "github.com/flamego/flamego"
  10.     "github.com/flamego/i18n"
  11.     "github.com/flamego/template"
  12.     "github.com/flamego/validator"
  13. )
  15. type User struct {
  16.     FirstName string `form:"first_name" validate:"required"`
  17.     LastName  string `form:"last_name" validate:"required"`
  18.     Age       int    `form:"age" validate:"gte=0,lte=130"`
  19.     Email     string `form:"email" validate:"required,email"`
  20. }
  22. func main() {
  23.     f := flamego.Classic()
  24.     f.Use(template.Templater())
  25.     f.Use(i18n.I18n(
  26.         i18n.Options{
  27.             Languages: []i18n.Language{
  28.                 {Name: "en-US", Description: "English"},
  29.                 {Name: "zh-CN", Description: "简体中文"},
  30.             },
  31.         },
  32.     ))
  33.     f.Get("/", func(t template.Template) {
  34.         t.HTML(http.StatusOK, "home")
  35.     })
  36.     f.Post("/", binding.Form(User{}), func(w http.ResponseWriter, form User, errs binding.Errors, l i18n.Locale) {
  37.         if len(errs) > 0 {
  38.             var err error
  39.             switch errs[0].Category {
  40.             case binding.ErrorCategoryValidation:
  41.                 verr := errs[0].Err.(validator.ValidationErrors)[0]
  42.                 name := l.Translate("field::" + verr.Namespace())
  43.                 param := verr.Param()
  44.                 var reason string
  45.                 if param == "" {
  46.                     reason = l.Translate("validation::" + verr.Tag())
  47.                 } else {
  48.                     reason = l.Translate("validation::"+verr.Tag(), verr.Param())
  49.                 }
  50.                 err = errors.New(name + reason)
  51.             default:
  52.                 err = errs[0].Err
  53.             }
  54.             w.WriteHeader(http.StatusBadRequest)
  55.             _, _ = w.Write([]byte(fmt.Sprintf("Oops! Error occurred: %v", err)))
  56.             return
  57.         }
  59.         w.WriteHeader(http.StatusOK)
  60.         w.Write([]byte(fmt.Sprintf("User: %#+v", form)))
  61.     })
  62.     f.Run()
  63. }
  1. <form method="POST">
  2.   <div>
  3.     <label>First name:</label>
  4.     <input type="text" name="first_name" value="John">
  5.   </div>
  6.   <div>
  7.     <label>Last name:</label>
  8.     <input type="text" name="last_name" value="Smith">
  9.   </div>
  10.   <div>
  11.     <label>Age:</label>
  12.     <input type="number" name="age" value="90">
  13.   </div>
  14.   <div>
  15.     <label>Email:</label>
  16.     <input type="email" name="email" value="john@example.com">
  17.   </div>
  18.   <div>
  19.     <label>Language:</label>
  20.     <a href="?lang=en-US">English</a>,
  21.     <a href="?lang=zh-CN">简体中文</a>
  22.   </div>
  23.   <input type="submit" name="button" value="Submit">
  24. </form>
  1. [field]
  2. User.FirstName = First name
  3. User.LastName = Last name
  4. User.Age = Age
  5. User.Email = Email
  7. [validation]
  8. required = ` cannot be empty`
  9. gte = ` must be greater than or equal to %s`
  10. lte = ` must be less than or equal to %s`
  11. email = ` must be an email address`
  1. [field]
  2. User.FirstName = 名字
  3. User.LastName = 姓氏
  4. User.Age = 年龄
  5. User.Email = 邮箱
  7. [validation]
  8. required = 不能为空
  9. gte = 必须大于或等于 %s
  10. lte = 必须小于或等于 %s
  11. email = 必须是一个电子邮箱地址