binding

The binding middleware provides request data binding and validation for Flame instances, including Form, Multipart Form, JSON and YAML formats.

You can read source code of this middleware on GitHubbinding - 图1open in new window and API documentation on pkg.go.devbinding - 图2open in new window.

Installation

The minimum requirement of Go is 1.16.

  1. go get github.com/flamego/binding

Usage examples

TIP

Examples included in this section is to demonstrate the usage of the binding middleware, please refer to the documentation of validatorbinding - 图3open in new window package for validation syntax and constraints.

The type of binding object is injected into the request context and the special data type binding.Errorsbinding - 图4open in new window is provided to indicate any errors occurred in binding and/or validation phases.

DANGER

Pointers is prohibited be passed as the binding object to prevent side effects, and to make sure every handler gets a fresh copy of the object on every request.

Form

The binding.Formbinding - 图5open in new window takes a binding object and parses the request payload encoded as application/x-www-form-urlencoded, a binding.Optionsbinding - 图6open in new window can be used to further customize the behavior of the function.

The form struct tag should be used to indicate the binding relations between the payload and the object:

  • 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

The binding.MultipartFormbinding - 图7open in new window takes a binding object and parses the request payload encoded as multipart/form-data, a binding.Optionsbinding - 图8open in new window can be used to further customize the behavior of the function.

The form struct tag should be used to indicate the binding relations between the payload and the object, and *multipart.FileHeaderbinding - 图9open in new window should be type of the field that you’re going to store the uploaded content:

  • 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

The binding.JSONbinding - 图10open in new window takes a binding object and parses the request payload encoded as application/json, a binding.Optionsbinding - 图11open in new window can be used to further customize the behavior of the function.

The json struct tag should be used to indicate the binding relations between the payload and the object:

  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

The binding.YAMLbinding - 图12open in new window takes a binding object and parses the request payload encoded as application/yaml, a binding.Optionsbinding - 图13open in new window can be used to further customize the behavior of the function.

The yaml struct tag should be used to indicate the binding relations between the payload and the object:

  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. }

Localize validation errors

If your web application supports localization for users speak in different languages, it is equally important to provide the error message in their preferred language.

Here is a playable example in your browser to get a taste of how to localize validation errors in your own style!

  • 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 = 必须是一个电子邮箱地址