Binding Request Data
Bind using struct tags
Echo provides following method to bind data from different sources (path params, query params, request body) to structure using
Context#Bind(i interface{})
method.
The default binder supports decoding application/json, application/xml and
application/x-www-form-urlencoded data based on the Content-Type header.
In the struct definitions each field can be tagged to restrict binding to specific source.
query
- source is request query parameters.param
- source is route path parameter.form
- source is form. Values are taken from query and request body. Uses Go standard library form parsing.json
- source is request body. Uses Go json package fo unmarshalling.xml
- source is request body. Uses Go xml package fo unmarshalling.
type User struct {
ID string `path:"id" query:"id" form:"id" json:"id" xml:"id"`
}
Request data is binded to the struct in given order:
- Path parameters
- Query parameters (only for GET/DELETE methods)
- Request body
Notes:
- For
query
,param
,form
only fields with tags are bound. - For
json
andxml
can bind to public fields without tags but this is by their standard library implementation. - Each step can overwrite binded fields from the previous step. This means if your json request has query param
&name=query
and body is{"name": "body"}
then the result will beUser{Name: "body"}
. - To avoid security flaws try to avoid passing binded structs directly to other methods if
these structs contain fields that should not be bindable. It is advisable to have separate struct for binding and map it
explicitly to your business struct. Consider what will happen if your binded struct has public
field
IsAdmin bool
and request body would contain{IsAdmin: true, Name: "hacker"}
. - When binding forms take note that Echo implementation uses standard library form parsing which parses form data from BOTH URL and BODY if content type is not MIMEMultipartForm. See documentation for non-MIMEMultipartForm and MIMEMultipartForm
- To bind data only from request body use following code
if err := (&DefaultBinder{}).BindBody(c, &payload); err != nil { return err }
- To bind data only from query parameters use following code
if err := (&DefaultBinder{}).BindQueryParams(c, &payload); err != nil { return err }
- To bind data only from path parameters use following code
if err := (&DefaultBinder{}).BindPathParams(c, &payload); err != nil { return err }
Example
Example below binds the request payload into User
struct based on tags:
// User
type User struct {
Name string `json:"name" form:"name" query:"name"`
Email string `json:"email" form:"email" query:"email"`
}
e.POST("/users", func(c echo.Context) (err error) {
u := new(User)
if err = c.Bind(u); err != nil {
return
}
// To avoid security flaws try to avoid passing binded structs directly to other methods
// if these structs contain fields that should not be bindable.
user := UserDTO{
Name: u.Name,
Email: u.Email,
IsAdmin: false // because you could accidentally expose fields that should not be bind
}
executeSomeBusinessLogic(user)
return c.JSON(http.StatusOK, u)
}
JSON Data
curl -X POST http://localhost:1323/users \
-H 'Content-Type: application/json' \
-d '{"name":"Joe","email":"[email protected]"}'
Form Data
curl -X POST http://localhost:1323/users \
-d 'name=Joe' \
-d '[email protected]'
Query Parameters
curl -X GET http://localhost:1323/users\?name\=Joe\&email\=[email protected]
Fast binding with dedicated helpers
For binding data found in a request a handful of helper functions are provided. This will allow binding of query parameters, path parameters or data found in the body like forms or JSON data.
Following functions provide a handful of methods for binding to Go native types from request query or path parameters. These binders offer a fluent syntax and can be chained to configure, execute binding and handle errors.
echo.QueryParamsBinder(c)
- binds query parameters (source URL)echo.PathParamsBinder(c)
- binds path parameters (source URL)echo.FormFieldBinder(c)
- binds form fields (source URL + body). See also Request.ParseForm.
A binder is usually completed by BindError()
or BindErrors()
which returns errors if binding fails.
With FailFast()
the binder can be configured stop binding on the first error or continue binding for
the binder call chain. Fail fast is enabled by default and should be disabled when using BindErrors()
.
BindError()
returns the first bind error from binder and resets all errors in this binder.
BindErrors()
returns all bind errors from binder and resets errors in binder.
// url = "/api/search?active=true&id=1&id=2&id=3&length=25"
var opts struct {
IDs []int64
Active bool
}
length := int64(50) // default length is 50
// creates query params binder that stops binding at first error
err := echo.QueryParamsBinder(c).
Int64("length", &length).
Int64s("ids", &opts.IDs).
Bool("active", &opts.Active).
BindError() // returns first binding error
Supported types
Types that are supported:
- bool
- float32
- float64
- int
- int8
- int16
- int32
- int64
- uint
- uint8/byte (does not support
bytes()
. Use BindUnmarshaler/CustomFunc to convert value from base64 etc to []byte{}) - uint16
- uint32
- uint64
- string
- time
- duration
- BindUnmarshaler() interface
- UnixTime() - converts unix time (integer) to time.Time
- UnixTimeNano() - converts unix time with nano second precision (integer) to time.Time
- CustomFunc() - callback function for your custom conversion logic
For every supported type there are following methods:
<Type>("param", &destination)
- if parameter value exists then binds it to given destination of that type i.eInt64(...)
.Must<Type>("param", &destination)
- parameter value is required to exist, binds it to given destination of that type i.eMustInt64(...)
.<Type>s("param", &destination)
- (for slices) if parameter values exists then binds it to given destination of that type i.eInt64s(...)
.Must<Type>s("param", &destination)
- (for slices) parameter value is required to exist, binds it to given destination of that type i.eMustInt64s(...)
.
for some slice types BindWithDelimiter("param", &dest, ",")
supports splitting parameter values before type conversion is done. For example URL /api/search?id=1,2,3&id=1
can be bind to []int64{1,2,3,1}
Custom Binder
Custom binder can be registered using Echo#Binder
.
type CustomBinder struct {}
func (cb *CustomBinder) Bind(i interface{}, c echo.Context) (err error) {
// You may use default binder
db := new(echo.DefaultBinder)
if err = db.Bind(i, c); err != echo.ErrUnsupportedMediaType {
return
}
// Define your custom implementation here
return
}