Golang 微框架 Gin 簡介
框架一直是敏捷開發中的利器，能讓開發者很快的上手並做出應用，甚至有的時候，脫離了框架，一些開發者都不會寫程序了。成長總不會一蹴而就，從寫出程序獲取成就感，再到精通框架，快速構造應用，當這些方面都得心應手的時候，可以嘗試改造一些框架，或是自己創造一個。
曾經我以為Python世界裏的框架已經夠多了，後來發現相比golang簡直小巫見大巫。golang提供的net/http庫已經很好了，對於http的協議的實現非常好，基於此再造框架，也不會是難事，因此生態中出現了很多框架。既然構造框架的門檻變低了，那麽低門檻同樣也會帶來質量參差不齊的框架。
考察了幾個框架，通過其github的活躍度，維護的team，以及生產環境中的使用率。發現Gin還是一個可以學習的輕巧框架。
Gin
Gin是一個golang的微框架，封裝比較優雅，API友好，源碼註釋比較明確，已經發布了1.0版本。具有快速靈活，容錯方便等特點。其實對於golang而言，web框架的依賴要遠比Python，Java之類的要小。自身的net/http足夠簡單，性能也非常不錯。框架更像是一些常用函數或者工具的集合。借助框架開發，不僅可以省去很多常用的封裝帶來的時間，也有助於團隊的編碼風格和形成規範。
下面就Gin的用法做一個簡單的介紹。
首先需要安裝，安裝比較簡單，使用go get即可
go get gopkg.in/gin-gonic/gin.v1
gin的版本托管再 gopkg的網站上。我在安裝的過程中，gokpg卡住了，後來不得不根據gin裏的godep的文件，把響應的源碼從github上下載，然後copy到對應的目錄。
關於golang的包管理和依賴，我們以後再討論。
Hello World
使用Gin實現Hello world非常簡單，創建一個router，然後使用其Run的方法：
import (
"gopkg.in/gin-gonic/gin.v1" "net/http"
)
func main(){
router := gin.Default()
router.GET("/", func(c *gin.Context) {
c.String(http.StatusOK, "Hello World")
})
router.Run(":8000") }
簡單幾行代碼，就能實現一個web服務。使用gin的Default方法創建一個路由handler。然後通過HTTP方法綁定路由規則和路由函數。不同於net/http庫的路由函數，gin進行了封裝，把request和response都封裝到gin.Context的上下文環境。最後是啟動路由的Run方法監聽端口。麻雀雖小，五臟俱全。當然，除了GET方法，gin也支持POST,PUT,DELETE,OPTION等常用的restful方法。
restful路由
gin的路由來自httprouter庫。因此httprouter具有的功能，gin也具有，不過gin不支持路由正則表達式：
func main(){
router := gin.Default()
router.GET("/user/:name", func(c *gin.Context)
{
name := c.Param("name")
c.String(http.StatusOK, "Hello %s", name)
}
)
}
冒號:加上一個參數名組成路由參數。可以使用c.Params的方法讀取其值。當然這個值是字串string。諸如/user/rsj217，和/user/hello都可以匹配，而/user/和/user/rsj217/不會被匹配。
? ~ curl http://127.0.0.1:8000/user/rsj217 Hello rsj217% ? ~ curl http://127.0.0.1:8000/user/rsj217/ 404 page not found% ? ~ curl http://127.0.0.1:8000/user/ 404 page not found%
除了:，gin還提供了*號處理參數，*號能匹配的規則就更多。
func main(){
router := gin.Default()
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)
}
}
}
訪問效果如下：
? ~ curl http://127.0.0.1:8000/user/rsj217/
rsj217 is /% ? ~ curl http://127.0.0.1:8000/user/rsj217/中國
rsj217 is /中國%
query string參數與body參數
web提供的服務通常是client和server的交互。其中客戶端向服務器發送請求，除了路由參數，其他的參數無非兩種，查詢字符串query string和報文體body參數。所謂query string，即路由用，用?以後連接的key1=value2&key2=value2的形式的參數。當然這個key-value是經過urlencode編碼。
query string
對於參數的處理，經常會出現參數不存在的情況，對於是否提供默認值，gin也考慮了，並且給出了一個優雅的方案：
func main(){
router := gin.Default()
router.GET("/welcome", func(c *gin.Context) {
firstname := c.DefaultQuery("firstname", "Guest")
lastname := c.Query("lastname")
c.String(http.StatusOK, "Hello %s %s", firstname, lastname)
})
router.Run() }
使用c.DefaultQuery方法讀取參數，其中當參數不存在的時候，提供一個默認值。使用Query方法讀取正常參數，當參數不存在的時候，返回空字串：
? ~ curl http://127.0.0.1:8000/welcome Hello Guest % ? ~ curl http://127.0.0.1:8000/welcome\?firstname\=中國 Hello 中國 % ? ~ curl http://127.0.0.1:8000/welcome\?firstname\=中國\&lastname\=天朝 Hello 中國 天朝% ? ~ curl http://127.0.0.1:8000/welcome\?firstname\=\&lastname\=天朝 Hello 天朝% ? ~ curl http://127.0.0.1:8000/welcome\?firstname\=%E4%B8%AD%E5%9B%BD Hello 中國 %之所以使用中文，是為了說明urlencode。註意，當firstname為空字串的時候，並不會使用默認的Guest值，空值也是值，DefaultQuery只作用於key不存在的時候，提供默認值。
body
http的報文體傳輸數據就比query string稍微復雜一點，常見的格式就有四種。例如application/json，application/x-www-form-urlencoded, application/xml和multipart/form-data。後面一個主要用於圖片上傳。json格式的很好理解，urlencode其實也不難，無非就是把query string的內容，放到了body體裏，同樣也需要urlencode。默認情況下，c.PostFROM解析的是x-www-form-urlencoded或from-data的參數。
func main(){
router := gin.Default()
router.POST("/form_post", func(c *gin.Context) {
message := c.PostForm("message")
nick := c.DefaultPostForm("nick", "anonymous")
c.JSON(http.StatusOK, gin.H{ "status": gin.H{ "status_code":
http.StatusOK, "status": "ok", }, "message": message, "nick": nick,
})
})
}
與get處理query參數一樣，post方法也提供了處理默認參數的情況。同理，如果參數不存在，將會得到空字串。
? ~ curl -X POST http://127.0.0.1:8000/form_post -H "Content-Type:application/x-www-form-urlencoded" -d "message=hello&nick=rsj217" | python -m json.tool % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 104 100 79 100 25 48555 15365 --:--:-- --:--:-- --:--:-- 79000
{ "message": "hello",
"nick": "rsj217",
"status": { "status": "ok", "status_code": 200 } }
前面我們使用c.String返回響應，顧名思義則返回string類型。content-type是plain或者text。調用c.JSON則返回json數據。其中gin.H封裝了生成json的方式，是一個強大的工具。使用golang可以像動態語言一樣寫字面量的json，對於嵌套json的實現，嵌套gin.H即可。
發送數據給服務端，並不是post方法才行，put方法一樣也可以。同時querystring和body也不是分開的，兩個同時發送也可以：
func main(){
router := gin.Default()
router.PUT("/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 \n", id, page, name, message)
c.JSON(http.StatusOK, gin.H{
"status_code": http.StatusOK,
})
})
}
上面的例子，展示了同時使用查詢字串和body參數發送數據給服務器。
文件上傳
上傳單個文件
前面介紹了基本的發送數據，其中multipart/form-data轉用於文件上傳。gin文件上傳也很方便，和原生的net/http方法類似，不同在於gin把原生的request封裝到c.Request中了。
func main(){
router := gin.Default()
router.POST("/upload", func(c *gin.Context) {
name := c.PostForm("name")
fmt.Println(name)
file, header, err := c.Request.FormFile("upload")
if err != nil {
c.String(http.StatusBadRequest, "Bad request")
return
}
filename := header.Filename
fmt.Println(file, err, filename)
out, err := os.Create(filename)
if err != nil {
log.Fatal(err)
}
defer out.Close()
_, err = io.Copy(out, file)
if err != nil {
log.Fatal(err)
}
c.String(http.StatusCreated, "upload successful")
})
router.Run(":8000")
}
使用c.Request.FormFile解析客戶端文件name屬性。如果不傳文件，則會拋錯，因此需要處理這個錯誤。一種方式是直接返回。然後使用os的操作，把文件數據復制到硬盤上。
使用下面的命令可以測試上傳，註意upload為c.Request.FormFile指定的參數，其值必須要是絕對路徑：
curl -X POST http://127.0.0.1:8000/upload -F "upload=@/Users/ghost/Desktop/pic.jpg" -H "Content-Type: multipart/form-data"
上傳多個文件
單個文件上傳很簡單，別以為多個文件就會很麻煩。依葫蘆畫瓢，所謂多個文件，無非就是多一次遍歷文件，然後一次copy數據存儲即可。下面只寫handler，省略main函數的初始化路由和開啟服務器監聽了：
router.POST("/multi/upload", func(c *gin.Context) {
err := c.Request.ParseMultipartForm(200000)
if err != nil {
log.Fatal(err)
}
formdata := c.Request.MultipartForm
files := formdata.File["upload"]
for i, _ := range files { /
file, err := files[i].Open()
defer file.Close()
if err != nil {
log.Fatal(err)
}
out, err := os.Create(files[i].Filename)
defer out.Close()
if err != nil {
log.Fatal(err)
}
_, err = io.Copy(out, file)
if err != nil {
log.Fatal(err)
}
c.String(http.StatusCreated, "upload successful")
}
})
與單個文件上傳類似，只不過使用了c.Request.MultipartForm得到文件句柄，再獲取文件數據，然後遍歷讀寫。
使用curl上傳
curl -X POST http://127.0.0.1:8000/multi/upload -F "upload=@/Users/ghost/Desktop/pic.jpg" -F "upload=@
表單上傳
上面我們使用的都是curl上傳，實際上，用戶上傳圖片更多是通過表單，或者ajax和一些requests的請求完成。下面展示一下web的form表單如何上傳。
我們先要寫一個表單頁面，因此需要引入gin如何render模板。前面我們見識了c.String和c.JSON。下面就來看看c.HTML方法。
首先需要定義一個模板的文件夾。然後調用c.HTML渲染模板，可以通過gin.H給模板傳值。至此，無論是String，JSON還是HTML，以及後面的XML和YAML，都可以看到Gin封裝的接口簡明易用。
創建一個文件夾templates，然後再裏面創建html文件upload.html:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>upload</title>
</head>
<body>
<h3>Single Upload</h3>
<form action="/upload", method="post" enctype="multipart/form-data">
<input type="text" value="hello gin" />
<input type="file" name="upload" />
<input type="submit" value="upload" />
</form>
<h3>Multi Upload</h3>
<form action="/multi/upload", method="post" enctype="multipart/form-data">
<input type="text" value="hello gin" />
<input type="file" name="upload" />
<input type="file" name="upload" />
<input type="submit" value="upload" />
</form>
</body>
</html>
upload 很簡單，沒有參數。一個用於單個文件上傳，一個用於多個文件上傳。
router.LoadHTMLGlob("templates/*")
router.GET("/upload", func(c *gin.Context) {
c.HTML(http.StatusOK, "upload.html", gin.H{})
})
使用LoadHTMLGlob定義模板文件路徑。
參數綁定
我們已經見識了x-www-form-urlencoded類型的參數處理，現在越來越多的應用習慣使用JSON來通信，也就是無論返回的response還是提交的request，其content-type類型都是application/json的格式。而對於一些舊的web表單頁還是x-www-form-urlencoded的形式，這就需要我們的服務器能改hold住這多種content-type的參數了。
Python的世界裏很好解決，畢竟動態語言不需要實現定義數據模型。因此可以寫一個裝飾器將兩個格式的數據封裝成一個數據模型。golang中要處理並非易事，好在有gin，他們的model bind功能非常強大。
type User struct {
Username string `form:"username" json:"username" binding:"required"`
Passwd string `form:"passwd" json:"passwd" bdinding:"required"`
Age int `form:"age" json:"age"`
}
func main(){
router := gin.Default()
router.POST("/login", func(c *gin.Context) {
var user User
var err error
contentType := c.Request.Header.Get("Content-Type")
switch contentType {
case "application/json":
err = c.BindJSON(&user)
case "application/x-www-form-urlencoded":
err = c.BindWith(&user, binding.Form)
}
if err != nil {
fmt.Println(err)
log.Fatal(err)
}
c.JSON(http.StatusOK, gin.H{
"user": user.Username,
"passwd": user.Passwd,
"age": user.Age,
})
})
}
先定義一個User模型結構體，然後針對客戶端的content-type，一次使BindJSON和BindWith方法。
? ~ curl -X POST http://127.0.0.1:8000/login -H "Content-Type:application/x-www-form-urlencoded" -d "username=rsj217&passwd=123&age=21" | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 79 100 46 100 33 41181 29543 --:--:-- --:--:-- --:--:-- 46000
{
"age": 21,
"passwd": "123",
"username": "rsj217"
}
? ~ curl -X POST http://127.0.0.1:8000/login -H "Content-Type:application/x-www-form-urlencoded" -d "username=rsj217&passwd=123&new=21" | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 78 100 45 100 33 37751 27684 --:--:-- --:--:-- --:--:-- 45000
{
"age": 0,
"passwd": "123",
"username": "rsj217"
}
? ~ curl -X POST http://127.0.0.1:8000/login -H "Content-Type:application/x-www-form-urlencoded" -d "username=rsj217&new=21" | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0curl: (52) Empty reply from server
No JSON object could be decoded
可以看到，結構體中，設置了binding標簽的字段（username和passwd），如果沒傳會拋錯誤。非banding的字段（age），對於客戶端沒有傳，User結構會用零值填充。對於User結構沒有的參數，會自動被忽略。
改成json的效果類似：
? ~ curl -X POST http://127.0.0.1:8000/login -H "Content-Type:application/json" -d ‘{"username": "rsj217", "passwd": "123", "age": 21}‘ | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 96 100 46 100 50 32670 35511 --:--:-- --:--:-- --:--:-- 50000
{
"age": 21,
"passwd": "123",
"username": "rsj217"
}
? ~ curl -X POST http://127.0.0.1:8000/login -H "Content-Type:application/json" -d ‘{"username": "rsj217", "passwd": "123", "new": 21}‘ | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
100 95 100 45 100 50 49559 55066 --:--:-- --:--:-- --:--:-- 50000
{
"age": 0,
"passwd": "123",
"username": "rsj217"
}
? ~ curl -X POST http://127.0.0.1:8000/login -H "Content-Type:application/json" -d ‘{"username": "rsj217", "new": 21}‘ | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0curl: (52) Empty reply from server
No JSON object could be decoded
? ~ curl -X POST http://127.0.0.1:8000/login -H "Content-Type:application/json" -d ‘{"username": "rsj217", "passwd": 123, "new": 21}‘ | python -m json.tool
% Total % Received % Xferd Average Speed Time Time Time Current
Dload Upload Total Spent Left Speed
0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0curl: (52) Empty reply from server
No JSON object could be decoded
使用json還需要註意一點，json是有數據類型的，因此對於 {"passwd": "123"} 和 {"passwd": 123}是不同的數據類型，解析需要符合對應的數據類型,否則會出錯。
當然，gin還提供了更加高級方法，c.Bind，它會更加content-type自動推斷是bind表單還是json的參數。
router.POST("/login", func(c *gin.Context) {
var user User
err := c.Bind(&user)
if err != nil {
fmt.Println(err)
log.Fatal(err)
}
c.JSON(http.StatusOK, gin.H{
"username": user.Username,
"passwd": user.Passwd,
"age": user.Age,
})
})
多格式渲染
既然請求可以使用不同的content-type，響應也如此。通常響應會有html，text，plain，json和xml等。
gin提供了很優雅的渲染方法。到目前為止，我們已經見識了c.String， c.JSON，c.HTML，下面介紹一下c.XML。
router.GET("/render", func(c *gin.Context) {
contentType := c.DefaultQuery("content_type", "json")
if contentType == "json" {
c.JSON(http.StatusOK, gin.H{
"user": "rsj217",
"passwd": "123",
})
} else if contentType == "xml" {
c.XML(http.StatusOK, gin.H{
"user": "rsj217",
"passwd": "123",
})
}
})
結果如下：
? ~ curl http://127.0.0.1:8000/render\?content_type\=json
{"passwd":"123","user":"rsj217"}
? ~ curl http://127.0.0.1:8000/render\?content_type\=xml
<map><user>rsj217</user><passwd>123</passwd></map>%
重定向
gin對於重定向的請求，相當簡單。調用上下文的Redirect方法：
router.GET("/redict/google", func(c *gin.Context) {
c.Redirect(http.StatusMovedPermanently, "https://google.com")
})
分組路由
熟悉Flask的同學應該很了解藍圖分組。Flask提供了藍圖用於管理組織分組api。gin也提供了這樣的功能，讓你的代碼邏輯更加模塊化，同時分組也易於定義中間件的使用範圍。
v1 := router.Group("/v1")
v1.GET("/login", func(c *gin.Context) {
c.String(http.StatusOK, "v1 login")
})
v2 := router.Group("/v2")
v2.GET("/login", func(c *gin.Context) {
c.String(http.StatusOK, "v2 login")
})
訪問效果如下：
? ~ curl http://127.0.0.1:8000/v1/login v1 login% ? ~ curl http://127.0.0.1:8000/v2/login v2 login%
middleware中間件
golang的net/http設計的一大特點就是特別容易構建中間件。gin也提供了類似的中間件。需要註意的是中間件只對註冊過的路由函數起作用。對於分組路由，嵌套使用中間件，可以限定中間件的作用範圍。中間件分為全局中間件，單個路由中間件和群組中間件。
全局中間件
先定義一個中間件函數：
func MiddleWare() gin.HandlerFunc {
return func(c *gin.Context) {
fmt.Println("before middleware")
c.Set("request", "clinet_request")
c.Next()
fmt.Println("before middleware")
}
}
該函數很簡單，只會給c上下文添加一個屬性，並賦值。後面的路由處理器，可以根據被中間件裝飾後提取其值。需要註意，雖然名為全局中間件，只要註冊中間件的過程之前設置的路由，將不會受註冊的中間件所影響。只有註冊了中間件一下代碼的路由函數規則，才會被中間件裝飾。
router.Use(MiddleWare())
{
router.GET("/middleware", func(c *gin.Context) {
request := c.MustGet("request").(string)
req, _ := c.Get("request")
c.JSON(http.StatusOK, gin.H{
"middile_request": request,
"request": req,
})
})
}
使用router裝飾中間件，然後在/middlerware即可讀取request的值，註意在router.Use(MiddleWare())代碼以上的路由函數，將不會有被中間件裝飾的效果。使用花括號包含被裝飾的路由函數只是一個代碼規範，即使沒有被包含在內的路由函數，只要使用router進行路由，都等於被裝飾了。想要區分權限範圍，可以使用組返回的對象註冊中間件。
? ~ curl http://127.0.0.1:8000/middleware
{"middile_request":"clinet_request","request":"clinet_request"}
如果沒有註冊就使用MustGet方法讀取c的值將會拋錯，可以使用Get方法取而代之。
上面的註冊裝飾方式，會讓所有下面所寫的代碼都默認使用了router的註冊過的中間件。
單個路由中間件
當然，gin也提供了針對指定的路由函數進行註冊。
router.GET("/before", MiddleWare(), func(c *gin.Context) {
request := c.MustGet("request").(string)
c.JSON(http.StatusOK, gin.H{
"middile_request": request,
})
})
把上述代碼寫在 router.Use(Middleware())之前，同樣也能看見/before被裝飾了中間件。
群組中間件
群組的中間件也類似，只要在對於的群組路由上註冊中間件函數即可：
authorized := router.Group("/", MyMiddelware())
// 或者這樣用：
authorized := router.Group("/")
authorized.Use(MyMiddelware())
{
authorized.POST("/login", loginEndpoint)
}
群組可以嵌套，因為中間件也可以根據群組的嵌套規則嵌套。
中間件實踐
中間件最大的作用，莫過於用於一些記錄log，錯誤handler，還有就是對部分接口的鑒權。下面就實現一個簡易的鑒權中間件。
View Code
登錄函數會設置一個session_id的cookie，註意這裏需要指定path為/，不然gin會自動設置cookie的path為/auth，一個特別奇怪的問題。/homne的邏輯很簡單，使用中間件AuthMiddleWare註冊之後，將會先執行AuthMiddleWare的邏輯，然後才到/home的邏輯。
AuthMiddleWare的代碼如下：
View Code
從上下文的請求中讀取cookie，然後校對cookie，如果有問題，則終止請求，直接返回，這裏使用了c.Abort()方法。
View Code
異步協程
golang的高並發一大利器就是協程。gin裏可以借助協程實現異步任務。因為涉及異步過程，請求的上下文需要copy到異步的上下文，並且這個上下文是只讀的。
router.GET("/sync", func(c *gin.Context) {
time.Sleep(5 * time.Second)
log.Println("Done! in path" + c.Request.URL.Path)
})
router.GET("/async", func(c *gin.Context) {
cCp := c.Copy()
go func() {
time.Sleep(5 * time.Second)
log.Println("Done! in path" + cCp.Request.URL.Path)
}()
})
在請求的時候，sleep5秒鐘，同步的邏輯可以看到，服務的進程睡眠了。異步的邏輯則看到響應返回了，然後程序還在後臺的協程處理。
自定義router
gin不僅可以使用框架本身的router進行Run，也可以配合使用net/http本身的功能：
func main() {
router := gin.Default()
http.ListenAndServe(":8080", router)
}
或者
func main() {
router := gin.Default()
s := &http.Server{
Addr: ":8000",
Handler: router,
ReadTimeout: 10 * time.Second,
WriteTimeout: 10 * time.Second,
MaxHeaderBytes: 1 << 20,
}
s.ListenAndServe()
}
當然還有一個優雅的重啟和結束進程的方案。後面將會探索使用supervisor管理golang的進程。
總結
Gin是一個輕巧而強大的golang web框架。涉及常見開發的功能，我們都做了簡單的介紹。關於服務的啟動，請求參數的處理和響應格式的渲染，以及針對上傳和中間件鑒權做了例子。更好的掌握來自實踐，同時gin的源碼註釋很詳細，可以閱讀源碼了解更多詳細的功能和魔法特性。
作者：人世間
鏈接：http://www.jianshu.com/p/a31e4ee25305
來源：簡書
著作權歸作者所有。商業轉載請聯系作者獲得授權，非商業轉載請註明出處。
Golang 微框架 Gin 簡介