-
-[](https://travis-ci.org/gin-gonic/gin)
-[](https://codecov.io/gh/gin-gonic/gin)
-[](https://goreportcard.com/report/github.com/gin-gonic/gin)
-[](https://godoc.org/github.com/gin-gonic/gin)
-[](https://gitter.im/gin-gonic/gin?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
-[](https://sourcegraph.com/github.com/gin-gonic/gin?badge)
-[](https://www.codetriage.com/gin-gonic/gin)
-[](https://github.com/gin-gonic/gin/releases)
-
-Gin is a web framework written in Go (Golang). It features a martini-like API with much better performance, up to 40 times faster thanks to [httprouter](https://github.com/julienschmidt/httprouter). If you need performance and good productivity, you will love Gin.
-
-
-## Contents
-
-- [Installation](#installation)
-- [Prerequisite](#prerequisite)
-- [Quick start](#quick-start)
-- [Benchmarks](#benchmarks)
-- [Gin v1.stable](#gin-v1-stable)
-- [Build with jsoniter](#build-with-jsoniter)
-- [API Examples](#api-examples)
- - [Using GET,POST,PUT,PATCH,DELETE and OPTIONS](#using-get-post-put-patch-delete-and-options)
- - [Parameters in path](#parameters-in-path)
- - [Querystring parameters](#querystring-parameters)
- - [Multipart/Urlencoded Form](#multiparturlencoded-form)
- - [Another example: query + post form](#another-example-query--post-form)
- - [Map as querystring or postform parameters](#map-as-querystring-or-postform-parameters)
- - [Upload files](#upload-files)
- - [Grouping routes](#grouping-routes)
- - [Blank Gin without middleware by default](#blank-gin-without-middleware-by-default)
- - [Using middleware](#using-middleware)
- - [How to write log file](#how-to-write-log-file)
- - [Custom Log Format](#custom-log-format)
- - [Model binding and validation](#model-binding-and-validation)
- - [Custom Validators](#custom-validators)
- - [Only Bind Query String](#only-bind-query-string)
- - [Bind Query String or Post Data](#bind-query-string-or-post-data)
- - [Bind Uri](#bind-uri)
- - [Bind HTML checkboxes](#bind-html-checkboxes)
- - [Multipart/Urlencoded binding](#multiparturlencoded-binding)
- - [XML, JSON, YAML and ProtoBuf rendering](#xml-json-yaml-and-protobuf-rendering)
- - [JSONP rendering](#jsonp)
- - [Serving static files](#serving-static-files)
- - [Serving data from reader](#serving-data-from-reader)
- - [HTML rendering](#html-rendering)
- - [Multitemplate](#multitemplate)
- - [Redirects](#redirects)
- - [Custom Middleware](#custom-middleware)
- - [Using BasicAuth() middleware](#using-basicauth-middleware)
- - [Goroutines inside a middleware](#goroutines-inside-a-middleware)
- - [Custom HTTP configuration](#custom-http-configuration)
- - [Support Let's Encrypt](#support-lets-encrypt)
- - [Run multiple service using Gin](#run-multiple-service-using-gin)
- - [Graceful restart or stop](#graceful-restart-or-stop)
- - [Build a single binary with templates](#build-a-single-binary-with-templates)
- - [Bind form-data request with custom struct](#bind-form-data-request-with-custom-struct)
- - [Try to bind body into different structs](#try-to-bind-body-into-different-structs)
- - [http2 server push](#http2-server-push)
- - [Define format for the log of routes](#define-format-for-the-log-of-routes)
- - [Set and get a cookie](#set-and-get-a-cookie)
-- [Testing](#testing)
-- [Users](#users)
-
-## Installation
-
-To install Gin package, you need to install Go and set your Go workspace first.
-
-1. The first need [Go](https://golang.org/) installed (**version 1.8+ is required**), then you can use the below Go command to install Gin.
-
-```sh
-$ go get -u github.com/gin-gonic/gin
-```
-
-2. Import it in your code:
-
-```go
-import "github.com/gin-gonic/gin"
-```
-
-3. (Optional) Import `net/http`. This is required for example if using constants such as `http.StatusOK`.
-
-```go
-import "net/http"
-```
-
-### Use a vendor tool like [Govendor](https://github.com/kardianos/govendor)
-
-1. `go get` govendor
-
-```sh
-$ go get github.com/kardianos/govendor
-```
-2. Create your project folder and `cd` inside
-
-```sh
-$ mkdir -p $GOPATH/src/github.com/myusername/project && cd "$_"
-```
-
-3. Vendor init your project and add gin
-
-```sh
-$ govendor init
-$ govendor fetch github.com/gin-gonic/gin@v1.3
-```
-
-4. Copy a starting template inside your project
-
-```sh
-$ curl https://raw.githubusercontent.com/gin-gonic/examples/master/basic/main.go > main.go
-```
-
-5. Run your project
-
-```sh
-$ go run main.go
-```
-
-## Prerequisite
-
-Now Gin requires Go 1.6 or later and Go 1.7 will be required soon.
-
-## Quick start
-
-```sh
-# assume the following codes in example.go file
-$ cat example.go
-```
-
-```go
-package main
-
-import "github.com/gin-gonic/gin"
-
-func main() {
- r := gin.Default()
- r.GET("/ping", func(c *gin.Context) {
- c.JSON(200, gin.H{
- "message": "pong",
- })
- })
- r.Run() // listen and serve on 0.0.0.0:8080
-}
-```
-
-```
-# run example.go and visit 0.0.0.0:8080/ping on browser
-$ go run example.go
-```
-
-## Benchmarks
-
-Gin uses a custom version of [HttpRouter](https://github.com/julienschmidt/httprouter)
-
-[See all benchmarks](/BENCHMARKS.md)
-
-Benchmark name | (1) | (2) | (3) | (4)
---------------------------------------------|-----------:|------------:|-----------:|---------:
-**BenchmarkGin_GithubAll** | **30000** | **48375** | **0** | **0**
-BenchmarkAce_GithubAll | 10000 | 134059 | 13792 | 167
-BenchmarkBear_GithubAll | 5000 | 534445 | 86448 | 943
-BenchmarkBeego_GithubAll | 3000 | 592444 | 74705 | 812
-BenchmarkBone_GithubAll | 200 | 6957308 | 698784 | 8453
-BenchmarkDenco_GithubAll | 10000 | 158819 | 20224 | 167
-BenchmarkEcho_GithubAll | 10000 | 154700 | 6496 | 203
-BenchmarkGocraftWeb_GithubAll | 3000 | 570806 | 131656 | 1686
-BenchmarkGoji_GithubAll | 2000 | 818034 | 56112 | 334
-BenchmarkGojiv2_GithubAll | 2000 | 1213973 | 274768 | 3712
-BenchmarkGoJsonRest_GithubAll | 2000 | 785796 | 134371 | 2737
-BenchmarkGoRestful_GithubAll | 300 | 5238188 | 689672 | 4519
-BenchmarkGorillaMux_GithubAll | 100 | 10257726 | 211840 | 2272
-BenchmarkHttpRouter_GithubAll | 20000 | 105414 | 13792 | 167
-BenchmarkHttpTreeMux_GithubAll | 10000 | 319934 | 65856 | 671
-BenchmarkKocha_GithubAll | 10000 | 209442 | 23304 | 843
-BenchmarkLARS_GithubAll | 20000 | 62565 | 0 | 0
-BenchmarkMacaron_GithubAll | 2000 | 1161270 | 204194 | 2000
-BenchmarkMartini_GithubAll | 200 | 9991713 | 226549 | 2325
-BenchmarkPat_GithubAll | 200 | 5590793 | 1499568 | 27435
-BenchmarkPossum_GithubAll | 10000 | 319768 | 84448 | 609
-BenchmarkR2router_GithubAll | 10000 | 305134 | 77328 | 979
-BenchmarkRivet_GithubAll | 10000 | 132134 | 16272 | 167
-BenchmarkTango_GithubAll | 3000 | 552754 | 63826 | 1618
-BenchmarkTigerTonic_GithubAll | 1000 | 1439483 | 239104 | 5374
-BenchmarkTraffic_GithubAll | 100 | 11383067 | 2659329 | 21848
-BenchmarkVulcan_GithubAll | 5000 | 394253 | 19894 | 609
-
-- (1): Total Repetitions achieved in constant time, higher means more confident result
-- (2): Single Repetition Duration (ns/op), lower is better
-- (3): Heap Memory (B/op), lower is better
-- (4): Average Allocations per Repetition (allocs/op), lower is better
-
-## Gin v1. stable
-
-- [x] Zero allocation router.
-- [x] Still the fastest http router and framework. From routing to writing.
-- [x] Complete suite of unit tests
-- [x] Battle tested
-- [x] API frozen, new releases will not break your code.
-
-## Build with [jsoniter](https://github.com/json-iterator/go)
-
-Gin uses `encoding/json` as default json package but you can change to [jsoniter](https://github.com/json-iterator/go) by build from other tags.
-
-```sh
-$ go build -tags=jsoniter .
-```
-
-## API Examples
-
-You can find a number of ready-to-run examples at [Gin examples repository](https://github.com/gin-gonic/examples).
-
-### Using GET, POST, PUT, PATCH, DELETE and OPTIONS
-
-```go
-func main() {
- // Creates a gin router with default middleware:
- // logger and recovery (crash-free) middleware
- router := gin.Default()
-
- router.GET("/someGet", getting)
- router.POST("/somePost", posting)
- router.PUT("/somePut", putting)
- router.DELETE("/someDelete", deleting)
- router.PATCH("/somePatch", patching)
- router.HEAD("/someHead", head)
- router.OPTIONS("/someOptions", options)
-
- // By default it serves on :8080 unless a
- // PORT environment variable was defined.
- router.Run()
- // router.Run(":3000") for a hard coded port
-}
-```
-
-### Parameters in path
-
-```go
-func main() {
- router := gin.Default()
-
- // This handler will match /user/john but will not match /user/ or /user
- router.GET("/user/:name", func(c *gin.Context) {
- name := c.Param("name")
- c.String(http.StatusOK, "Hello %s", name)
- })
-
- // However, this one will match /user/john/ and also /user/john/send
- // If no other routers match /user/john, it will redirect to /user/john/
- router.GET("/user/:name/*action", func(c *gin.Context) {
- name := c.Param("name")
- action := c.Param("action")
- message := name + " is " + action
- c.String(http.StatusOK, message)
- })
-
- router.Run(":8080")
-}
-```
-
-### Querystring parameters
-
-```go
-func main() {
- router := gin.Default()
-
- // Query string parameters are parsed using the existing underlying request object.
- // The request responds to a url matching: /welcome?firstname=Jane&lastname=Doe
- router.GET("/welcome", func(c *gin.Context) {
- firstname := c.DefaultQuery("firstname", "Guest")
- lastname := c.Query("lastname") // shortcut for c.Request.URL.Query().Get("lastname")
-
- c.String(http.StatusOK, "Hello %s %s", firstname, lastname)
- })
- router.Run(":8080")
-}
-```
-
-### Multipart/Urlencoded Form
-
-```go
-func main() {
- router := gin.Default()
-
- router.POST("/form_post", func(c *gin.Context) {
- message := c.PostForm("message")
- nick := c.DefaultPostForm("nick", "anonymous")
-
- c.JSON(200, gin.H{
- "status": "posted",
- "message": message,
- "nick": nick,
- })
- })
- router.Run(":8080")
-}
-```
-
-### Another example: query + post form
-
-```
-POST /post?id=1234&page=1 HTTP/1.1
-Content-Type: application/x-www-form-urlencoded
-
-name=manu&message=this_is_great
-```
-
-```go
-func main() {
- router := gin.Default()
-
- router.POST("/post", func(c *gin.Context) {
-
- id := c.Query("id")
- page := c.DefaultQuery("page", "0")
- name := c.PostForm("name")
- message := c.PostForm("message")
-
- fmt.Printf("id: %s; page: %s; name: %s; message: %s", id, page, name, message)
- })
- router.Run(":8080")
-}
-```
-
-```
-id: 1234; page: 1; name: manu; message: this_is_great
-```
-
-### Map as querystring or postform parameters
-
-```
-POST /post?ids[a]=1234&ids[b]=hello HTTP/1.1
-Content-Type: application/x-www-form-urlencoded
-
-names[first]=thinkerou&names[second]=tianou
-```
-
-```go
-func main() {
- router := gin.Default()
-
- router.POST("/post", func(c *gin.Context) {
-
- ids := c.QueryMap("ids")
- names := c.PostFormMap("names")
-
- fmt.Printf("ids: %v; names: %v", ids, names)
- })
- router.Run(":8080")
-}
-```
-
-```
-ids: map[b:hello a:1234], names: map[second:tianou first:thinkerou]
-```
-
-### Upload files
-
-#### Single file
-
-References issue [#774](https://github.com/gin-gonic/gin/issues/774) and detail [example code](https://github.com/gin-gonic/examples/tree/master/upload-file/single).
-
-`file.Filename` **SHOULD NOT** be trusted. See [`Content-Disposition` on MDN](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition#Directives) and [#1693](https://github.com/gin-gonic/gin/issues/1693)
-
-> The filename is always optional and must not be used blindly by the application: path information should be stripped, and conversion to the server file system rules should be done.
-
-```go
-func main() {
- router := gin.Default()
- // Set a lower memory limit for multipart forms (default is 32 MiB)
- // router.MaxMultipartMemory = 8 << 20 // 8 MiB
- router.POST("/upload", func(c *gin.Context) {
- // single file
- file, _ := c.FormFile("file")
- log.Println(file.Filename)
-
- // Upload the file to specific dst.
- // c.SaveUploadedFile(file, dst)
-
- c.String(http.StatusOK, fmt.Sprintf("'%s' uploaded!", file.Filename))
- })
- router.Run(":8080")
-}
-```
-
-How to `curl`:
-
-```bash
-curl -X POST http://localhost:8080/upload \
- -F "file=@/Users/appleboy/test.zip" \
- -H "Content-Type: multipart/form-data"
-```
-
-#### Multiple files
-
-See the detail [example code](https://github.com/gin-gonic/examples/tree/master/upload-file/multiple).
-
-```go
-func main() {
- router := gin.Default()
- // Set a lower memory limit for multipart forms (default is 32 MiB)
- // router.MaxMultipartMemory = 8 << 20 // 8 MiB
- router.POST("/upload", func(c *gin.Context) {
- // Multipart form
- form, _ := c.MultipartForm()
- files := form.File["upload[]"]
-
- for _, file := range files {
- log.Println(file.Filename)
-
- // Upload the file to specific dst.
- // c.SaveUploadedFile(file, dst)
- }
- c.String(http.StatusOK, fmt.Sprintf("%d files uploaded!", len(files)))
- })
- router.Run(":8080")
-}
-```
-
-How to `curl`:
-
-```bash
-curl -X POST http://localhost:8080/upload \
- -F "upload[]=@/Users/appleboy/test1.zip" \
- -F "upload[]=@/Users/appleboy/test2.zip" \
- -H "Content-Type: multipart/form-data"
-```
-
-### Grouping routes
-
-```go
-func main() {
- router := gin.Default()
-
- // Simple group: v1
- v1 := router.Group("/v1")
- {
- v1.POST("/login", loginEndpoint)
- v1.POST("/submit", submitEndpoint)
- v1.POST("/read", readEndpoint)
- }
-
- // Simple group: v2
- v2 := router.Group("/v2")
- {
- v2.POST("/login", loginEndpoint)
- v2.POST("/submit", submitEndpoint)
- v2.POST("/read", readEndpoint)
- }
-
- router.Run(":8080")
-}
-```
-
-### Blank Gin without middleware by default
-
-Use
-
-```go
-r := gin.New()
-```
-
-instead of
-
-```go
-// Default With the Logger and Recovery middleware already attached
-r := gin.Default()
-```
-
-
-### Using middleware
-```go
-func main() {
- // Creates a router without any middleware by default
- r := gin.New()
-
- // Global middleware
- // Logger middleware will write the logs to gin.DefaultWriter even if you set with GIN_MODE=release.
- // By default gin.DefaultWriter = os.Stdout
- r.Use(gin.Logger())
-
- // Recovery middleware recovers from any panics and writes a 500 if there was one.
- r.Use(gin.Recovery())
-
- // Per route middleware, you can add as many as you desire.
- r.GET("/benchmark", MyBenchLogger(), benchEndpoint)
-
- // Authorization group
- // authorized := r.Group("/", AuthRequired())
- // exactly the same as:
- authorized := r.Group("/")
- // per group middleware! in this case we use the custom created
- // AuthRequired() middleware just in the "authorized" group.
- authorized.Use(AuthRequired())
- {
- authorized.POST("/login", loginEndpoint)
- authorized.POST("/submit", submitEndpoint)
- authorized.POST("/read", readEndpoint)
-
- // nested group
- testing := authorized.Group("testing")
- testing.GET("/analytics", analyticsEndpoint)
- }
-
- // Listen and serve on 0.0.0.0:8080
- r.Run(":8080")
-}
-```
-
-### How to write log file
-```go
-func main() {
- // Disable Console Color, you don't need console color when writing the logs to file.
- gin.DisableConsoleColor()
-
- // Logging to a file.
- f, _ := os.Create("gin.log")
- gin.DefaultWriter = io.MultiWriter(f)
-
- // Use the following code if you need to write the logs to file and console at the same time.
- // gin.DefaultWriter = io.MultiWriter(f, os.Stdout)
-
- router := gin.Default()
- router.GET("/ping", func(c *gin.Context) {
- c.String(200, "pong")
- })
-
- router.Run(":8080")
-}
-```
-
-### Custom Log Format
-```go
-func main() {
- router := gin.New()
-
- // LoggerWithFormatter middleware will write the logs to gin.DefaultWriter
- // By default gin.DefaultWriter = os.Stdout
- router.Use(gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string {
-
- // your custom format
- return fmt.Sprintf("%s - [%s] \"%s %s %s %d %s \"%s\" %s\"\n",
- param.ClientIP,
- param.TimeStamp.Format(time.RFC1123),
- param.Method,
- param.Path,
- param.Request.Proto,
- param.StatusCode,
- param.Latency,
- param.Request.UserAgent(),
- param.ErrorMessage,
- )
- }))
- router.Use(gin.Recovery())
-
- router.GET("/ping", func(c *gin.Context) {
- c.String(200, "pong")
- })
-
- router.Run(":8080")
-}
-```
-
-**Sample Output**
-```
-::1 - [Fri, 07 Dec 2018 17:04:38 JST] "GET /ping HTTP/1.1 200 122.767µs "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/71.0.3578.80 Safari/537.36" "
-```
-
-### Controlling Log output coloring
-
-By default, logs output on console should be colorized depending on the detected TTY.
-
-Never colorize logs:
-
-```go
-func main() {
- // Disable log's color
- gin.DisableConsoleColor()
-
- // Creates a gin router with default middleware:
- // logger and recovery (crash-free) middleware
- router := gin.Default()
-
- router.GET("/ping", func(c *gin.Context) {
- c.String(200, "pong")
- })
-
- router.Run(":8080")
-}
-```
-
-Always colorize logs:
-
-```go
-func main() {
- // Force log's color
- gin.ForceConsoleColor()
-
- // Creates a gin router with default middleware:
- // logger and recovery (crash-free) middleware
- router := gin.Default()
-
- router.GET("/ping", func(c *gin.Context) {
- c.String(200, "pong")
- })
-
- router.Run(":8080")
-}
-```
-
-### Model binding and validation
-
-To bind a request body into a type, use model binding. We currently support binding of JSON, XML, YAML and standard form values (foo=bar&boo=baz).
-
-Gin uses [**go-playground/validator.v8**](https://github.com/go-playground/validator) for validation. Check the full docs on tags usage [here](http://godoc.org/gopkg.in/go-playground/validator.v8#hdr-Baked_In_Validators_and_Tags).
-
-Note that you need to set the corresponding binding tag on all fields you want to bind. For example, when binding from JSON, set `json:"fieldname"`.
-
-Also, Gin provides two sets of methods for binding:
-- **Type** - Must bind
- - **Methods** - `Bind`, `BindJSON`, `BindXML`, `BindQuery`, `BindYAML`
- - **Behavior** - These methods use `MustBindWith` under the hood. If there is a binding error, the request is aborted with `c.AbortWithError(400, err).SetType(ErrorTypeBind)`. This sets the response status code to 400 and the `Content-Type` header is set to `text/plain; charset=utf-8`. Note that if you try to set the response code after this, it will result in a warning `[GIN-debug] [WARNING] Headers were already written. Wanted to override status code 400 with 422`. If you wish to have greater control over the behavior, consider using the `ShouldBind` equivalent method.
-- **Type** - Should bind
- - **Methods** - `ShouldBind`, `ShouldBindJSON`, `ShouldBindXML`, `ShouldBindQuery`, `ShouldBindYAML`
- - **Behavior** - These methods use `ShouldBindWith` under the hood. If there is a binding error, the error is returned and it is the developer's responsibility to handle the request and error appropriately.
-
-When using the Bind-method, Gin tries to infer the binder depending on the Content-Type header. If you are sure what you are binding, you can use `MustBindWith` or `ShouldBindWith`.
-
-You can also specify that specific fields are required. If a field is decorated with `binding:"required"` and has a empty value when binding, an error will be returned.
-
-```go
-// Binding from JSON
-type Login struct {
- User string `form:"user" json:"user" xml:"user" binding:"required"`
- Password string `form:"password" json:"password" xml:"password" binding:"required"`
-}
-
-func main() {
- router := gin.Default()
-
- // Example for binding JSON ({"user": "manu", "password": "123"})
- router.POST("/loginJSON", func(c *gin.Context) {
- var json Login
- if err := c.ShouldBindJSON(&json); err != nil {
- c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
- return
- }
-
- if json.User != "manu" || json.Password != "123" {
- c.JSON(http.StatusUnauthorized, gin.H{"status": "unauthorized"})
- return
- }
-
- c.JSON(http.StatusOK, gin.H{"status": "you are logged in"})
- })
-
- // Example for binding XML (
- //
- // Using posts/index.tmpl
- -{{ end }} -``` - -templates/users/index.tmpl - -```html -{{ define "users/index.tmpl" }} -Using users/index.tmpl
- -{{ end }} -``` - -#### Custom Template renderer - -You can also use your own html template render - -```go -import "html/template" - -func main() { - router := gin.Default() - html := template.Must(template.ParseFiles("file1", "file2")) - router.SetHTMLTemplate(html) - router.Run(":8080") -} -``` - -#### Custom Delimiters - -You may use custom delims - -```go - r := gin.Default() - r.Delims("{[{", "}]}") - r.LoadHTMLGlob("/path/to/templates") -``` - -#### Custom Template Funcs - -See the detail [example code](https://github.com/gin-gonic/examples/tree/master/template). - -main.go - -```go -import ( - "fmt" - "html/template" - "net/http" - "time" - - "github.com/gin-gonic/gin" -) - -func formatAsDate(t time.Time) string { - year, month, day := t.Date() - return fmt.Sprintf("%d%02d/%02d", year, month, day) -} - -func main() { - router := gin.Default() - router.Delims("{[{", "}]}") - router.SetFuncMap(template.FuncMap{ - "formatAsDate": formatAsDate, - }) - router.LoadHTMLFiles("./testdata/template/raw.tmpl") - - router.GET("/raw", func(c *gin.Context) { - c.HTML(http.StatusOK, "raw.tmpl", map[string]interface{}{ - "now": time.Date(2017, 07, 01, 0, 0, 0, 0, time.UTC), - }) - }) - - router.Run(":8080") -} - -``` - -raw.tmpl - -```html -Date: {[{.now | formatAsDate}]} -``` - -Result: -``` -Date: 2017/07/01 -``` - -### Multitemplate - -Gin allow by default use only one html.Template. Check [a multitemplate render](https://github.com/gin-contrib/multitemplate) for using features like go 1.6 `block template`. - -### Redirects - -Issuing a HTTP redirect is easy. Both internal and external locations are supported. - -```go -r.GET("/test", func(c *gin.Context) { - c.Redirect(http.StatusMovedPermanently, "http://www.google.com/") -}) -``` - - -Issuing a Router redirect, use `HandleContext` like below. - -``` go -r.GET("/test", func(c *gin.Context) { - c.Request.URL.Path = "/test2" - r.HandleContext(c) -}) -r.GET("/test2", func(c *gin.Context) { - c.JSON(200, gin.H{"hello": "world"}) -}) -``` - - -### Custom Middleware - -```go -func Logger() gin.HandlerFunc { - return func(c *gin.Context) { - t := time.Now() - - // Set example variable - c.Set("example", "12345") - - // before request - - c.Next() - - // after request - latency := time.Since(t) - log.Print(latency) - - // access the status we are sending - status := c.Writer.Status() - log.Println(status) - } -} - -func main() { - r := gin.New() - r.Use(Logger()) - - r.GET("/test", func(c *gin.Context) { - example := c.MustGet("example").(string) - - // it would print: "12345" - log.Println(example) - }) - - // Listen and serve on 0.0.0.0:8080 - r.Run(":8080") -} -``` - -### Using BasicAuth() middleware - -```go -// simulate some private data -var secrets = gin.H{ - "foo": gin.H{"email": "foo@bar.com", "phone": "123433"}, - "austin": gin.H{"email": "austin@example.com", "phone": "666"}, - "lena": gin.H{"email": "lena@guapa.com", "phone": "523443"}, -} - -func main() { - r := gin.Default() - - // Group using gin.BasicAuth() middleware - // gin.Accounts is a shortcut for map[string]string - authorized := r.Group("/admin", gin.BasicAuth(gin.Accounts{ - "foo": "bar", - "austin": "1234", - "lena": "hello2", - "manu": "4321", - })) - - // /admin/secrets endpoint - // hit "localhost:8080/admin/secrets - authorized.GET("/secrets", func(c *gin.Context) { - // get user, it was set by the BasicAuth middleware - user := c.MustGet(gin.AuthUserKey).(string) - if secret, ok := secrets[user]; ok { - c.JSON(http.StatusOK, gin.H{"user": user, "secret": secret}) - } else { - c.JSON(http.StatusOK, gin.H{"user": user, "secret": "NO SECRET :("}) - } - }) - - // Listen and serve on 0.0.0.0:8080 - r.Run(":8080") -} -``` - -### Goroutines inside a middleware - -When starting new Goroutines inside a middleware or handler, you **SHOULD NOT** use the original context inside it, you have to use a read-only copy. - -```go -func main() { - r := gin.Default() - - r.GET("/long_async", func(c *gin.Context) { - // create copy to be used inside the goroutine - cCp := c.Copy() - go func() { - // simulate a long task with time.Sleep(). 5 seconds - time.Sleep(5 * time.Second) - - // note that you are using the copied context "cCp", IMPORTANT - log.Println("Done! in path " + cCp.Request.URL.Path) - }() - }) - - r.GET("/long_sync", func(c *gin.Context) { - // simulate a long task with time.Sleep(). 5 seconds - time.Sleep(5 * time.Second) - - // since we are NOT using a goroutine, we do not have to copy the context - log.Println("Done! in path " + c.Request.URL.Path) - }) - - // Listen and serve on 0.0.0.0:8080 - r.Run(":8080") -} -``` - -### Custom HTTP configuration - -Use `http.ListenAndServe()` directly, like this: - -```go -func main() { - router := gin.Default() - http.ListenAndServe(":8080", router) -} -``` -or - -```go -func main() { - router := gin.Default() - - s := &http.Server{ - Addr: ":8080", - Handler: router, - ReadTimeout: 10 * time.Second, - WriteTimeout: 10 * time.Second, - MaxHeaderBytes: 1 << 20, - } - s.ListenAndServe() -} -``` - -### Support Let's Encrypt - -example for 1-line LetsEncrypt HTTPS servers. - -```go -package main - -import ( - "log" - - "github.com/gin-gonic/autotls" - "github.com/gin-gonic/gin" -) - -func main() { - r := gin.Default() - - // Ping handler - r.GET("/ping", func(c *gin.Context) { - c.String(200, "pong") - }) - - log.Fatal(autotls.Run(r, "example1.com", "example2.com")) -} -``` - -example for custom autocert manager. - -```go -package main - -import ( - "log" - - "github.com/gin-gonic/autotls" - "github.com/gin-gonic/gin" - "golang.org/x/crypto/acme/autocert" -) - -func main() { - r := gin.Default() - - // Ping handler - r.GET("/ping", func(c *gin.Context) { - c.String(200, "pong") - }) - - m := autocert.Manager{ - Prompt: autocert.AcceptTOS, - HostPolicy: autocert.HostWhitelist("example1.com", "example2.com"), - Cache: autocert.DirCache("/var/www/.cache"), - } - - log.Fatal(autotls.RunWithManager(r, &m)) -} -``` - -### Run multiple service using Gin - -See the [question](https://github.com/gin-gonic/gin/issues/346) and try the following example: - -```go -package main - -import ( - "log" - "net/http" - "time" - - "github.com/gin-gonic/gin" - "golang.org/x/sync/errgroup" -) - -var ( - g errgroup.Group -) - -func router01() http.Handler { - e := gin.New() - e.Use(gin.Recovery()) - e.GET("/", func(c *gin.Context) { - c.JSON( - http.StatusOK, - gin.H{ - "code": http.StatusOK, - "error": "Welcome server 01", - }, - ) - }) - - return e -} - -func router02() http.Handler { - e := gin.New() - e.Use(gin.Recovery()) - e.GET("/", func(c *gin.Context) { - c.JSON( - http.StatusOK, - gin.H{ - "code": http.StatusOK, - "error": "Welcome server 02", - }, - ) - }) - - return e -} - -func main() { - server01 := &http.Server{ - Addr: ":8080", - Handler: router01(), - ReadTimeout: 5 * time.Second, - WriteTimeout: 10 * time.Second, - } - - server02 := &http.Server{ - Addr: ":8081", - Handler: router02(), - ReadTimeout: 5 * time.Second, - WriteTimeout: 10 * time.Second, - } - - g.Go(func() error { - return server01.ListenAndServe() - }) - - g.Go(func() error { - return server02.ListenAndServe() - }) - - if err := g.Wait(); err != nil { - log.Fatal(err) - } -} -``` - -### Graceful restart or stop - -Do you want to graceful restart or stop your web server? -There are some ways this can be done. - -We can use [fvbock/endless](https://github.com/fvbock/endless) to replace the default `ListenAndServe`. Refer issue [#296](https://github.com/gin-gonic/gin/issues/296) for more details. - -```go -router := gin.Default() -router.GET("/", handler) -// [...] -endless.ListenAndServe(":4242", router) -``` - -An alternative to endless: - -* [manners](https://github.com/braintree/manners): A polite Go HTTP server that shuts down gracefully. -* [graceful](https://github.com/tylerb/graceful): Graceful is a Go package enabling graceful shutdown of an http.Handler server. -* [grace](https://github.com/facebookgo/grace): Graceful restart & zero downtime deploy for Go servers. - -If you are using Go 1.8, you may not need to use this library! Consider using http.Server's built-in [Shutdown()](https://golang.org/pkg/net/http/#Server.Shutdown) method for graceful shutdowns. See the full [graceful-shutdown](https://github.com/gin-gonic/examples/tree/master/graceful-shutdown) example with gin. - -```go -// +build go1.8 - -package main - -import ( - "context" - "log" - "net/http" - "os" - "os/signal" - "syscall" - "time" - - "github.com/gin-gonic/gin" -) - -func main() { - router := gin.Default() - router.GET("/", func(c *gin.Context) { - time.Sleep(5 * time.Second) - c.String(http.StatusOK, "Welcome Gin Server") - }) - - srv := &http.Server{ - Addr: ":8080", - Handler: router, - } - - go func() { - // service connections - if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed { - log.Fatalf("listen: %s\n", err) - } - }() - - // Wait for interrupt signal to gracefully shutdown the server with - // a timeout of 5 seconds. - quit := make(chan os.Signal) - // kill (no param) default send syscall.SIGTERM - // kill -2 is syscall.SIGINT - // kill -9 is syscall.SIGKILL but can"t be catch, so don't need add it - signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM) - <-quit - log.Println("Shutdown Server ...") - - ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) - defer cancel() - if err := srv.Shutdown(ctx); err != nil { - log.Fatal("Server Shutdown:", err) - } - // catching ctx.Done(). timeout of 5 seconds. - select { - case <-ctx.Done(): - log.Println("timeout of 5 seconds.") - } - log.Println("Server exiting") -} -``` - -### Build a single binary with templates - -You can build a server into a single binary containing templates by using [go-assets][]. - -[go-assets]: https://github.com/jessevdk/go-assets - -```go -func main() { - r := gin.New() - - t, err := loadTemplate() - if err != nil { - panic(err) - } - r.SetHTMLTemplate(t) - - r.GET("/", func(c *gin.Context) { - c.HTML(http.StatusOK, "/html/index.tmpl",nil) - }) - r.Run(":8080") -} - -// loadTemplate loads templates embedded by go-assets-builder -func loadTemplate() (*template.Template, error) { - t := template.New("") - for name, file := range Assets.Files { - if file.IsDir() || !strings.HasSuffix(name, ".tmpl") { - continue - } - h, err := ioutil.ReadAll(file) - if err != nil { - return nil, err - } - t, err = t.New(name).Parse(string(h)) - if err != nil { - return nil, err - } - } - return t, nil -} -``` - -See a complete example in the `https://github.com/gin-gonic/examples/tree/master/assets-in-binary` directory. - -### Bind form-data request with custom struct - -The follow example using custom struct: - -```go -type StructA struct { - FieldA string `form:"field_a"` -} - -type StructB struct { - NestedStruct StructA - FieldB string `form:"field_b"` -} - -type StructC struct { - NestedStructPointer *StructA - FieldC string `form:"field_c"` -} - -type StructD struct { - NestedAnonyStruct struct { - FieldX string `form:"field_x"` - } - FieldD string `form:"field_d"` -} - -func GetDataB(c *gin.Context) { - var b StructB - c.Bind(&b) - c.JSON(200, gin.H{ - "a": b.NestedStruct, - "b": b.FieldB, - }) -} - -func GetDataC(c *gin.Context) { - var b StructC - c.Bind(&b) - c.JSON(200, gin.H{ - "a": b.NestedStructPointer, - "c": b.FieldC, - }) -} - -func GetDataD(c *gin.Context) { - var b StructD - c.Bind(&b) - c.JSON(200, gin.H{ - "x": b.NestedAnonyStruct, - "d": b.FieldD, - }) -} - -func main() { - r := gin.Default() - r.GET("/getb", GetDataB) - r.GET("/getc", GetDataC) - r.GET("/getd", GetDataD) - - r.Run() -} -``` - -Using the command `curl` command result: - -``` -$ curl "http://localhost:8080/getb?field_a=hello&field_b=world" -{"a":{"FieldA":"hello"},"b":"world"} -$ curl "http://localhost:8080/getc?field_a=hello&field_c=world" -{"a":{"FieldA":"hello"},"c":"world"} -$ curl "http://localhost:8080/getd?field_x=hello&field_d=world" -{"d":"world","x":{"FieldX":"hello"}} -``` - -### Try to bind body into different structs - -The normal methods for binding request body consumes `c.Request.Body` and they -cannot be called multiple times. - -```go -type formA struct { - Foo string `json:"foo" xml:"foo" binding:"required"` -} - -type formB struct { - Bar string `json:"bar" xml:"bar" binding:"required"` -} - -func SomeHandler(c *gin.Context) { - objA := formA{} - objB := formB{} - // This c.ShouldBind consumes c.Request.Body and it cannot be reused. - if errA := c.ShouldBind(&objA); errA == nil { - c.String(http.StatusOK, `the body should be formA`) - // Always an error is occurred by this because c.Request.Body is EOF now. - } else if errB := c.ShouldBind(&objB); errB == nil { - c.String(http.StatusOK, `the body should be formB`) - } else { - ... - } -} -``` - -For this, you can use `c.ShouldBindBodyWith`. - -```go -func SomeHandler(c *gin.Context) { - objA := formA{} - objB := formB{} - // This reads c.Request.Body and stores the result into the context. - if errA := c.ShouldBindBodyWith(&objA, binding.JSON); errA == nil { - c.String(http.StatusOK, `the body should be formA`) - // At this time, it reuses body stored in the context. - } else if errB := c.ShouldBindBodyWith(&objB, binding.JSON); errB == nil { - c.String(http.StatusOK, `the body should be formB JSON`) - // And it can accepts other formats - } else if errB2 := c.ShouldBindBodyWith(&objB, binding.XML); errB2 == nil { - c.String(http.StatusOK, `the body should be formB XML`) - } else { - ... - } -} -``` - -* `c.ShouldBindBodyWith` stores body into the context before binding. This has -a slight impact to performance, so you should not use this method if you are -enough to call binding at once. -* This feature is only needed for some formats -- `JSON`, `XML`, `MsgPack`, -`ProtoBuf`. For other formats, `Query`, `Form`, `FormPost`, `FormMultipart`, -can be called by `c.ShouldBind()` multiple times without any damage to -performance (See [#1341](https://github.com/gin-gonic/gin/pull/1341)). - -### http2 server push - -http.Pusher is supported only **go1.8+**. See the [golang blog](https://blog.golang.org/h2push) for detail information. - -```go -package main - -import ( - "html/template" - "log" - - "github.com/gin-gonic/gin" -) - -var html = template.Must(template.New("https").Parse(` - - -" as text instead of an element. - // rawTag's contents are lower-cased. - rawTag string - // textIsRaw is whether the current text token's data is not escaped. - textIsRaw bool - // convertNUL is whether NUL bytes in the current token's data should - // be converted into \ufffd replacement characters. - convertNUL bool - // allowCDATA is whether CDATA sections are allowed in the current context. - allowCDATA bool -} - -// AllowCDATA sets whether or not the tokenizer recognizes as -// the text "foo". The default value is false, which means to recognize it as -// a bogus comment "" instead. -// -// Strictly speaking, an HTML5 compliant tokenizer should allow CDATA if and -// only if tokenizing foreign content, such as MathML and SVG. However, -// tracking foreign-contentness is difficult to do purely in the tokenizer, -// as opposed to the parser, due to HTML integration points: an