Data Binding and Validation
go get github.com/go-macaron/binding
Suppose you have a contact form on your site where at least name and message are required. We'll need a struct to receive the data:
type ContactForm struct {
Name string `form:"name" binding:"Required"`
Email string `form:"email"`
Message string `form:"message" binding:"Required"`
MailingAddress string `form:"mailing_address"`
}
Then we simply add our route in Macaron:
m.Post("/contact/submit", binding.Bind(ContactForm{}), func(contact ContactForm) string {
return fmt.Sprintf("Name: %s\nEmail: %s\nMessage: %s\nMailing Address: %v",
contact.Name, contact.Email, contact.Message, contact.MailingAddress)
})
By default, if there are any errors (like a required field is empty), binding middleware will return an error to the client and your app won't even see the request. To prevent this behavior, you can use
binding.BindIgnErr
instead.Don't try to bind to embedded struct pointers; it won't work. See martini-contrib/binding issue 30 if you want to help with this.
By default, there is one naming convention for form tag name, which are:
Name
->name
UnitPrice
->unit_price
For example, previous example can be simplified with following code:
type ContactForm struct {
Name string `binding:"Required"`
Email string
Message string `binding:"Required"`
MailingAddress string
}
Clean and neat, isn't it?
If you want to custom your app naming convention, you can use
binding.SetNameMapper
function, which accepts a function that is type of binding.NameMapper
.To get data from JSON payloads, simply use the
json:
struct tags instead of form:
.Use JSON-to-Go to correctly convert JSON to a Go type definition. It's useful if you're new to this or the structure is large/complex.
If you'd like to bind the data to an interface rather than to a concrete struct, you can specify the interface and use it like this:
m.Post("/contact/submit", binding.Bind(ContactForm{}, (*MyInterface)(nil)), func(contact MyInterface) {
// ... your struct became an interface!
})
Each of these middleware handlers are independent and optional, though be aware that some handlers invoke other ones.
binding.Bind
is a convenient wrapper over the other handlers in this package. It does the following boilerplate for you:- 1.Deserializes request data into a struct
- 2.
- 3.If your struct doesn't implement
binding.ErrorHandler
, then default error handling will be applied. Otherwise, callsErrorHandler.Error
method to perform custom error handling.
Notes:
- Your application (the final handler) will not even see the request if there are any errors when default error handling is applied.
- Header
Content-Type
will be used to know how to deserialize the requests.
Don't attempt to bind a pointer to a struct. This will cause a panic to prevent a race condition where every request would be pointing to the same struct.
binding.Form
deserializes form data from the request, whether in the query string or as a form-urlencoded
payload. It only does these things:- 1.Deserializes request data into a struct
- 2.
Note that it does not handle errors. You may receive a
binding.Errors
into your own handler if you want to handle errors.Like
binding.Form
, binding.MultipartForm
deserializes form data from a request into the struct you pass in. Additionally, this will deserialize a POST request that has a form of enctype="multipart/form-data"
. If the bound struct contains a field of type *multipart.FileHeader
(or []*multipart.FileHeader
), you also can read any uploaded files that were part of the form.This handler does the following:
- 1.Deserializes request data into a struct
- 2.
Again, like
binding.Form
, no error handling is performed, but you can get the errors in your handler by receiving a binding.Errors
type.type UploadForm struct {
Title string `form:"title"`
TextUpload *multipart.FileHeader `form:"txtUpload"`
}
func main() {
m := macaron.Classic()
m.Post("/", binding.MultipartForm(UploadForm{}), uploadHandler(uf UploadForm) string {
file, err := uf.TextUpload.Open()
// ... you can now read the uploaded file
})
m.Run()
}
- 1.Deserializes request data into a struct
- 2.
Similar to
binding.Form
, no error handling is performed, but you can get the errors and handle them yourself.
binding.Validate
receives a populated struct and checks it for errors with basic rules. It will execute the Validator.Validate()
method on the struct, if it is a binding.Validator
.There are some builtin validation rules. To use them, the tag format is
binding:"<Name>"
.Name | Note |
OmitEmpty | Omit rest of validations if value is empty |
Required | Must be non-zero value |
AlphaDash | Must be alpha characters or numerics or -_ |
AlphaDashDot | Must be alpha characters or numerics, -_ or . |
Size(int) | Fixed length |
MinSize(int) | Minimum length |
MaxSize(int) | Maximum length |
Range(int,int) | Value range(inclusive) |
Email | Must be E-mail address |
Url | Must be HTTP/HTTPS URL address |
In(a,b,c,...) | Must be one of element in array |
NotIn(a,b,c,...) | Must not be one of element in array |
Include(string) | Must contain |
Exclude(string) | Must not contain |
Default(string) | Set default value when field is zero-value(cannot use this when bind with interface wrapper) |
To combine multiple rules:
binding:"Required;MinSize(10)"
.If you want additional validation beyond just checking required fields, your struct can implement the
binding.Validator
interface like so:func (cf ContactForm) Validate(ctx *macaron.Context, errs binding.Errors) binding.Errors {
if strings.Contains(cf.Message, "Go needs generics") {
errs = append(errors, binding.Error{
FieldNames: []string{"message"},
Classification: "ComplaintError",
Message: "Go has generics. They're called interfaces.",
})
}
return errs
}
Now, any contact form submissions with "Go needs generics" in the message will return an error explaining your folly.
If you need to more validation rules that are applied automatically for you, you can add custom rules by function
binding.AddParamRule
, it accepts type binding.ParamRule
as argument.Suppose you want to limit minimum value:
binding.AddParamRule(&binding.ParamRule{
IsMatch: func(rule string) bool {
return strings.HasPrefix(rule, "Min(")
},
IsValid: func(errs binding.Errors, rule, name string, v interface{}) (bool, binding.Errors) {
num, ok := v.(int)
if !ok {
return false, errs
}
min, _ := strconv.Atoi(rule[4 : len(rule)-1])
if num < min {
errs.Add([]string{name}, "MinimumValue", "Value is too small")
return false, errs
}
return true, errs
},
})
binding.AddRule(&binding.Rule{
IsMatch: func(rule string) bool {
return rule == "String"
},
IsValid: func(errs binding.Errors, name string, v interface{}) (bool, binding.Errors) {
_, ok := v.(string)
return ok, errs
},
})
Custom validation rules are applied after builtin rules.
If you want to avoid default error handle process but still want binding middleware calls handle function for you, your struct can implement the
binding.ErrorHandler
interface like so:func (cf ContactForm) Error(ctx *macaron.Context, errs binding.Errors) {
// Custom process to handle error.
}
This operation happens after your custom validation.
Last modified 3yr ago