抱歉，您的浏览器无法访问本站
本页面需要浏览器支持（启用）JavaScript
了解详情 >

基于Golang的后端高性能框架 —— Gin

Programming

发布于：2023年2月27日

使用 Gin

使用 Gin 框架的基本方法可以展示为下面这段代码：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
func main() {

    r := gin.Default()

    serveRoute := func(c *gin.Context) {
        c.JSON(200, gin.H{
            "message": "hello world"
        })
    }

    r.GET("/hi", serveRoute)

    r.Run()
}

r是一个使用默认值实例化了的gin.Engine。该引擎用于管理所有HTTP请求，接受路由注册等。serveRoute是一个用于处理路由的函数，其参数必须为一个*gin.Context。接下来向引擎的特定请求和路由路径注册这个处理函数。最终，我们让引擎进行默认监听（局域网地址，8080端口）。这就启动了一个Web服务。

在内部，引擎对于每一个到来的请求分配一个对应的gin.Context，将这个上下文传入我们的自定义函数。在原理部分再详细展开相关内容。

路由组和动态路由

（还没写）

Middleware

（还没写）

Gin 原理 - Engine 部分

gin.Default()做了什么？我们参考一下Gin的源代码中的gin.go：

（有句吐槽不说不快，感觉这源代码目录结构也太随意了。而且同一个包下的不同文件实际上都是共享上下文的，导致某个文件里声明的类型大概率是另一个文件里的某处冒出来的，如果不用IDE看源代码真是头大）

1
2
3
4
5
6
7
// Default returns an Engine instance with the Logger and Recovery middleware already attached.
func Default() *Engine {
        debugPrintWARNINGDefault()
        engine := New()
        engine.Use(Logger(), Recovery())
        return engine
}

实际上其使用了New()，并默认使用了两个中间件Logger(), Recovery()。那我们紧接着去看New()的实现：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
func New() *Engine {
        debugPrintWARNINGNew()
        engine := &Engine{
                RouterGroup: RouterGroup{
                        Handlers: nil,
                        basePath: "/",
                        root:     true,
                },
                FuncMap:                template.FuncMap{},
                RedirectTrailingSlash:  true,
                RedirectFixedPath:      false,
                HandleMethodNotAllowed: false,
                ForwardedByClientIP:    true,
                AppEngine:              defaultAppEngine,
                UseRawPath:             false,
                UnescapePathValues:     true,
                MaxMultipartMemory:     defaultMultipartMemory,
                trees:                  make(methodTrees, 0, 9),
                delims:                 render.Delims{Left: "{{", Right: "}}"},
                secureJsonPrefix:       "while(1);",
        }
        engine.RouterGroup.engine = engine
        engine.pool.New = func() interface{} {
                return engine.allocateContext()
        }
        return engine
}

我们先不考虑默认引擎使用的中间件，而研究一下Run()方法是如何实现的：

1
2
3
4
5
6
7
8
func (engine *Engine) Run(addr ...string) (err error) {
        defer func() { debugPrintError(err) }()

        address := resolveAddress(addr)
        debugPrint("Listening and serving HTTP on %s\n", address)
        err = http.ListenAndServe(address, engine)
        return
}

使用了 net/http 的 ListenAndServe()。那么引擎必须实现 net/http 的接口 ServeHTTP。我们再回到源码里寻找一下：

1
2
3
4
5
6
7
8
9
10
func (engine *Engine) ServeHTTP(w http.ResponseWriter, req *http.Request) {
        c := engine.pool.Get().(*Context)
        c.writermem.reset(w)
        c.Request = req
        c.reset()

        engine.handleHTTPRequest(c)

        engine.pool.Put(c)
}

这个处理流程很明确了，首先从pool中获得一个gin.Context，给这个上下文赋值我们后面再看，放到handleHTTPRequest()里面，处理完毕之后再放回池子回收。那这个方法又具体做了些什么？

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
func (engine *Engine) handleHTTPRequest(c *Context) {
        httpMethod := c.Request.Method
        path := c.Request.URL.Path
        unescape := false
        if engine.UseRawPath && len(c.Request.URL.RawPath) > 0 {
                path = c.Request.URL.RawPath
                unescape = engine.UnescapePathValues
        }

        // Find root of the tree for the given HTTP method
        t := engine.trees
        for i, tl := 0, len(t); i < tl; i++ {
                if t[i].method == httpMethod {
                        root := t[i].root
                        // Find route in tree
                        handlers, params, tsr := root.getValue(path, c.Params, unescape)
                        if handlers != nil {
                                c.handlers = handlers
                                c.Params = params
                                c.Next()
                                c.writermem.WriteHeaderNow()
                                return
                        }
                        if httpMethod != "CONNECT" && path != "/" {
                                if tsr && engine.RedirectTrailingSlash {
                                        redirectTrailingSlash(c)
                                        return
                                }
                                if engine.RedirectFixedPath && redirectFixedPath(c, root, engine.RedirectFixedPath) {
                                        return
                                }
                        }
                        break
                }
        }

        if engine.HandleMethodNotAllowed {
                for _, tree := range engine.trees {
                        if tree.method != httpMethod {
                                if handlers, _, _ := tree.root.getValue(path, nil, unescape); handlers != nil {
                                        c.handlers = engine.allNoMethod
                                        serveError(c, 405, default405Body)
                                        return
                                }
                        }
                }
        }
        c.handlers = engine.allNoRoute
        serveError(c, 404, default404Body)
}

使用语法树进行匹配。核心逻辑是如果成功，那么去c.Next()。我们接下来有必要看看上下文的源代码了。

但在这之前，引擎结构体的成员还有些值得注意的点，我们浅浅分开看一看。

RouterGroup

显然这个是用来处理路由的，可以看到RouterGroup结构中存在着Handlers，这些应该就是中间件和处理方法存放的地方。看看routergroup.go中的定义：

1
2
3
4
5
6
7
8
// RouterGroup is used internally to configure router, a RouterGroup is associated with
// a prefix and an array of handlers (middleware).
type RouterGroup struct {
	Handlers HandlersChain
	basePath string
	engine   *Engine
	root     bool
}

上面的注释已经讲很清楚了，HandlersChain就是一个放着中间件的数组。basePath则是代表这个路由组的基础地址。在注册路由时，我们会传入新的相对地址。路由的实际地址是根据这两个地址的结合算出来的。

为什么要持有对引擎的引用？Use(),GET()等方法都调用了handle()这个没有暴露的方法，我们看一下这个方法的实现：

1
2
3
4
5
6
func (group *RouterGroup) handle(httpMethod, relativePath string, handlers HandlersChain) IRoutes {
	absolutePath := group.calculateAbsolutePath(relativePath)
	handlers = group.combineHandlers(handlers)
	group.engine.addRoute(httpMethod, absolutePath, handlers)
	return group.returnObj()
}

也就是说我们在当前路由组中注册了中间件，并引擎中注册了路径。非常合理。请注意注册路径的时候传递的参数，也就是http方法 / 绝对路径 / HandlersChain的值类型。那么我们可以猜到语法树存放的K-V逻辑是路径-方法列表。

关于返回值类型IRoutes我觉得也有必要看一看。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
// IRouter defines all router handle interface includes single and group router.
type IRouter interface {
	IRoutes
	Group(string, ...HandlerFunc) *RouterGroup
}

// IRoutes defines all router handle interface.
type IRoutes interface {
	Use(...HandlerFunc) IRoutes

	Handle(string, string, ...HandlerFunc) IRoutes
	Any(string, ...HandlerFunc) IRoutes
	GET(string, ...HandlerFunc) IRoutes
	POST(string, ...HandlerFunc) IRoutes
	DELETE(string, ...HandlerFunc) IRoutes
	PATCH(string, ...HandlerFunc) IRoutes
	PUT(string, ...HandlerFunc) IRoutes
	OPTIONS(string, ...HandlerFunc) IRoutes
	HEAD(string, ...HandlerFunc) IRoutes
	Match([]string, string, ...HandlerFunc) IRoutes

	StaticFile(string, string) IRoutes
	StaticFileFS(string, string, http.FileSystem) IRoutes
	Static(string, string) IRoutes
	StaticFS(string, http.FileSystem) IRoutes
}

没什么特别的，就是路由类型的接口。

trees

字典树，路由的处理就放在这里了。它的类型是methodTrees。我们转去tree.go看他的实现。

1
2
3
4
5
6
type methodTree struct {
	method string
	root   *node
}

type methodTrees []methodTree

结合之前引擎匹配路径的原理不难猜出，引擎实际上为每种不同的HTTP请求方式维护了一个Trie树。接下来就是这个数据结构的具体实现了。

(有空再写)

pool

此处使用了 Go 包 sync/pool实现了上下文池。这是一个为了减少GC而设计的对象池，其是可伸缩、线程安全的。它的目的是存放分配但暂时不用的对象，在需要的时候直接拿出来。我们现在只需要知道这些，具体的原理感觉之后需要详细了解一下sync包。

Gin 原理 - Context 部分

Context是Gin中的重要的一部分，它承担了在中间件间传递信息，控制流，验证JSON和快速返回请求的一些功能。这种设计方法也就是责任链模式的体现。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
type Context struct {
	writermem responseWriter
	Request   *http.Request
	Writer    ResponseWriter

	Params   Params
	handlers HandlersChain
	index    int8
	fullPath string

	engine       *Engine
	params       *Params
	skippedNodes *[]skippedNode

	// This mutex protects Keys map.
	mu sync.RWMutex

	// Keys is a key/value pair exclusively for the context of each request.
	Keys map[string]any

	// Errors is a list of errors attached to all the handlers/middlewares who used this context.
	Errors errorMsgs

	// Accepted defines a list of manually accepted formats for content negotiation.
	Accepted []string

	// queryCache caches the query result from c.Request.URL.Query().
	queryCache url.Values

	// formCache caches c.Request.PostForm, which contains the parsed form data from POST, PATCH,
	// or PUT body parameters.
	formCache url.Values

	// SameSite allows a server to define a cookie attribute making it impossible for
	// the browser to send this cookie along with cross-site requests.
	sameSite http.SameSite
}

其中的index和handlers就是Next()方法执行的关键。这个方法的实现很简单：

1
2
3
4
5
6
7
func (c *Context) Next() {
	c.index++
	for c.index < int8(len(c.handlers)) {
		c.handlers[c.index](c)
		c.index++
	}
}

让index在所有方法上不停的移动，并将自身传入对应的方法中进行执行。我们方法中常用的一些Context提供的功能可以浅浅看一看。

Set 和 Get

使用到了Context的RWMutex和Keys这两个参数。很简单地对map进行上锁，读取再解锁。可以预料到如果用这个的话应该会影响性能。但Golang的map实现要求必须上锁，否则必定fatal error。

BindXX 和 ShouldBindXX

（Gin终于舍得给binding单独写个Package了，但是代码好多，有空再看）

Abort

Abort的操作把index设置为abortIndex。这个行为一般在某个Handler末尾前执行，并让Context不执行接下来的handlers。也就是说你可以在某个中间件截断这次请求。那么abortIndex是啥呢？

1
2
// abortIndex represents a typical value used in abort functions.
const abortIndex int8 = math.MaxInt8 >> 1

再浅说一下怎么简单记忆位移运算符：

1
2
n << m (n times 2 for m times)
y >> x (y divided by 2 for x times)

更新于：2024年4月9日

Golang

后端

Gin

评论