Middlware binding provides request data binding and validation for Macaron Instances.
go get github.com/go-macaron/bindingSuppose 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)
})That's it! The binding.Bind function takes care of validating required fields.
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.
{% hint style="danger" %} 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. {% endhint %}
By default, there is one naming convention for form tag name, which are:
Name->nameUnitPrice->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:.
{% hint style="tip" %} 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. {% endhint %}
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:
- Deserializes request data into a struct
- Performs validation with
binding.Validate - If your struct doesn't implement
binding.ErrorHandler, then default error handling will be applied. Otherwise, callsErrorHandler.Errormethod 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-Typewill be used to know how to deserialize the requests.
{% hint style="danger" %} 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. {% endhint %}
binding.Form deserializes form data from the request, whether in the query string or as a form-urlencoded payload. It only does these things:
- Deserializes request data into a struct
- Performs validation with
binding.Validate
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:
- Deserializes request data into a struct
- Performs validation with
binding.Validate
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()
}binding.Json deserializes JSON data in the payload of the request. It does the following things:
- Deserializes request data into a struct
- Performs validation with
binding.Validate
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
},
})If your rule is simple, you can also use binding.AddRule, it accepts type binding.Rule:
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.