gin

Overview ¶

A MVC binder for free-style of function handler with *gin.Context

Abstract ¶

There are may tedious processes for coding on web service:

1. Type conversion from HTTP query parameter to desired type in GoLang.
2. Binding body of HTTP POST to JSON object in GoLang. 2.1. Perform post-process(e.x. trim text) of binding data 2.2. Perform data validation of binding data
3. Convert the result data to JSON response.

Gin has provided foundation features on simple and versatile web application, this framework try to enhance the building of web application on instinct way.

MvcHandler ¶

A MVC handler can be any function with ruled types of parameter and defined returned types.

type MvcHandler interface{}

You can define handler of supported:

func(req *http.Request, params *gin.Params) OutputHandler {
    return TextOutputHandler("Hello World")
}

func(
    data *struct {
        // Binding data from form(or query string)
        Name string `form:"name" default:"anonymous"`
        // Binding data from uri
        Age int `uri:"id" default:"0"`
        // Binding data from header
        SessionId string `header:"session_id"`
        // Binding data from JSON
        Weight int `json:"weight"`
    },
) OutputHandler {
    return TextOutputHandler("Hello World")
}

WrapToGinHandler ¶

After you define the MVC handler, you could use "MvcBuilder.WrapToGinHandler()" to convert your handler to "gin.HandlerFunc".

mvcBuilder := NewMvcConfig().ToBuilder()
engine.Get("/your-web-service", mvcBuilder.WrapToGinHandler(your_mvc_handler))

Parameters of Handler ¶

"<struct>" - See parameter tags for automatic binding

This type of value woule be checked by ogin.ConformAndValidateStruct automatically.

"*gin.Context" - The context object of current request

TODO-Parameters of Handler ¶

"json.Unmarshaler" - If the type of value is json.Unmarshaler, use the UnmarshalJSON([]byte) function of the value

This type of value woule be checked by ogin.ConformAndValidateStruct automatically.

"gin.ResponseWriter" - See "gin.ResponseWriter"

"gin.Params" - See "gin.Params"

"*http.Request" - See "http.Request"

"http.ResponseWriter" - See "http.ResponseWriter"

"*url.URL" - See "url.URL"

"*multipart.Reader" - See "multipart.Reader"; Once you use *multipart.Form, the reader would reach EOF.

"*multipart.Form" - See "multipart.Form"

"*validator.Validate" - See go-playground/validator.v10

Tagging Struct ¶

There are various definition of tags could be used on struct:

type MyData struct {
    // Binding data from form(or query string)
    Name string `form:"name"`
    // Binding data from uri
    Age int `uri:"id"`
    // Binding data from header
    SessionId string `header:"session_id"`
    // Binding data from JSON
    Weight int `json:"weight"`
}

Form(Query string), header, or JSON body

form:"field_1" - Use query parameter param_name_1 as binding value
form:"field_2" - Must be bool type, used to indicate whether or not has viable value for this parameter
header:"header_value_1" - Use the value of URI parameter pm_1 as binding value
header:"header_value_2" - Use the form value of in_1 as binding value
uri:"uri_v_1" - Must be bool type, used to indicate whether or not has viable value for this parameter
uri:"uri_v_2" - Use the header value of Content-Type as binding value
json:"v1" - Must be bool type, used to indicate whether or not has viable value for this parameter
json:"v2" - Must be bool type, used to indicate whether or not has viable value for this parameter

TODO-Default Value

default:"20" - Gives value 20 if the value of binding is empty
default:"[20,40,30]" - Gives value [20, 40, 30](as array, no space)if the value of binding is empty

By default, if the value of binding is existing, the framework would use the default value of binding type.

Data Validation ¶

The Gin framework uses "go-playground/validator"(v10) as default validator.

See Also: Documentations of Gin's Binding: https://github.com/gin-gonic/gin#model-binding-and-validation

You can register "ErrorHandler" to resolve errors comes from "MvcHandler"

See

"MvcConfig.RegisterErrorHandlers(ErrorHandler)"

OutputHandler ¶

You can provides various combination of returned value for "MvcHandler":

OutputHandler - Single value of output body
(OutputHandler, error) - OutputHandler nad error
(OutputHandler, int) - response status and OutputHandler
(OutputHandler, int, error) - response status, OutputHandler, and error

Implements "OutputHandler"

You can implements "OutputHandler" of returned type:

type MyCar struct {}
func (self *MyUser) Output(context *gin.Context) error {
  context.JSON(200, "[1, 11, 21]")
  return nil
}

func yourHandler() *MyCar {
  return nil
}

see: "JsonOutputHandler", "TextOutputHandler", "XmlOutputHandler", etc.

TODO-Return value by other types ¶

"json.Marshaler" - If the type of returned value is json.Marshaler, use JsonOutputHandler() as output type

"string" - If the type of returned value is string, use TextOutputHandler() as output type

"fmt.Stringer" - As same as string