Gin框架介紹及使用

阿新 • • 發佈：2020-12-29

Gin框架介紹及使用

Gin是一個用Go語言編寫的web框架。它是一個類似於martini但擁有更好效能的API框架, 由於使用了httprouter，速度提高了近40倍。如果你是效能和高效的追求者, 你會愛上Gin。

Gin框架介紹

Go世界裡最流行的Web框架，Github上有32K+star。基於httprouter開發的Web框架。中文文件齊全，簡單易用的輕量級框架。

Gin框架安裝與使用

安裝

下載並安裝Gin:

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

第一個Gin示例：

package main

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

func main() {
	// 建立一個預設的路由引擎
	r := gin.Default()
	// GET：請求方式；/hello：請求的路徑
	// 當客戶端以GET方法請求/hello路徑時，會執行後面的匿名函式
	r.GET("/hello", func(c *gin.Context) {
		// c.JSON：返回JSON格式的資料
		c.JSON(200, gin.H{
			"message": "Hello world!",
		})
	})
	// 啟動HTTP服務，預設在0.0.0.0:8080啟動服務
	r.Run()
}

將上面的程式碼儲存並編譯執行，然後使用瀏覽器開啟127.0.0.1:8080/hello就能看到一串JSON字串。

RESTful API

REST與技術無關，代表的是一種軟體架構風格，REST是Representational State Transfer的簡稱，中文翻譯為“表徵狀態轉移”或“表現層狀態轉化”。

推薦閱讀阮一峰理解RESTful架構

簡單來說，REST的含義就是客戶端與Web伺服器之間進行互動的時候，使用HTTP協議中的4個請求方法代表不同的動作。

GET用來獲取資源
POST用來新建資源
PUT用來更新資源
DELETE用來刪除資源。

只要API程式遵循了REST風格，那就可以稱其為RESTful API。目前在前後端分離的架構中，前後端基本都是通過RESTful API來進行互動。

例如，我們現在要編寫一個管理書籍的系統，我們可以查詢對一本書進行查詢、建立、更新和刪除等操作，我們在編寫程式的時候就要設計客戶端瀏覽器與我們Web服務端互動的方式和路徑。按照經驗我們通常會設計成如下模式：

請求方法	URL	含義
GET	/book	查詢書籍資訊
POST	/create_book	建立書籍記錄
POST	/update_book	更新書籍資訊
POST	/delete_book	刪除書籍資訊

同樣的需求我們按照RESTful API設計如下：

請求方法	URL	含義
GET	/book	查詢書籍資訊
POST	/book	建立書籍記錄
PUT	/book	更新書籍資訊
DELETE	/book	刪除書籍資訊

Gin框架支援開發RESTful API的開發。

func main() {
	r := gin.Default()
	r.GET("/book", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "GET",
		})
	})

	r.POST("/book", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "POST",
		})
	})

	r.PUT("/book", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "PUT",
		})
	})

	r.DELETE("/book", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "DELETE",
		})
	})
}

開發RESTful API的時候我們通常使用Postman來作為客戶端的測試工具。

Gin渲染

HTML渲染

我們首先定義一個存放模板檔案的templates資料夾，然後在其內部按照業務分別定義一個posts資料夾和一個users資料夾。 posts/index.html檔案的內容如下：

{{define "posts/index.html"}}
<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>posts/index</title>
</head>
<body>
    {{.title}}
</body>
</html>
{{end}}

users/index.html檔案的內容如下：

{{define "users/index.html"}}
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>users/index</title>
</head>
<body>
    {{.title}}
</body>
</html>
{{end}}

Gin框架中使用LoadHTMLGlob()或者LoadHTMLFiles()方法進行HTML模板渲染。

func main() {
	r := gin.Default()
	r.LoadHTMLGlob("templates/**/*")
	//r.LoadHTMLFiles("templates/posts/index.html", "templates/users/index.html")
	r.GET("/posts/index", func(c *gin.Context) {
		c.HTML(http.StatusOK, "posts/index.html", gin.H{
			"title": "posts/index",
		})
	})

	r.GET("users/index", func(c *gin.Context) {
		c.HTML(http.StatusOK, "users/index.html", gin.H{
			"title": "users/index",
		})
	})

	r.Run(":8080")
}

自定義模板函式

定義一個不轉義相應內容的safe模板函式如下：

func main() {
	router := gin.Default()
	router.SetFuncMap(template.FuncMap{
		"safe": func(str string) template.HTML{
			return template.HTML(str)
		},
	})
	router.LoadHTMLFiles("./index.tmpl")

	router.GET("/index", func(c *gin.Context) {
		c.HTML(http.StatusOK, "index.tmpl", "<a href='https://liwenzhou.com'>李文周的部落格</a>")
	})

	router.Run(":8080")
}

在index.tmpl中使用定義好的safe模板函式：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <title>修改模板引擎的識別符號</title>
</head>
<body>
<div>{{ . | safe }}</div>
</body>
</html>

靜態檔案處理

當我們渲染的HTML檔案中引用了靜態檔案時，我們只需要按照以下方式在渲染頁面前呼叫gin.Static方法即可。

func main() {
	r := gin.Default()
	r.Static("/static", "./static")
	r.LoadHTMLGlob("templates/**/*")
   // ...
	r.Run(":8080")
}

使用模板繼承

Gin框架預設都是使用單模板，如果需要使用block template功能，可以通過"github.com/gin-contrib/multitemplate"庫實現，具體示例如下：

首先，假設我們專案目錄下的templates資料夾下有以下模板檔案，其中home.tmpl和index.tmpl繼承了base.tmpl：

templates
├── includes
│   ├── home.tmpl
│   └── index.tmpl
├── layouts
│   └── base.tmpl
└── scripts.tmpl

然後我們定義一個loadTemplates函式如下：

func loadTemplates(templatesDir string) multitemplate.Renderer {
	r := multitemplate.NewRenderer()
	layouts, err := filepath.Glob(templatesDir + "/layouts/*.tmpl")
	if err != nil {
		panic(err.Error())
	}
	includes, err := filepath.Glob(templatesDir + "/includes/*.tmpl")
	if err != nil {
		panic(err.Error())
	}
	// 為layouts/和includes/目錄生成 templates map
	for _, include := range includes {
		layoutCopy := make([]string, len(layouts))
		copy(layoutCopy, layouts)
		files := append(layoutCopy, include)
		r.AddFromFiles(filepath.Base(include), files...)
	}
	return r
}

我們在main函式中

func indexFunc(c *gin.Context){
	c.HTML(http.StatusOK, "index.tmpl", nil)
}

func homeFunc(c *gin.Context){
	c.HTML(http.StatusOK, "home.tmpl", nil)
}

func main(){
	r := gin.Default()
	r.HTMLRender = loadTemplates("./templates")
	r.GET("/index", indexFunc)
	r.GET("/home", homeFunc)
	r.Run()
}

補充檔案路徑處理

關於模板檔案和靜態檔案的路徑，我們需要根據公司/專案的要求進行設定。可以使用下面的函式獲取當前執行程式的路徑。

func getCurrentPath() string {
	if ex, err := os.Executable(); err == nil {
		return filepath.Dir(ex)
	}
	return "./"
}

JSON渲染

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

	// gin.H 是map[string]interface{}的縮寫
	r.GET("/someJSON", func(c *gin.Context) {
		// 方式一：自己拼接JSON
		c.JSON(http.StatusOK, gin.H{"message": "Hello world!"})
	})
	r.GET("/moreJSON", func(c *gin.Context) {
		// 方法二：使用結構體
		var msg struct {
			Name    string `json:"user"`
			Message string
			Age     int
		}
		msg.Name = "小王子"
		msg.Message = "Hello world!"
		msg.Age = 18
		c.JSON(http.StatusOK, msg)
	})
	r.Run(":8080")
}

XML渲染

注意需要使用具名的結構體型別。

func main() {
	r := gin.Default()
	// gin.H 是map[string]interface{}的縮寫
	r.GET("/someXML", func(c *gin.Context) {
		// 方式一：自己拼接JSON
		c.XML(http.StatusOK, gin.H{"message": "Hello world!"})
	})
	r.GET("/moreXML", func(c *gin.Context) {
		// 方法二：使用結構體
		type MessageRecord struct {
			Name    string
			Message string
			Age     int
		}
		var msg MessageRecord
		msg.Name = "小王子"
		msg.Message = "Hello world!"
		msg.Age = 18
		c.XML(http.StatusOK, msg)
	})
	r.Run(":8080")
}

YMAL渲染

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

protobuf渲染

r.GET("/someProtoBuf", func(c *gin.Context) {
	reps := []int64{int64(1), int64(2)}
	label := "test"
	// protobuf 的具體定義寫在 testdata/protoexample 檔案中。
	data := &protoexample.Test{
		Label: &label,
		Reps:  reps,
	}
	// 請注意，資料在響應中變為二進位制資料
	// 將輸出被 protoexample.Test protobuf 序列化了的資料
	c.ProtoBuf(http.StatusOK, data)
})

獲取引數

獲取querystring引數

querystring指的是URL中?後面攜帶的引數，例如：/user/search?username=小王子&address=沙河。獲取請求的querystring引數的方法如下：

func main() {
	//Default返回一個預設的路由引擎
	r := gin.Default()
	r.GET("/user/search", func(c *gin.Context) {
		username := c.DefaultQuery("username", "小王子")
		//username := c.Query("username")
		address := c.Query("address")
		//輸出json結果給呼叫方
		c.JSON(http.StatusOK, gin.H{
			"message":  "ok",
			"username": username,
			"address":  address,
		})
	})
	r.Run()
}

獲取form引數

請求的資料通過form表單來提交，例如向/user/search傳送一個POST請求，獲取請求資料的方式如下：

func main() {
	//Default返回一個預設的路由引擎
	r := gin.Default()
	r.POST("/user/search", func(c *gin.Context) {
		// DefaultPostForm取不到值時會返回指定的預設值
		//username := c.DefaultPostForm("username", "小王子")
		username := c.PostForm("username")
		address := c.PostForm("address")
		//輸出json結果給呼叫方
		c.JSON(http.StatusOK, gin.H{
			"message":  "ok",
			"username": username,
			"address":  address,
		})
	})
	r.Run(":8080")
}

獲取path引數

請求的引數通過URL路徑傳遞，例如：/user/search/小王子/沙河。獲取請求URL路徑中的引數的方式如下。

func main() {
	//Default返回一個預設的路由引擎
	r := gin.Default()
	r.GET("/user/search/:username/:address", func(c *gin.Context) {
		username := c.Param("username")
		address := c.Param("address")
		//輸出json結果給呼叫方
		c.JSON(http.StatusOK, gin.H{
			"message":  "ok",
			"username": username,
			"address":  address,
		})
	})

	r.Run(":8080")
}

引數繫結

為了能夠更方便的獲取請求相關引數，提高開發效率，我們可以基於請求的Content-Type識別請求資料型別並利用反射機制自動提取請求中QueryString、form表單、JSON、XML等引數到結構體中。下面的示例程式碼演示了.ShouldBind()強大的功能，它能夠基於請求自動提取JSON、form表單和QueryString型別的資料，並把值繫結到指定的結構體物件。

// Binding from JSON
type Login struct {
	User     string `form:"user" json:"user" binding:"required"`
	Password string `form:"password" json:"password" binding:"required"`
}

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

	// 繫結JSON的示例 ({"user": "q1mi", "password": "123456"})
	router.POST("/loginJSON", func(c *gin.Context) {
		var login Login

		if err := c.ShouldBind(&login); err == nil {
			fmt.Printf("login info:%#v\n", login)
			c.JSON(http.StatusOK, gin.H{
				"user":     login.User,
				"password": login.Password,
			})
		} else {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		}
	})

	// 繫結form表單示例 (user=q1mi&password=123456)
	router.POST("/loginForm", func(c *gin.Context) {
		var login Login
		// ShouldBind()會根據請求的Content-Type自行選擇繫結器
		if err := c.ShouldBind(&login); err == nil {
			c.JSON(http.StatusOK, gin.H{
				"user":     login.User,
				"password": login.Password,
			})
		} else {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		}
	})

	// 繫結QueryString示例 (/loginQuery?user=q1mi&password=123456)
	router.GET("/loginForm", func(c *gin.Context) {
		var login Login
		// ShouldBind()會根據請求的Content-Type自行選擇繫結器
		if err := c.ShouldBind(&login); err == nil {
			c.JSON(http.StatusOK, gin.H{
				"user":     login.User,
				"password": login.Password,
			})
		} else {
			c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
		}
	})

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

ShouldBind會按照下面的順序解析請求中的資料完成繫結：

如果是 GET 請求，只使用 Form 繫結引擎（query）。
如果是 POST 請求，首先檢查 content-type 是否為 JSON 或 XML，然後再使用 Form（form-data）。

檔案上傳

單個檔案上傳

檔案上傳前端頁面程式碼：

<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <title>上傳檔案示例</title>
</head>
<body>
<form action="/upload" method="post" enctype="multipart/form-data">
    <input type="file" name="f1">
    <input type="submit" value="上傳">
</form>
</body>
</html>

後端gin框架部分程式碼：

func main() {
	router := gin.Default()
	// 處理multipart forms提交檔案時預設的記憶體限制是32 MiB
	// 可以通過下面的方式修改
	// router.MaxMultipartMemory = 8 << 20  // 8 MiB
	router.POST("/upload", func(c *gin.Context) {
		// 單個檔案
		file, err := c.FormFile("f1")
		if err != nil {
			c.JSON(http.StatusInternalServerError, gin.H{
				"message": err.Error(),
			})
			return
		}

		log.Println(file.Filename)
		dst := fmt.Sprintf("C:/tmp/%s", file.Filename)
		// 上傳檔案到指定的目錄
		c.SaveUploadedFile(file, dst)
		c.JSON(http.StatusOK, gin.H{
			"message": fmt.Sprintf("'%s' uploaded!", file.Filename),
		})
	})
	router.Run()
}

多個檔案上傳

func main() {
	router := gin.Default()
	// 處理multipart forms提交檔案時預設的記憶體限制是32 MiB
	// 可以通過下面的方式修改
	// router.MaxMultipartMemory = 8 << 20  // 8 MiB
	router.POST("/upload", func(c *gin.Context) {
		// Multipart form
		form, _ := c.MultipartForm()
		files := form.File["file"]

		for index, file := range files {
			log.Println(file.Filename)
			dst := fmt.Sprintf("C:/tmp/%s_%d", file.Filename, index)
			// 上傳檔案到指定的目錄
			c.SaveUploadedFile(file, dst)
		}
		c.JSON(http.StatusOK, gin.H{
			"message": fmt.Sprintf("%d files uploaded!", len(files)),
		})
	})
	router.Run()
}

重定向

HTTP重定向

HTTP 重定向很容易。內部、外部重定向均支援。

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

路由重定向

路由重定向，使用HandleContext：

r.GET("/test", func(c *gin.Context) {
    // 指定重定向的URL
    c.Request.URL.Path = "/test2"
    r.HandleContext(c)
})
r.GET("/test2", func(c *gin.Context) {
    c.JSON(http.StatusOK, gin.H{"hello": "world"})
})

Gin路由

普通路由

r.GET("/index", func(c *gin.Context) {...})
r.GET("/login", func(c *gin.Context) {...})
r.POST("/login", func(c *gin.Context) {...})

此外，還有一個可以匹配所有請求方法的Any方法如下：

r.Any("/test", func(c *gin.Context) {...})

為沒有配置處理函式的路由新增處理程式，預設情況下它返回404程式碼，下面的程式碼為沒有匹配到路由的請求都返回views/404.html頁面。

r.NoRoute(func(c *gin.Context) {
		c.HTML(http.StatusNotFound, "views/404.html", nil)
	})

路由組

我們可以將擁有共同URL字首的路由劃分為一個路由組。習慣性一對{}包裹同組的路由，這只是為了看著清晰，你用不用{}包裹功能上沒什麼區別。

func main() {
	r := gin.Default()
	userGroup := r.Group("/user")
	{
		userGroup.GET("/index", func(c *gin.Context) {...})
		userGroup.GET("/login", func(c *gin.Context) {...})
		userGroup.POST("/login", func(c *gin.Context) {...})

	}
	shopGroup := r.Group("/shop")
	{
		shopGroup.GET("/index", func(c *gin.Context) {...})
		shopGroup.GET("/cart", func(c *gin.Context) {...})
		shopGroup.POST("/checkout", func(c *gin.Context) {...})
	}
	r.Run()
}

路由組也是支援巢狀的，例如：

shopGroup := r.Group("/shop")
	{
		shopGroup.GET("/index", func(c *gin.Context) {...})
		shopGroup.GET("/cart", func(c *gin.Context) {...})
		shopGroup.POST("/checkout", func(c *gin.Context) {...})
		// 巢狀路由組
		xx := shopGroup.Group("xx")
		xx.GET("/oo", func(c *gin.Context) {...})
	}

通常我們將路由分組用在劃分業務邏輯或劃分API版本時。

路由原理

Gin框架中的路由使用的是httprouter這個庫。

其基本原理就是構造一個路由地址的字首樹。

Gin中介軟體

Gin框架允許開發者在處理請求的過程中，加入使用者自己的鉤子（Hook）函式。這個鉤子函式就叫中介軟體，中介軟體適合處理一些公共的業務邏輯，比如登入認證、許可權校驗、資料分頁、記錄日誌、耗時統計等。

定義中介軟體

Gin中的中介軟體必須是一個gin.HandlerFunc型別。例如我們像下面的程式碼一樣定義一個統計請求耗時的中介軟體。

// StatCost 是一個統計耗時請求耗時的中介軟體
func StatCost() gin.HandlerFunc {
	return func(c *gin.Context) {
		start := time.Now()
		c.Set("name", "小王子") // 可以通過c.Set在請求上下文中設定值，後續的處理函式能夠取到該值
		// 呼叫該請求的剩餘處理程式
		c.Next()
		// 不呼叫該請求的剩餘處理程式
		// c.Abort()
		// 計算耗時
		cost := time.Since(start)
		log.Println(cost)
	}
}

註冊中介軟體

在gin框架中，我們可以為每個路由新增任意數量的中介軟體。

為全域性路由註冊

func main() {
	// 新建一個沒有任何預設中介軟體的路由
	r := gin.New()
	// 註冊一個全域性中介軟體
	r.Use(StatCost())
	
	r.GET("/test", func(c *gin.Context) {
		name := c.MustGet("name").(string) // 從上下文取值
		log.Println(name)
		c.JSON(http.StatusOK, gin.H{
			"message": "Hello world!",
		})
	})
	r.Run()
}

為某個路由單獨註冊

// 給/test2路由單獨註冊中介軟體（可註冊多個）
	r.GET("/test2", StatCost(), func(c *gin.Context) {
		name := c.MustGet("name").(string) // 從上下文取值
		log.Println(name)
		c.JSON(http.StatusOK, gin.H{
			"message": "Hello world!",
		})
	})

為路由組註冊中介軟體

為路由組註冊中介軟體有以下兩種寫法。

寫法1：

shopGroup := r.Group("/shop", StatCost())
{
    shopGroup.GET("/index", func(c *gin.Context) {...})
    ...
}

寫法2：

shopGroup := r.Group("/shop")
shopGroup.Use(StatCost())
{
    shopGroup.GET("/index", func(c *gin.Context) {...})
    ...
}

中介軟體注意事項

gin預設中介軟體

gin.Default()預設使用了Logger和Recovery中介軟體，其中：

Logger中介軟體將日誌寫入gin.DefaultWriter，即使配置了GIN_MODE=release。
Recovery中介軟體會recover任何panic。如果有panic的話，會寫入500響應碼。

如果不想使用上面兩個預設的中介軟體，可以使用gin.New()新建一個沒有任何預設中介軟體的路由。

gin中介軟體中使用goroutine

當在中介軟體或handler中啟動新的goroutine時，不能使用原始的上下文（c *gin.Context），必須使用其只讀副本（c.Copy()）。

執行多個服務

我們可以在多個埠啟動服務，例如：

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,
	}
   // 藉助errgroup.Group或者自行開啟兩個goroutine分別啟動兩個服務
	g.Go(func() error {
		return server01.ListenAndServe()
	})

	g.Go(func() error {
		return server02.ListenAndServe()
	})

	if err := g.Wait(); err != nil {
		log.Fatal(err)
	}
}

Gin框架介紹及使用

Gin框架介紹及使用

Gin框架介紹

Gin框架安裝與使用

安裝

第一個Gin示例：

RESTful API

Gin渲染

HTML渲染

自定義模板函式

靜態檔案處理

使用模板繼承

補充檔案路徑處理

JSON渲染

XML渲染

YMAL渲染

protobuf渲染

獲取引數

獲取querystring引數

獲取form引數

獲取path引數

引數繫結

檔案上傳

單個檔案上傳

多個檔案上傳

重定向

HTTP重定向

路由重定向

Gin路由

普通路由

路由組

路由原理

Gin中介軟體

定義中介軟體

註冊中介軟體

為全域性路由註冊

為某個路由單獨註冊

為路由組註冊中介軟體

中介軟體注意事項

gin預設中介軟體

gin中介軟體中使用goroutine

執行多個服務

相關推薦