2020最新Gin框架中文文档（更新于2020.06）定期维护

我会带着你远行 2023-02-17 08:47 49阅读 0赞

## 前言
    	哈喽，大家好，我是asong。最近在学习Gin框架。在学习的过程
    	中，一直看英文文档，对于英语渣渣的我来说，很痛苦，就想着给
    	他翻译过来，弄成中文文档，可以提高我们的学习下效率。网上翻
    	译过来的文档有很多，不过都很旧了，许多更新也没有处理，不是
    	很完整。所以我就自己一边学英语、一边翻译了这篇中文文档，现
    	在分享给你们，希望对你们有用。备注：由于文档是我自己翻译，
    	有错误欢迎指出。文档已上传个人
    	github:https://github.com/sunsong2020/Golang_Dream/tree/master/Gin/Doc
    	无水印版本获取：关注公众号：Golang梦工厂，后台回复Gin，即可获取。

备注： 这里只贴出部分重要文档 ，完整版PDF获取请按以上方式进行获取。

# 2020Gin框架中文文档 #

### 文章目录 ###

*  2020Gin框架中文文档
 *   *  安装
     *  快速开始
     *  API 例子
     *   *  使用 GET, POST, PUT, PATCH, DELETE and OPTIONS
         *  路由参数
         *  查询字符串参数
         *  Multipart/Urlencoded 表单
         *  其他示例：query+post 表单
         *  Map 作为查询字符串或 post表单 参数
         *  上传文件
         *   *  单个文件
             *  多个文件
         *  路由分组
         *  默认的没有中间件的空白 Gin
         *  使用中间件
         *  如何写入日志文件
         *  自定义日志格式
         *  控制日志输出颜色（Controlling Log output coloring）
         *  模型绑定和验证
     *  公众号：Golang梦工厂

## 安装 ##

在安装Gin包之前，你需要在你的电脑上安装Go环境并设置你的工作区。

1.  首先需要安装Go(支持版本1.11+)，然后使用以下Go命令安装Gin:

$ go get -u github.com/gin-gonic/gin

1.  在你的代码中导入Gin包:

import "github.com/gin-gonic/gin"

1.  (可选)如果使用诸如`http.StatusOK`之类的常量，则需要引入`net/http`包：

import "net/http"

## 快速开始 ##

# 假设example.go 文件中包含以下代码
    $ cat example.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 (for windows "localhost:8080")
    }

## API 例子 ##

您可以在Gin示例的仓库中找到许多现成的示例。

### 使用 GET, POST, PUT, PATCH, DELETE and OPTIONS ###

func main() { 
    	//使用默认中间件（logger 和 recovery 中间件）创建 gin 路由
    	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)
    
    	// 默认在 8080 端口启动服务，除非定义了一个 PORT 的环境变量。.
    	router.Run()
    	// router.Run(":3000") hardcode 端口号
    }

### 路由参数 ###

func main() { 
    	router := gin.Default()
    
    	// 这个handler 将会匹配 /user/john 但不会匹配 /user/ 或者 /user
    	router.GET("/user/:name", func(c *gin.Context) { 
    		name := c.Param("name")
    		c.String(http.StatusOK, "Hello %s", name)
    	})
    
    	// 但是, 这个将匹配 /user/john/ 以及 /user/john/send
    	// 如果没有其他路由器匹配 /user/john, 它将重定向到 /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.POST("/user/:name/*action", func(c *gin.Context) { 
    		c.FullPath() == "/user/:name/*action" // true
    	})
    
    	router.Run(":8080")
    }

### 查询字符串参数 ###

func main() { 
    	router := gin.Default()
    
    	// 查询字符串参数使用现有的底层 request 对象解析
    	// 请求响应匹配的 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") 快捷写法
    
    		c.String(http.StatusOK, "Hello %s %s", firstname, lastname)
    	})
    	router.Run(":8080")
    }

### Multipart/Urlencoded 表单 ###

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

### 其他示例：query+post 表单 ###

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

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 作为查询字符串或 post表单 参数 ###

POST /post?ids[a]=1234&ids[b]=hello HTTP/1.1
    Content-Type: application/x-www-form-urlencoded
    
    names[first]=thinkerou&names[second]=tianou

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]

### 上传文件 ###

#### 单个文件 ####

参考 issue [ \#774][_774] 与详细的示例代码： [example code][].

慎用 file.Filename ， 参考 [Content-Disposition on MDN][] 和 [\#1693][1693]

上传文件的文件名可以由用户自定义，所以可能包含非法字符串，为了安全起见，应该由服务端统一文件名规则。

func main() { 
    	router := gin.Default()
    	// 给表单限制上传大小 (默认是 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)
    
    		// 上传文件到指定的路径
    		c.SaveUploadedFile(file, dst)
    
    		c.String(http.StatusOK, fmt.Sprintf("'%s' uploaded!", file.Filename))
    	})
    	router.Run(":8080")
    }

curl 测试：

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

#### 多个文件 ####

参考详细示例：[example code.][]

func main() { 
    	router := gin.Default()
    	// 给表单限制上传大小 (default is 32 MiB)
    	router.MaxMultipartMemory = 8 << 20  // 8 MiB
    	router.POST("/upload", func(c *gin.Context) { 
    		// 多文件
    		form, _ := c.MultipartForm()
    		files := form.File["upload[]"]
    
    		for _, file := range files { 
    			log.Println(file.Filename)
    
    			//上传文件到指定的路径
    			c.SaveUploadedFile(file, dst)
    		}
    		c.String(http.StatusOK, fmt.Sprintf("%d files uploaded!", len(files)))
    	})
    	router.Run(":8080")
    }

curl 测试：

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"

### 路由分组 ###

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

### 默认的没有中间件的空白 Gin ###

使用:

r := gin.New()

代替

// 默认已经连接了 Logger and Recovery 中间件
    r := gin.Default()

### 使用中间件 ###

func main() { 
    	// 创建一个默认的没有任何中间件的路由
    	r := gin.New()
    
    	// 全局中间件
    	// Logger 中间件将写日志到 gin.DefaultWriter 即使你设置 GIN_MODE=release.
    	// 默认设置 gin.DefaultWriter = os.Stdout
    	r.Use(gin.Logger())
    
    	// Recovery 中间件从任何 panic 恢复，如果出现 panic，它会写一个 500 错误。
    	r.Use(gin.Recovery())
    
    	// 对于每个路由中间件，您可以根据需要添加任意数量
    	r.GET("/benchmark", MyBenchLogger(), benchEndpoint)
    
    	// 授权组
    	// authorized := r.Group("/", AuthRequired())
    	// 也可以这样
    	authorized := r.Group("/")
    	// 每个组的中间件！ 在这个实例中，我们只需要在 "authorized" 组中
    	// 使用自定义创建的 AuthRequired() 中间件
    	authorized.Use(AuthRequired())
    	{ 
    		authorized.POST("/login", loginEndpoint)
    		authorized.POST("/submit", submitEndpoint)
    		authorized.POST("/read", readEndpoint)
    
    		// 嵌套组
    		testing := authorized.Group("testing")
    		testing.GET("/analytics", analyticsEndpoint)
    	}
    
    	// 监听并服务于 0.0.0.0:8080
    	r.Run(":8080")
    }

### 如何写入日志文件 ###

func main() { 
        // 禁用控制台颜色，当你将日志写入到文件的时候，你不需要控制台颜色
        gin.DisableConsoleColor()
    
        // 写入日志文件
        f, _ := os.Create("gin.log")
        gin.DefaultWriter = io.MultiWriter(f)
    
        // 如果你需要同时写入日志文件和控制台上显示，使用下面代码
        // gin.DefaultWriter = io.MultiWriter(f, os.Stdout)
    
        router := gin.Default()
        router.GET("/ping", func(c *gin.Context) { 
            c.String(200, "pong")
        })
    
        router.Run(":8080")
    }

### 自定义日志格式 ###

func main() { 
    	router := gin.New()
    
    	// LoggerWithFormatter 中间件会将日志写入 gin.DefaultWriter
    	// 默认 gin.DefaultWriter = os.Stdout
    	router.Use(gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string { 
    
    		// 你的自定义格式
    		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")
    }

样本输出：

::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） ###

默认，控制台上输出的日志应根据检测到的TTY进行着色。

没有为日志着色：

func main() { 
        // 禁用日志的颜色
        gin.DisableConsoleColor()
        
        // 使用默认中间件创建一个 gin路由:
        // logger 与 recovery (crash-free) 中间件
        router := gin.Default()
        
        router.GET("/ping", func(c *gin.Context) { 
            c.String(200, "pong")
        })
        
        router.Run(":8080")
    }

为日志着色：

func main() { 
        //记录日志的颜色
        gin.ForceConsoleColor()
        
        // 使用默认中间件创建一个 gin路由:
        // logger 与 recovery (crash-free) 中间件
        router := gin.Default()
        
        router.GET("/ping", func(c *gin.Context) { 
            c.String(200, "pong")
        })
        
        router.Run(":8080")
    }

### 模型绑定和验证 ###

若要将请求主体绑定到结构体中，请使用模型绑定，目前支持JSON、XML、YAML和标准表单值（foo=bar&boo=baz）的绑定。

**Gin**使用[go-playground/validator.v8][go-playground_validator.v8]验证参数，点击此处查看完整文档[here][]

需要在绑定的字段上设置tag，比如，绑定格式为json，需要设置为 `json:"fieldname"`

此外，Gin提供了两种绑定方法：

*  类型 - Must bind
    
     *  方法 - Bind, BindJSON, BindXML, BindQuery, BindYAML, BindHeader
     *  行为 - 这些方法底层使用`MustBindWith`，如果存在绑定错误，请求将被以下指令中止 `c.AbortWithError(400, err).SetType(ErrorTypeBind)`，响应状态代码会被设置为400，请求头`Content-Type`被设置为`text/plain`; `charset=utf-8`。注意，如果你试图在此之后设置响应代码，将会发出一个警告 `[GIN-debug] [WARNING] Headers were already written. Wanted to override status code 400 with 422`，如果你希望更好地控制行为，请使用ShouldBind相关的方法。
 *  类型 - Should bind
    
     *  方法 - ShouldBind, ShouldBindJSON, ShouldBindXML, ShouldBindQuery, ShouldBindYAML, ShouldBindHeader。
     *  行为 - 这些方法底层使用 `ShouldBindWith`，如果存在绑定错误，则返回错误，开发人员可以正确处理请求和错误。当我们使用绑定方法时，Gin会根据`Content-Type`推断出使用哪种绑定器，如果你确定你绑定的是什么，你可以使用`MustBindWith`或者`BindingWith`。

你还可以给字段指定特定规则的修饰符，如果一个字段用`binding:"required"`修饰，并且在绑定时该字段的值为空，那么将返回一个错误。

// 绑定为 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()
    
    	// 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"})
    	})
    
    	// XML 绑定示例 (
    	// <?xml version="1.0" encoding="UTF-8"?>
    	// <root>
    	// <user>user</user>
    	// <password>123</password>
    	// </root>)
    	router.POST("/loginXML", func(c *gin.Context) { 
    		var xml Login
    		if err := c.ShouldBindXML(&xml); err != nil { 
    			c.JSON(http.StatusBadRequest, gin.H{ "error": err.Error()})
    			return
    		}
    		
    		if xml.User != "manu" || xml.Password != "123" { 
    			c.JSON(http.StatusUnauthorized, gin.H{ "status": "unauthorized"})
    			return
    		} 
    		
    		c.JSON(http.StatusOK, gin.H{ "status": "you are logged in"})
    	})
    
    	// 绑定HTML表单的示例 (user=manu&password=123)
    	router.POST("/loginForm", func(c *gin.Context) { 
    		var form Login
    		//这个将通过 content-type 头去推断绑定器使用哪个依赖。
    		if err := c.ShouldBind(&form); err != nil { 
    			c.JSON(http.StatusBadRequest, gin.H{ "error": err.Error()})
    			return
    		}
    		
    		if form.User != "manu" || form.Password != "123" { 
    			c.JSON(http.StatusUnauthorized, gin.H{ "status": "unauthorized"})
    			return
    		} 
    		
    		c.JSON(http.StatusOK, gin.H{ "status": "you are logged in"})
    	})
    
    	// 监听并服务于 0.0.0.0:8080
    	router.Run(":8080")
    }

请求示例：

$ curl -v -X POST \
      http://localhost:8080/loginJSON \
      -H 'content-type: application/json' \
      -d '{ "user": "manu" }'
    > POST /loginJSON HTTP/1.1
    > Host: localhost:8080
    > User-Agent: curl/7.51.0
    > Accept: */* > content-type: application/json > Content-Length: 18 > * upload completely sent off: 18 out of 18 bytes < HTTP/1.1 400 Bad Request < Content-Type: application/json; charset=utf-8 < Date: Fri, 04 Aug 2017 03:51:31 GMT < Content-Length: 100 < {"error":"Key: 'Login.Password' Error:Field validation for 'Password' failed on the 'required' tag"}

跳过验证：

当使用上面的`curl`命令运行上面的示例时，返回错误，因为示例中`Password`字段使用了`binding:"required"`，如果我们使用`binding:"-"`，那么它就不会报错。  
\# 运行example.go文件并在浏览器上访问0.0.0.0:8080/ping（windows访问：localhost:8080/ping）  
$ go run example.go

## 公众号：Golang梦工厂 ##

Asong是一名Golang开发工程师，专注于Golang相关技术：Golang面试、Beego、Gin、Mysql、Linux、网络、操作系统等，致力于Golang开发。欢迎关注公众号：Golang梦工厂。一起学习，一起进步。

获取文档方式：直接公众号后台回复：Gin，即可获取最新Gin中文文档。作者asong定期维护。

同时文档上传个人github：https://github.com/sunsong2020/Golang\_Dream/Gin/Doc，自行下载，能给个Star就更好了！！！

![公众号图片][format_png]

[_774]: https://github.com/gin-gonic/gin/issues/774
[example code]: https://github.com/gin-gonic/gin
[Content-Disposition on MDN]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Disposition#Directives
[1693]: https://github.com/gin-gonic/gin/issues/1693
[example code.]: https://github.com/gin-gonic/examples/tree/master/upload-file/multiple
[go-playground_validator.v8]: https://github.com/go-playground/validator
[here]: https://godoc.org/github.com/go-playground/validator#hdr-Baked_In_Validators_and_Tags
[format_png]: https://imgconvert.csdnimg.cn/aHR0cHM6Ly9zb25nLW9zcy5vc3MtY24tYmVpamluZy5hbGl5dW5jcy5jb20vd3gvcXJjb2RlX2Zvcl9naF9lZmVkNDc3NWJhNzNfMjU4LmpwZw?x-oss-process=image/format,png