binding

README

binding

A powerful HTTP request parameters binder that supports struct tag expression.

Example

func Example() {
	type InfoRequest struct {
		Name          string   `path:"name"`
		Year          []int    `query:"year"`
		Email         *string  `json:"email" vd:"email($)"`
		Friendly      bool     `json:"friendly"`
		Status        string   `json:"status" default:"single"`
		Pie           float32  `json:"pie,required"`
		Hobby         []string `json:",required"`
		BodyNotFound  *int     `json:"BodyNotFound"`
		Authorization string   `header:"Authorization,required" vd:"$=='Basic 123456'"`
		SessionID     string   `cookie:"sessionid,required"`
		AutoBody      string
		AutoNotFound  *string
		TimeRFC3339   time.Time `query:"t"`
	}

	args := new(InfoRequest)
	binder := binding.New(nil)
	err := binder.BindAndValidate(args, requestExample(), new(testPathParams))

	fmt.Println("bind and validate result:")

	fmt.Printf("error: %v\n", err)

	b, _ := json.MarshalIndent(args, "", "	")
	fmt.Printf("args JSON string:\n%s\n", b)

	// Output:
	// request:
	// POST /info/henrylee2cn?year=2018&year=2019&t=2019-09-04T18%3A04%3A08%2B08%3A00 HTTP/1.1
	// Host: localhost
	// User-Agent: Go-http-client/1.1
	// Transfer-Encoding: chunked
	// Authorization: Basic 123456
	// Content-Type: application/json;charset=utf-8
	// Cookie: sessionid=987654
	//
	// 83
	// {"AutoBody":"autobody_test","Hobby":["Coding","Mountain climbing"],"email":"henrylee2cn@gmail.com","friendly":true,"pie":3.1415926}
	// 0
	//
	// bind and validate result:
	// error: <nil>
	// args JSON string:
	// {
	// 	"Name": "henrylee2cn",
	// 	"Year": [
	// 		2018,
	// 		2019
	// 	],
	// 	"email": "henrylee2cn@gmail.com",
	// 	"friendly": true,
	// 	"status": "single",
	// 	"pie": 3.1415925,
	// 	"Hobby": [
	// 		"Coding",
	// 		"Mountain climbing"
	// 	],
	// 	"BodyNotFound": null,
	// 	"Authorization": "Basic 123456",
	// 	"SessionID": "987654",
	// 	"AutoBody": "autobody_test",
	// 	"AutoNotFound": null,
	// 	"TimeRFC3339": "2019-09-04T18:04:08+08:00"
	// }
}
...

Syntax

The parameter position in HTTP request:

expression	renameable	description
path:"$name" or path:"$name,required"	Yes	URL path parameter
query:"$name" or query:"$name,required"	Yes	URL query parameter
raw_body:"" or raw_body:"required"	Yes	The raw bytes of body
form:"$name" or form:"$name,required"	Yes	The field in body, support: application/x-www-form-urlencoded, multipart/form-data
protobuf:"...(raw syntax)"	No	The field in body, support: application/x-protobuf
json:"$name" or json:"$name,required"	No	The field in body, support: application/json
header:"$name" or header:"$name,required"	Yes	Header parameter
cookie:"$name" or cookie:"$name,required"	Yes	Cookie parameter
default:"$value"	Yes	Default parameter
vd:"...(tagexpr validator syntax)"	Yes	The tagexpr expression of validator

NOTE:

• "$name" is variable placeholder
• If "$name" is empty, use the name of field
• If "$name" is -, omit the field
• Expression required or req indicates that the parameter is required
• default:"$value" defines the default value for fallback when no binding is successful
• If no position is tagged, try bind parameters from the body when the request has body,
  otherwise try bind from the URL query
• When there is unexportable and no tags, omit the field
• When there are multiple tags, or exportable and no tags, the order in which to try to bind is:
  1. path
  2. form
  3. query
  4. cookie
  5. header
  6. protobuf
  7. json
  8. default

Type Unmarshalor

TimeRFC3339-binding function is registered by default.

Register your own binding function for the specified type, e.g.:

MustRegTypeUnmarshal(reflect.TypeOf(time.Time{}), func(v string, emptyAsZero bool) (reflect.Value, error) {
	if v == "" && emptyAsZero {
		return reflect.ValueOf(time.Time{}), nil
	}
	t, err := time.Parse(time.RFC3339, v)
	if err != nil {
		return reflect.Value{}, err
	}
	return reflect.ValueOf(t), nil
})

Documentation

Overview

Example

package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"strings"
	"time"

	"github.com/henrylee2cn/goutil/httpbody"

	"github.com/bytedance/go-tagexpr/binding"
)

func main() {
	type InfoRequest struct {
		Name          string   `path:"name"`
		Year          []int    `query:"year"`
		Email         *string  `json:"email" vd:"email($)"`
		Friendly      bool     `json:"friendly"`
		Pie           float32  `json:"pie,required"`
		Hobby         []string `json:",required"`
		BodyNotFound  *int     `json:"BodyNotFound"`
		Authorization string   `header:"Authorization,required" vd:"$=='Basic 123456'"`
		userIdHeader  string   `header:"x-user_ID,required"`
		SessionID     string   `cookie:"sessionid,required"`
		AutoBody      string
		AutoNotFound  *string
		TimeRFC3339   time.Time `query:"t"`
	}

	args := new(InfoRequest)
	binder := binding.New(nil)
	err := binder.BindAndValidate(args, requestExample(), new(testPathParams))

	fmt.Println("bind and validate result:")

	fmt.Printf("error: %v\n", err)

	b, _ := json.MarshalIndent(args, "", "	")
	fmt.Printf("args JSON string:\n%s\n", b)

}

func requestExample() *http.Request {
	contentType, bodyReader, _ := httpbody.NewJSONBody(map[string]interface{}{
		"email":    "henrylee2cn@gmail.com",
		"friendly": true,
		"pie":      3.1415926,
		"Hobby":    []string{"Coding", "Mountain climbing"},
		"AutoBody": "autobody_test",
	})
	header := make(http.Header)
	header.Add("Content-Type", contentType)
	header.Add("Authorization", "Basic 123456")
	header.Add("x-user_ID", "123456")
	cookies := []*http.Cookie{
		{Name: "sessionid", Value: "987654"},
	}
	req := newRequest("http://localhost/info/henrylee2cn?year=2018&year=2019&t=2019-09-04T18%3A04%3A08%2B08%3A00", header, cookies, bodyReader)
	req.Method = "POST"
	var w bytes.Buffer
	req.Write(&w)
	fmt.Printf("request:\n%s", strings.Replace(w.String(), "\r\n", "\n", -1))

	bodyReader.(*bytes.Reader).Seek(0, 0)
	return req
}

Output:

request:
POST /info/henrylee2cn?year=2018&year=2019&t=2019-09-04T18%3A04%3A08%2B08%3A00 HTTP/1.1
Host: localhost
User-Agent: Go-http-client/1.1
Transfer-Encoding: chunked
Authorization: Basic 123456
Content-Type: application/json;charset=utf-8
Cookie: sessionid=987654
X-User_id: 123456

83
{"AutoBody":"autobody_test","Hobby":["Coding","Mountain climbing"],"email":"henrylee2cn@gmail.com","friendly":true,"pie":3.1415926}
0

bind and validate result:
error: <nil>
args JSON string:
{
	"Name": "henrylee2cn",
	"Year": [
		2018,
		2019
	],
	"email": "henrylee2cn@gmail.com",
	"friendly": true,
	"pie": 3.1415925,
	"Hobby": [
		"Coding",
		"Mountain climbing"
	],
	"BodyNotFound": null,
	"Authorization": "Basic 123456",
	"SessionID": "987654",
	"AutoBody": "autobody_test",
	"AutoNotFound": null,
	"TimeRFC3339": "2019-09-04T18:04:08+08:00"
}

Index

• func Bind(structPointer interface{}, req *http.Request, pathParams PathParams) error
• func BindAndValidate(structPointer interface{}, req *http.Request, pathParams PathParams) error
• func MustRegTypeUnmarshal(t reflect.Type, fn func(v string, emptyAsZero bool) (reflect.Value, error))
• func RegTypeUnmarshal(t reflect.Type, fn func(v string, emptyAsZero bool) (reflect.Value, error)) error
• func ResetJSONUnmarshaler(fn JSONUnmarshaler)
• func SetErrorFactory(bindErrFactory, validatingErrFactory func(failField, msg string) error)
• func SetLooseZeroMode(enable bool)
• func Validate(value interface{}) error
• type Binding
  • func Default() *Binding
  • func New(config *Config) *Binding
  • func (b *Binding) Bind(recvPointer interface{}, req *http.Request, pathParams PathParams) error
  • func (b *Binding) BindAndValidate(recvPointer interface{}, req *http.Request, pathParams PathParams) error
  • func (b *Binding) IBind(recvPointer interface{}, req Request, pathParams PathParams) error
  • func (b *Binding) IBindAndValidate(recvPointer interface{}, req Request, pathParams PathParams) error
  • func (b *Binding) SetErrorFactory(bindErrFactory, validatingErrFactory func(failField, msg string) error) *Binding
  • func (b *Binding) SetLooseZeroMode(enable bool) *Binding
  • func (b *Binding) Validate(value interface{}) error
• type Body
  • func GetBody(r *http.Request) (*Body, error)
  • func (b *Body) Bytes() []byte
  • func (Body) Close() error
  • func (b *Body) Len() int
  • func (b *Body) Reset()
• type Config
• type Error
  • func (e *Error) Error() string
• type JSONUnmarshaler
• type PathParams
• type Request

Examples

• Package

Functions

func Bind

func Bind(structPointer interface{}, req *http.Request, pathParams PathParams) error

Bind binds the request parameters.

func BindAndValidate

func BindAndValidate(structPointer interface{}, req *http.Request, pathParams PathParams) error

BindAndValidate binds the request parameters and validates them if needed.

func MustRegTypeUnmarshal

func MustRegTypeUnmarshal(t reflect.Type, fn func(v string, emptyAsZero bool) (reflect.Value, error))

MustRegTypeUnmarshal registers unmarshalor function of type. NOTE:

panic if exist error.

func RegTypeUnmarshal

func RegTypeUnmarshal(t reflect.Type, fn func(v string, emptyAsZero bool) (reflect.Value, error)) error

RegTypeUnmarshal registers unmarshalor function of type.

func ResetJSONUnmarshaler

func ResetJSONUnmarshaler(fn JSONUnmarshaler)

ResetJSONUnmarshaler reset the JSON Unmarshal function. NOTE: verifyingRequired is true if the required tag is supported.

func SetErrorFactory

func SetErrorFactory(bindErrFactory, validatingErrFactory func(failField, msg string) error)

SetErrorFactory customizes the factory of validation error. NOTE:

If errFactory==nil, the default is used

func SetLooseZeroMode

func SetLooseZeroMode(enable bool)

SetLooseZeroMode if set to true, the empty string request parameter is bound to the zero value of parameter. NOTE:

The default is false;
Suitable for these parameter types: query/header/cookie/form .

func Validate

func Validate(value interface{}) error

Validate validates whether the fields of value is valid.

Types

type Binding

type Binding struct {
	// contains filtered or unexported fields
}

Binding binding and verification tool for http request

func Default

func Default() *Binding

Default returns the default binding. NOTE:

path tag name is 'path';
query tag name is 'query';
header tag name is 'header';
cookie tag name is 'cookie';
raw_body tag name is 'raw_body';
form tag name is 'form';
validator tag name is 'vd';
protobuf tag name is 'protobuf';
json tag name is 'json';
LooseZeroMode is false.

func New

func New(config *Config) *Binding

New creates a binding tool. NOTE:

Use default tag name for config fields that are empty

func (*Binding) Bind

func (b *Binding) Bind(recvPointer interface{}, req *http.Request, pathParams PathParams) error

Bind binds the request parameters.

func (*Binding) BindAndValidate

func (b *Binding) BindAndValidate(recvPointer interface{}, req *http.Request, pathParams PathParams) error

BindAndValidate binds the request parameters and validates them if needed.

func (*Binding) IBind

func (b *Binding) IBind(recvPointer interface{}, req Request, pathParams PathParams) error

IBind binds the request parameters.

func (*Binding) IBindAndValidate

func (b *Binding) IBindAndValidate(recvPointer interface{}, req Request, pathParams PathParams) error

IBindAndValidate binds the request parameters and validates them if needed.

func (*Binding) SetErrorFactory

func (b *Binding) SetErrorFactory(bindErrFactory, validatingErrFactory func(failField, msg string) error) *Binding

SetErrorFactory customizes the factory of validation error. NOTE:

If errFactory==nil, the default is used

func (*Binding) SetLooseZeroMode

func (b *Binding) SetLooseZeroMode(enable bool) *Binding

SetLooseZeroMode if set to true, the empty string request parameter is bound to the zero value of parameter. NOTE:

The default is false;
Suitable for these parameter types: query/header/cookie/form .

func (*Binding) Validate

func (b *Binding) Validate(value interface{}) error

Validate validates whether the fields of value is valid.

type Body

type Body struct {
	*bytes.Buffer
	// contains filtered or unexported fields
}

Body body copy

func GetBody

func GetBody(r *http.Request) (*Body, error)

GetBody get the body from http.Request

func (*Body) Bytes

func (b *Body) Bytes() []byte

Bytes returns all of the body bytes.

func (Body) Close

func (Body) Close() error

Close close.

func (*Body) Len

func (b *Body) Len() int

Len returns all of the body length.

func (*Body) Reset

func (b *Body) Reset()

Reset zero offset.

type Config

type Config struct {
	// LooseZeroMode if set to true,
	// the empty string request parameter is bound to the zero value of parameter.
	// NOTE: Suitable for these parameter types: query/header/cookie/form .
	LooseZeroMode bool
	// PathParam use 'path' by default when empty
	PathParam string
	// Query use 'query' by default when empty
	Query string
	// Header use 'header' by default when empty
	Header string
	// Cookie use 'cookie' by default when empty
	Cookie string
	// RawBody use 'raw' by default when empty
	RawBody string
	// FormBody use 'form' by default when empty
	FormBody string
	// Validator use 'vd' by default when empty
	Validator string
	// contains filtered or unexported fields
}

Config the struct tag naming and so on

type Error

type Error struct {
	ErrType, FailField, Msg string
}

Error validate error

func (*Error) Error

func (e *Error) Error() string

Error implements error interface.

type JSONUnmarshaler

type JSONUnmarshaler func(data []byte, v interface{}) error

JSONUnmarshaler is the interface implemented by types that can unmarshal a JSON description of themselves.

type PathParams

type PathParams interface {
	// Get returns the value of the first parameter which key matches the given name.
	// If no matching parameter is found, an empty string is returned.
	Get(name string) (string, bool)
}

PathParams parameter acquisition interface on the URL path

type Request

type Request interface {
	GetMethod() string
	GetQuery() url.Values
	GetContentType() string
	GetHeader() http.Header
	GetCookies() []*http.Cookie
	GetBody() ([]byte, error)
	GetPostForm() (url.Values, error)
	GetForm() (url.Values, error)
}