Gin 框架学习笔记（01）— 自定义结构体绑定表单、绑定URI、自定义log、自定义中间件、路由组、解析查询字符串、上传文件、使用HTTP方法

常用有两种：application/x-www-form-urlencoded 和 multipart/form-data，默认为 application/x-www-form-urlencoded。
​

当表单提交方法为 GET 时，浏览器用 x-www-form-urlencoded 的编码方式把表单数据转换成一个字串（name1=value1&name2=value2...），然后把这个字串追加到 URL 后面。
​

当表单提交方法为 POST 时，浏览器把表单数据封装到请求体中，然后发送到服务端。如果此时 enctype 属性为 application/x-www-form-urlencoded，则请求体是简单的键值对连接，格式如下：k1=v1&k2=v2&k3=v3。而如果此时 enctype 属性为 multipart/form-data，则请求体则是添加了分隔符、参数描述信息等内容。
​

enctype 属性表

在 Gin 框架中下列方法可以用处理表单数据：

    // PostForm 从特定的 urlencoded 表单或 multipart 表单返回特定参数的值，不存在则为空""
    func (c *Context) PostForm(key string) string

    // DefaultPostForm 从特定的 urlencoded 表单或 multipart 表单返回特定参数的值，
    // 不存在则返回指定的值
    func (c *Context) DefaultPostForm(key, defaultValue string) string

    // GetPostForm 类似 PostForm(key).从特定的 urlencoded 表单或 multipart 表单返回特定参数的值，
    // 如参数存在(即使值为"")则返回 (value, true)，不存在的参数则返回指定的值 ("", false)。
    // 例如:
    //   email=mail@example.com  -->  ("mail@example.com", true) := GetPostForm("email")
     //  email 为 "mail@example.com"
    //   email=                  -->  ("", true) := GetPostForm("email") // email 值为 ""
    //                           -->  ("", false) := GetPostForm("email") // email 不存在
    func (c *Context) GetPostForm(key string) (string, bool)

    // 从特定的 urlencoded 表单或 multipart 表单返回特定参数的字符串切片，
    // 切片的长度与指定参数的值多少有关
    func (c *Context) PostFormArray(key string) []string

    //
    func (c *Context) getFormCache()

    // 从特定的 urlencoded 表单或 multipart 表单返回特定参数的字符串切片，
    // 至少一个值存在则布尔值为true
    func (c *Context) GetPostFormArray(key string) ([]string, bool)

    // 从特定的 urlencoded 表单或 multipart 表单返回特定参数的字符串字典
    func (c *Context) PostFormMap(key string) map[string]string

    // 从特定的 urlencoded 表单或 multipart 表单返回特定参数的字符串字典，
    // 至少一个值存在则布尔值为true
    func (c *Context) GetPostFormMap(key string) (map[string]string, bool)

    // 返回表单指定参数的第一个文件
    func (c *Context) FormFile(name string) (*multipart.FileHeader, error)

    // 分析multipart表单，包括文件上传
    func (c *Context) MultipartForm() (*multipart.Form, error)

    // 将表单文件上传到特定dst
    func (c *Context) SaveUploadedFile(file *multipart.FileHeader, dst string) error

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")
}

输入输出

POST /post?id=1234&page=1 HTTP/1.1
Content-Type: application/x-www-form-urlencoded

name=manu&message=this_is_great

curl -H "Content-Type:application/x-www-form-urlencoded" -X POST -d "name=manu&message=this_is_great" "http://localhost:8080/post?id=1234&page=1"
id: 1234; page: 1; name: manu; message: this_is_great

在 Gin 框架中下列方法可以用处理 URLQuery 参数：

    // 返回指定名字参数的值，c.Params.ByName(key) 简写，
    // 如： "/user/:id"，则返回 id := c.Param("id")  id == "john"
    func (c *Context) Param(key string) string

    // Query 返回 query 中指定参数的值，如不存在则返回""。
    // c.Request.URL.Query().Get(key) 的简写，
    // 如 GET /path?id=1234&name=Manu&value=，则 c.Query("id") == "1234"
    func (c *Context) Query(key string) string

    // DefaultQuery 返回 query 中指定参数的值，如不存在则返回指定的值 defaultValue。
    // GET /?name=Manu&lastname=
    // c.DefaultQuery("name", "unknown") == "Manu"
    // c.DefaultQuery("id", "none") == "none"
    // c.DefaultQuery("lastname", "none") == ""
    func (c *Context) DefaultQuery(key, defaultValue string) string

    // GetQuery 类似 Query() , 返回 query 中指定参数的值，如参数存在(即使值为"")
    // 则返回 (value, true)，不存在的参数则返回指定的值 ("", false)。
    // c.Request.URL.Query().Get(key) 的简写
    //     GET /?name=Manu&lastname=
    //     ("Manu", true) == c.GetQuery("name")
    //     ("", false) == c.GetQuery("id")
    //     ("", true) == c.GetQuery("lastname")
    func (c *Context) GetQuery(key string) (string, bool)

    // 返回 URL 指定名字参数的字符串切片，切片的长度与指定参数的值多少有关
    func (c *Context) QueryArray(key string) []string

    //  返回 URL 指定名字参数的字符串切片与布尔值，值存在则为 true
    func (c *Context) GetQueryArray(key string) ([]string, bool)

    // 返回 URL 指定名字参数的字符串字典
    func (c *Context) QueryMap(key string) map[string]string

    // 返回 URL 指定名字参数的字符串字典与布尔值，值存在则为 true
    func (c *Context) GetQueryMap(key string) (map[string]string, bool)

对于类似 /welcome?firstname=Jane&lastname=Doe 这样的 URL， ? 后面为 Query 查询字符串参数，在 Gin 框架中有专门方法来处理这些参数，例如：

    func main() {
        router := gin.Default()

        // 使用现有的基础请求对象解析查询字符串参数。
        // 示例 URL： /welcome?firstname=Jane&lastname=Doe
        router.GET("/welcome", func(c *gin.Context) {
             firstname := c.DefaultQuery("firstname", "Guest")
            lastname := c.Query("lastname") // c.Request.URL.Query().Get("lastname") 的快捷方式
            name, _ := c.GetQuery("lastname")

            c.String(http.StatusOK, "Hello %s %s %s", firstname, lastname, name)
        })
        router.Run(":8080")
    }

程序运行在 Debug 模式时，通过浏览器访问

http://localhost:8080/welcome?firstname=Jane&lastname=Doe

上面是通过 Query 方式传递参数，在 Gin 框架中可以通过 Query()、DefaultQuery()、GetQuery() 等方法得到指定参数的值。

Query() 读取 URL 中的地址参数，例如

 // GET /path?id=1234&name=Manu&value=
   c.Query("id") == "1234"
   c.Query("name") == "Manu"
   c.Query("value") == ""
   c.Query("wtf") == ""

DefaultQuery()：类似 Query()，但是如果 key 不存在，会返回默认值

 //GET /?name=Manu&lastname=
 c.DefaultQuery("name", "unknown") == "Manu"
 c.DefaultQuery("id", "none") == "none"
 c.DefaultQuery("lastname", "none") == ""

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")
}

输出结果：

$ curl -X GET  http://localhost:8080/welcome?firstname=wohu\&lastname='1104'
Hello wohu 1104

$ curl -X GET  "http://localhost:8080/welcome?firstname=wohu&lastname=1104"
Hello wohu 1104

Issuing a HTTP redirect is easy. Both internal and external locations are supported.

r.GET("/test", func(c *gin.Context) {
	c.Redirect(http.StatusMovedPermanently, "http://www.google.com/")
})

Issuing a HTTP redirect from POST. Refer to issue: #444

r.POST("/test", func(c *gin.Context) {
	c.Redirect(http.StatusFound, "/foo")
})

Issuing a Router redirect, use HandleContext like below.

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"})
})

See the question and try the following example:

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,
				"message": "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,
				"message": "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)
	}
}

使用SecureJSON来防止json被劫持。如果给定的结构是数组值，默认将 "while(1), "添加到响应体中。

func main() {
	r := gin.Default()

	// You can also use your own secure json prefix
	// r.SecureJsonPrefix(")]}',\n")

	r.GET("/someJSON", func(c *gin.Context) {
		names := []string{"lena", "austin", "foo"}

		// Will output  :   while(1);["lena","austin","foo"]
		c.SecureJSON(http.StatusOK, names)
	})

	// Listen and serve on 0.0.0.0:8080
	r.Run(":8080")
}

绑定请求体的使用方法 c.Request.Body，但是它不能被多次调用。

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 {
    ...
  }
}

应该使用 c.ShouldBindBodyWith 避免该错误

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 {
    ...
  }
}

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")
}

使用方法：

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"

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.

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.
        dst := "test.png"
		c.SaveUploadedFile(file, dst)

		c.String(http.StatusOK, fmt.Sprintf("'%s' uploaded!", file.Filename))
	})
	router.Run(":8080")
}

使用方法

curl -X POST http://localhost:8080/upload \
  -F "file=@/Users/appleboy/test.zip" \
  -H "Content-Type: multipart/form-data"

// 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")
}

HTTP 协议支持的方法 GET、HEAD、POST、PUT、DELETE、OPTIONS、TRACE、PATCH、CONNECT 等都在 Gin 框架中都得到了支持。

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
}

使用

r := gin.New()

替代

// Default With the Logger and Recovery middleware already attached
r := gin.Default()

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")
}

func main() {
	r := gin.Default()

	// gin.H is a shortcut for map[string]interface{}
	r.GET("/someJSON", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
	})

	r.GET("/moreJSON", func(c *gin.Context) {
		// You also can use a struct
		var msg struct {
			Name    string `json:"user"`
			Message string
			Number  int
		}
		msg.Name = "Lena"
		msg.Message = "hey"
		msg.Number = 123
		// Note that msg.Name becomes "user" in the JSON
		// Will output  :   {"user": "Lena", "Message": "hey", "Number": 123}
		c.JSON(http.StatusOK, msg)
	})

	r.GET("/someXML", func(c *gin.Context) {
		c.XML(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
	})

	r.GET("/someYAML", func(c *gin.Context) {
		c.YAML(http.StatusOK, gin.H{"message": "hey", "status": http.StatusOK})
	})

	r.GET("/someProtoBuf", func(c *gin.Context) {
		reps := []int64{int64(1), int64(2)}
		label := "test"
		// The specific definition of protobuf is written in the testdata/protoexample file.
		data := &protoexample.Test{
			Label: &label,
			Reps:  reps,
		}
		// Note that data becomes binary data in the response
		// Will output protoexample.Test protobuf serialized data
		c.ProtoBuf(http.StatusOK, data)
	})

	// Listen and serve on 0.0.0.0:8080
	r.Run(":8080")
}

// NoResponse 请求的 url 不存在，返回 404
func NoResponse(c *gin.Context) {
    // 返回 404 状态码
    c.String(http.StatusNotFound, "404, page not exists!")
}

func main() {
    router := gin.Default()
    // 设定请求 url 不存在的返回值
    router.NoRoute(NoResponse)

    router.Run(":8080")
}

SetMode()这个函数来设置运行的模式，有三种模式可以设置，分别 gin.ReleaseMode、gin.TestMode 和 gin.DebugMode。正式发布时应该设置为正式模式。

func main() {
    // 正式发布模式
    gin.SetMode(gin.ReleaseMode)

    router := gin.Default()

    // 设定请求 url 不存在的返回值
    router.NoRoute(NoResponse)

    router.Run(":8080")
}

在 Gin 框架中，按照中间件作用的范围，可以分为三类中间件：全局中间件、组中间件、作用于单个处理程序的中间件。

全局中间件顾名思义，在所有的处理程序中都会生效，如下面代码中通过 Use() 方法加入的日志中间件：

// 新建一个没有任何默认中间件的路由
router := gin.New()

// 加入全局中间件日志中间件
router.Use(gin.Logger())

上面加入的日志中间件就是全局中间件，它会在每一个 HTTP 请求中生效。程序中注册的处理程序，其 URI 对应的路由信息都会包括这些中间件。
程序运行在 Debug 模式时，通过浏览器访问 http://localhost:8080/login，控制台输出如下：

[GIN-debug] GET    /login                    --> main.Login (2 handlers)
[GIN-debug] Listening and serving HTTP on :8080
[GIN] 2019/07/11 - 20:07:56 | 200 |            0s |           ::1 | GET      /login

可以看到处理程序 Login 实际上运行了两个 Handler，里面就含有日志中间件，并且日志中间件记录了该访问的日志。

可以通过 Group() 方法直接加入中间件。如下代码所示：

router := gin.New()
router.Use(gin.Recovery())

// 简单的组路由 v1，直接加入日志中间件
v1 := router.Group("/v1", gin.Logger())
{
  v1.GET("/login", Login)
}
router.Run(":8080")

也可以通过 Use() 方法在设置组路由后加入中间件。如下代码所示：

router := gin.New()
router.Use(gin.Recovery())

// 简单的组路由 v2
v2 := router.Group("/v2")
// 使用Use()方法加入日志中间件
v2.Use(gin.Logger())
{
    v2.GET("/login", Login)
}
router.Run(":8080")

组中间件只在本组路由的注册处理程序中生效，不影响到在其他组路由注册的处理程序。
程序运行在 Debug 模式时，通过浏览器访问 http://localhost:8080/v2/login，控制台输出如下：

[GIN-debug] GET /v1/login --> main.Login (3 handlers)
[GIN-debug] GET /v2/login --> main.Login (3 handlers)
[GIN-debug] Listening and serving HTTP on :8080
[GIN] 2019/07/11 - 22:40:26 | 200 | 964µs | ::1 | GET /v2/login

可以看到日志中间件在 v2 组路由中的处理程序中生效，且 v2 组路由的处理程序 Login 实际运行了三个 Handler，即全局中间件，日志中间件和路由处理程序这三个 Handler。

可以直接在单个处理程序上加入中间件。在 HTTP 请求方法中，如 GET() 方法的定义：

func (group *RouterGroup) GET(relativePath string, handlers ...HandlerFunc)

参数 handlers 可以填写多个，一般中间件写在前面而真正的处理程序写在最后。如下代码所示：

func main(){
    router := gin.New()
    router.Use(gin.Recovery())

    // 为单个处理程序添加任意数量的中间件。
    router.GET("/login",gin.Logger(), Login)

    router.Run(":8080")
}

通过控制台输出的信息可以看到 URI 路径 /login 实际上运行了三个 Handler，里面就含有日志中间件，异常恢复中间以及自身的处理程序这三个 Handler。
​

这三种中间件只是作用范围的区分，在功能上没有任何区别。比如身份验证可以作为中间件形式，选择性加在某些分组或者某些处理程序上。

在 Web 服务中，有时会出现意料之外的突发流量，尤其是中小站点资源有限，如有突发事件就会出现服务器扛不住流量的冲击，但为了保证服务的可用性，在某些情况下可采用限流的方式来保证服务可用。 Gin 框架官方对此推荐了一款中间件：

go get github.com/aviddiviner/gin-limit

    import (
        "time"

        "github.com/aviddiviner/gin-limit"
        "github.com/gin-gonic/gin"
    )

    func main() {
        router := gin.Default()

        router.Use(limit.MaxAllowed(1))

        router.GET("/test", func(c *gin.Context) {
            time.Sleep(10 * time.Second)
            c.String(200, "test")
        })

        router.Run(":8080")
    }

程序运行在 Debug 模式时，通过浏览器访问 http://localhost:8080/test，如果并发访问的数量超过程序预定的值（这里为 1），如果超过阈值 1 的访问数量限制其处理程序将会被阻塞，直到前面处理程序完成处理。
​

上面程序通过延时处理，可以模拟多个请求发生，打开浏览器，新开两个 Tab 窗口，访问 http://localhost:8080/test，由于有延时存在，可清楚观察到只有前面的处理程序完成了才会继续运行后面第二个访问的处理程序。
​

Gin 自带中间件远不止上面介绍的几种，比如 GZIP 等中间件，可以访问 https://github.com/gin-gonic/contrib 自行了解。在这里还可以了解到最新支持 Gin 框架的第三方中间件。例如：
​

Gin使用 encoding/json作为默认的 json包，但可以通过从其他标签构建来改变它。

$ go build -tags=jsoniter .

$ go build -tags=go_json .

Gin默认启用 MsgPack渲染功能。但可以通过指定 nomsgpack build标签来禁用这一功能。

$ go build -tags=nomsgpack .

这对于减少可执行文件的二进制大小很有用。
​

参考：
https://github.com/gin-gonic/gin
https://github.com/gin-gonic/examples
https://gin-gonic.com/docs/introduction/
​

https://www.jianshu.com/p/a31e4ee25305
https://blog.csdn.net/u014361775/article/details/80582910
https://learnku.com/docs/gin-gonic/1.7/examples-ascii-json/11362
​

​