Go web 开发框架 - Gin 简述
0. 背景
Go 语言开发框架很多，本文介绍Gin。
Gin 的英文意思是 杜松子酒，在它的官方介绍中提到了它的API 风格是 和 martini 相像的（ martini-like ）。而 martini 也是一个web框架，有意思的是 martini 的英文是 “马提尼”，也是一种鸡尾酒。
1. 简介
Go 是最快的全功能web框架之一，清澈，简洁。它的性能更好，速度快了40倍（相比于 martini 框架）。 Gin 是面向高性能和良好的生产力的选择。
总结就是：
- 简洁，晶莹剔透
- 性能好
特点：
- 快: 内存占用小。没有反射。
- 支持中间件: 通过中间件扩展能力。例如:Logger、授权、GZIP。
- 故障和恢复：Gin可以捕获HTTP请求期间发生的panic并恢复它。
- JSON验证: Gin可以解析和验证请求的JSON
- 路由分组：通过分组方便管理，比如控制授权与不需要授权，不同的API版本等。
- 错误管理：方便的收集HTTP请求期间发生的所有错误，可以通过中间件可以将它们写入日志文件、数据库并通过网络发送。
- 内置的视图呈现: 支持MVC，为JSON、XML和HTML呈现提供API。
- 可扩展：创建新中间件非常简单。
2. 开始之前
2.1 安装
go get -u github.com/gin-gonic/gin
2.2 导入包
import "github.com/gin-gonic/gin"
2.3 一个快速示例
简单步骤：
- 构建一个服务对象，通过 gin.Default()
- 启动服务，通过 r.Run()
示例如下：
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")
}
2.4 构建时注意事项
Gin使用encoding/json作为默认的json包，但是您可以通过从其他标记构建来更改为jsoniter。
$ go build -tags=jsoniter .
3. 使用示例
3.1 GET, POST,PUT 示例
形式如 router.GET("/someGet", getting)，第一个参数是 url 相对路径，第二个参数是 你的 hadler 处理器。
hadler 处理器的函数签名是：func(c *gin.Context) { }
func main() {
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)
router.Run()
}
3.2 处理URL路径中的参数（比如：/user/:name）
Parameters in path
func main() {
router := gin.Default()
// 匹配 /user/john
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)
})
// For each matched request Context will hold the route definition
router.POST("/user/:name/*action", func(c *gin.Context) {
c.FullPath() == "/user/:name/*action" // true
})
router.Run(":8080")
}
3.3 读取URL中的查询字符串
使用： c.DefaultQuery(), 或者 c.Query() 方法。
func main() {
router := gin.Default()
// 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")
}
3.4 读取URL中的查询字符串
使用: c.PostForm() 方法
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")
}
3.5 处理文件上传
获得文件：
file, _ := c.FormFile("file")
保存文件：
c.SaveUploadedFile(file, dst)
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")
}
3.6 路由分组
使用 router.Group("/v1") 实现 路由分组。
Grouping routes
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")
}
3.7 呈现 HTML 视图 （ HTML rendering ）
通过 LoadHTMLGlob() 或者 LoadHTMLFiles() 加载模板
通过 c.HTML(http.StatusOK, "index.tmpl", gin.H{
"title": "Main website",
})
第一个参数是 http 状态码，第二个参数是模板名，第三个参数是传入的参数值。
func main() {
router := gin.Default()
router.LoadHTMLGlob("templates/*")
//router.LoadHTMLFiles("templates/template1.html", "templates/template2.html")
router.GET("/index", func(c *gin.Context) {
c.HTML(http.StatusOK, "index.tmpl", gin.H{
"title": "Main website",
})
})
router.Run(":8080")
}
templates/index.tmpl
{{ .title }}
3.8 自定义中间件（Custom Middleware）
中间件是个函数，签名格式： func(c *gin.Context) {}
通过 c.Next() 表达继续在 链条中传递。
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")
}
更多内容，请参阅 官方Github
4. 参考
官网
https://gin-gonic.com/
官方github
https://github.com/gin-gonic/gin
官方github 的 readme 翻译
https://www.jianshu.com/p/98965b3ff638/
多款 Go 语言开发框架 介绍（含对比）
https://github.com/speedwheel/awesome-go-web-frameworks/blob/master/README.md#popularity
Martini是一个强大为了编写模块化Web应用而生的GO语言框架.
https://github.com/go-martini/martini/blob/master/translations/README_zh_cn.md