深入浅出 Gin 生命周期

本文首发于 深入浅出 Gin 生命周期 转载请注明出处。

Gin 是一个用 Go (Golang) 编写的 web 框架，由于出色的性能优势而被广泛使用，这里我们就来分析下 Gin 的请求生命周期

1 Gin 目录结构

先来了解下其目录结构：

.
├── binding 依据 HTTP 请求 Accept 解析响应数据格式
│   ├── binding.go
│   ├── binding_nomsgpack.go
│   ├── default_validator.go
│   ├── form.go
│   ├── form_mapping.go
│   ├── header.go
│   ├── json.go
│   ├── msgpack.go
│   ├── multipart_form_mapping.go
│   ├── protobuf.go
│   ├── query.go
│   ├── uri.go
│   ├── xml.go
│   ├── yaml.go
├── ginS
│   └── gins.go
├── internal
│   ├── bytesconv
│   │   ├── bytesconv.go
│   └── json
│       ├── json.go
│       └── jsoniter.go
├── render 依据解析的 HTTP 请求 Accept 响应格式生成响应
│   ├── data.go
│   ├── html.go
│   ├── json.go
│   ├── msgpack.go
│   ├── protobuf.go
│   ├── reader.go
│   ├── redirect.go
│   ├── render.go
│   ├── text.go
│   ├── xml.go
│   └── yaml.go
├── auth.go
├── *context.go
├── context_appengine.go
├── debug.go
├── deprecated.go
├── errors.go
├── fs.go
├── *gin.go
├── logger.go
├── mode.go 设置 Gin 运行环境模式
├── path.go Path 处理
├── recovery.go 处理 Panic 的 Recovery 中间件
├── *response_writer.go ResponseWriter
├── *routergroup.go 路由组设置
├── tree.go 路由算法
├── utils.go helper 函数
└── version.go

其中比较重要的模块为： context.go，gin.go，routergroup.go，以及 tree.go；分别处理 HTTP 请求及响应上下文，gin 引擎初始化，路由注册及路由查找算法实现。

binding 目录内提供基于 HTTP 请求消息头 Context-Type 的 MIME 信息自动解析功能，相对应的 Render 目录下提供具体数据格式渲染的实现方法。

2 Gin 请求生命周期

本文着重介绍 Gin 实现一个 Web 服务器，从请求到达到生成响应整个生命周期内的核心功能点，这将有助于我们理解 Gin 的执行原理和以后的开发工作的展开。

2.1 简单了解下 Gin 服务执行流程

先从官网的第一个 demo example.go 出发：

package main

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

func main() {
    // 创建 Gin Engine 实例
    r := gin.Default()

    // 设置请求 URI /ping 的路由及响应处理函数
    r.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{
            "message": "pong",
        })
    })

    // 启动 Web 服务，监听端口,等待 HTTP 请求到并生成响应
    r.Run() // 监听并在 0.0.0.0:8080 上启动服务
}

通过执行 go run example.go 命令来运行代码，它会启动一个阻塞进程监听并等待 HTTP 请求：

# 运行 example.go 并且在浏览器中访问 0.0.0.0:8080/ping
$ go run example.go

从代码中我们可以看出通过 Gin 实现一个最简单的 Web 服务器，只需 3 个步骤：

1）创建 Gin 实例
2）注册路由及处理函数
3）启动 Web 服务

2.2 Gin 生命周期

2.2.1 创建 Gin 实例

Gin 实例创建通过 gin.Default() 方法完成，其定义在 gin.go#L159 文件里：

// 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
}

Default() 方法实现如下功能：
1）创建 Gin 框架对象 Engine
2）配置 Gin 默认的中间件，Logger() 和 Recovery()，其实现分别位于 logger.go 和 recovery.go 文件内
3）返回 Gin 框架对象

其中 New() 方法会实例化 Gin 的 Engine 对象，gin.go#L129

// New returns a new blank Engine instance without any middleware attached.
// By default the configuration is:
// - RedirectTrailingSlash:  true
// - RedirectFixedPath:      false
// - HandleMethodNotAllowed: false
// - ForwardedByClientIP:    true
// - UseRawPath:             false
// - UnescapePathValues:     true
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,
        RemoveExtraSlash:       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
}

实例化比较核心的功能是：
1）初始化 Engine 对象, 关键步骤是初始化路由组 RouterGroup。
2）初始化 pool, 这是核心步骤. pool 用来存储 context 上下文对象. 用来优化处理 http 请求时的性能。

后面会重点分析 engine.pool 的实现细节。

Engine 是 Gin 框架的核心引擎 gin.go#L56，数据结构如下：

type Engine struct {
    RouterGroup // 关键：路由组

    // 设置开关
    RedirectTrailingSlash bool
    RedirectFixedPath bool
    HandleMethodNotAllowed bool
    ForwardedByClientIP    bool
    
    AppEngine bool
    UseRawPath bool
    
    UnescapePathValues bool
    MaxMultipartMemory int64
    RemoveExtraSlash bool

    // 界定符
    delims           render.Delims
    secureJSONPrefix string
    HTMLRender       render.HTMLRender
    FuncMap          template.FuncMap
    allNoRoute       HandlersChain
    allNoMethod      HandlersChain
    noRoute          HandlersChain
    noMethod         HandlersChain
    
    pool             sync.Pool // 关键：context 处理
    
    trees            methodTrees
    maxParams        uint16
}

Engine 结构体内部除一些功能性开关设置外，核心的就是 RouterRroup，pool 和 trees。Gin 的所有组件都是由 Engine 驱动。

2.2.2 路由注册

完成 Gin 的实例化之后，我们可以通过 r.GET("/ping", func(c *gin.Context) {}) 定义 HTTP 路由及处理 handler 函数。

以 gin.GET 为例，展开源码如下：

// GET is a shortcut for router.Handle("GET", path, handle).
func (group *RouterGroup) GET(relativePath string, handlers ...HandlerFunc) IRoutes {
    return group.handle(http.MethodGet, relativePath, handlers)
}

gin.GET 定义 HTTP GET 请求的路由及处理方法，并返回 IRoutes 对象实例。

2.2.2.1 RouterGroup 结构体

// 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
}

RouterGroup routergroup.go#L41 用于配置路由，其中：

• Handlers 数组定义了 Gin 中间件调用的 handler 方法
• engine 为 gin.go 实例化时设置的 Engine 实例对象

2.2.2.2 handle 添加路由

在 gin.GET 方法内部通过调用 group.handle() routergroup.go#L72 方法添加路由：

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

路由就和 Engine 绑定好关系了。

2.2.2.3 IRoute 接口类型

// 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

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

IRoute 是个接口类型，定义了 router 所需的 handle 接口，RouterGroup 实现了这个接口。

2.2.2.4 小结

推而广之，Gin 还支持如下等路由注册方法：

• r.POST
• r.DELETE
• r.PATCH
• r.PUT
• r.OPTIONS
• r.HEAD
• 以及 r.Any

它们都定义在 routergroup.go 文件内。

2.2.3 接收请求并响应

Gin 实例化和路由设置后工作完成后，我们进入 Gin 生命周期执行的核心功能分析，Gin 究竟是如何启动 Web 服务，监听 HTTP 请求并执行 HTTP 请求处理函数生成响应的。这些工作统统从 gin.Run() 出发 gin.go#L305：

// Run attaches the router to a http.Server and starts listening and serving HTTP requests.
// It is a shortcut for http.ListenAndServe(addr, router)
// Note: this method will block the calling goroutine indefinitely unless an error happens.
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
}

gin.Run() 是 net/http 标准库 http.ListenAndServe(addr, router) 的简写，功能是将路由连接到 http.Server 启动并监听 HTTP 请求。

由此，我们不得不放下手头的工作，率先了解下 net/http 标准库的执行逻辑。

2.2.3.1 net/http 标准库

net/http 标准库的 ListenAndServe(addr string, handler Handler) 方法定义在 net/http/server.go#L3162 文件里。

• 参数签名的第一个参数是监听的服务地址和端口；
• 第二个参数接收一个 Handler 对象它是一个接口类型需要实现 ServeHTTP(ResponseWriter, *Request) 方法。

func ListenAndServe(addr string, handler Handler) error {
    server := &Server{Addr: addr, Handler: handler}
    return server.ListenAndServe()
}

在 ListenAndServe(addr string, handler Handler) 内部则调用的是 Server 对象的 ListenAndServe() 方法由交由它启动监听和服务功能：

// ListenAndServe listens on the TCP network address srv.Addr and then
// calls Serve to handle requests on incoming connections.
// Accepted connections are configured to enable TCP keep-alives.
//
// If srv.Addr is blank, ":http" is used.
//
// ListenAndServe always returns a non-nil error. After Shutdown or Close,
// the returned error is ErrServerClosed.
func (srv *Server) ListenAndServe() error {
    if srv.shuttingDown() {
        return ErrServerClosed
    }
    addr := srv.Addr
    if addr == "" {
        addr = ":http"
    }
    ln, err := net.Listen("tcp", addr)// 监听
    if err != nil {
        return err
    }
    return srv.Serve(ln)// 启动服务等待连接
}

然后，执行 srv.Serve(ln) 即 Server.Serve(l net.Listener) server.go#L2951，在 net.Listen("tcp", addr) 等待连接，创建新的 goroutine 来处理请求和生成响应的业务逻辑：

func (srv *Server) Serve(l net.Listener) error {
    ...
    for {
        rw, e := l.Accept()
        if e != nil {
            select {
            case <-srv.getDoneChan():
                return ErrServerClosed
            default:
            }
            ...
            return e
        }
        if cc := srv.ConnContext; cc != nil {
            ctx = cc(ctx, rw)
            if ctx == nil {
                panic("ConnContext returned nil")
            }
        }
        tempDelay = 0
        c := srv.newConn(rw)
        c.setState(c.rwc, StateNew) // before Serve can return
        go c.serve(ctx) // 启动 Web 服务
    }
}

最后，进入到 go c.serve(ctx) 启动 Web 服务，读取 HTTP 请求数据，生成响应 server.go#L1817：

// Serve a new connection.
func (c *conn) serve(ctx context.Context) {
    ...

    // HTTP/1.x from here on.
    for {
        w, err := c.readRequest(ctx)// 读取 HTTP 去请求

        ...

        // HTTP cannot have multiple simultaneous active requests.[*]
        // Until the server replies to this request, it can't read another,
        // so we might as well run the handler in this goroutine.
        // [*] Not strictly true: HTTP pipelining. We could let them all process
        // in parallel even if their responses need to be serialized.
        // But we're not going to implement HTTP pipelining because it
        // was never deployed in the wild and the answer is HTTP/2.
        serverHandler{c.server}.ServeHTTP(w, w.req)
        ...
    }
}

最终，调用 r.Run() 方法传入的 Engine 来执行 serverHandler{c.server}.ServeHTTP(w, w.req) 处理接收到的 HTTP 请求和生成响应，这里将响应处理的控制权交回给 Gin Engine。

小结

Go 标准库 net/http 提供了丰富的 Web 编程接口支持，感兴趣的朋友可以深入研究下 net/http 标准库源码，了解其实现细节。

2.2.3.2 Engine.ServeHTTP 处理 HTTP 请求

Engine.ServeHTTP 是 Gin 框架核心中的核心，我们来看下它是如何处理请求和响应的：

// ServeHTTP conforms to the http.Handler interface.
func (engine *Engine) ServeHTTP(w http.ResponseWriter, req *http.Request) {
    c := engine.pool.Get().(*Context) // 从临时对象池 pool 获取 context 上下文对象
    c.writermem.reset(w)
    c.Request = req
    c.reset()

    engine.handleHTTPRequest(c) // 处理 HTTP 请求

    engine.pool.Put(c) // 使用完 context 对象, 归还给 pool 
}

ServeHTTP会先获取 Gin Context 上下文信息，接着将 Context 注入到 engine.handleHTTPRequest(c) 方法内来处理 HTTP 请求：

func (engine *Engine) handleHTTPRequest(c *Context) {
    httpMethod := c.Request.Method
    rPath := c.Request.URL.Path

    ...

    // Find root of the tree for the given HTTP method
    t := engine.trees
    for i, tl := 0, len(t); i < tl; i++ {

        ...

        root := t[i].root
        // Find route in tree
        value := root.getValue(rPath, c.params, unescape)
        
        ...
        
        if value.handlers != nil {
            c.handlers = value.handlers
            c.fullPath = value.fullPath
            c.Next() // 具体执行响应处理
            c.writermem.WriteHeaderNow()
            return
        }
        if httpMethod != "CONNECT" && rPath != "/" {
            ...
        }
        break
    }

    ...
}

handleHTTPRequest 完成 路由 及 回调 方法的查找，执行 Gin.Context.Next() 调用处理响应。

2.2.3.3 Gin.Context.Next() 在内部中间件执行 handler 方法

Gin.Context.Next() 仅有数行代码：

// Next should be used only inside middleware.
// It executes the pending handlers in the chain inside the calling handler.
// See example in GitHub.
func (c *Context) Next() {
    c.index++
    for c.index < int8(len(c.handlers)) {
        c.handlers[c.index](c)
        c.index++
    }
}

功能是在 Gin 内部中间件中执行 handler 调用，即 r.GET() 中传入的

func(c *gin.Context) {
    c.JSON(200, gin.H{
        "message": "pong",
    })
}

方法生成 HTTP 响应。

到这里我们完成了 Gin 的请求和响应的完整流程的源码走读，但是我们有必要对 Gin.Context 有多一些的了解。

2.2.3.4 Gin.Context 上下文处理

Gin 的 Context 实现了对 request 和 response 的封装是 Gin 的核心实现之一，其数据结构如下：

// Context is the most important part of gin. It allows us to pass variables between middleware,
// manage the flow, validate the JSON of a request and render a JSON response for example.
type Context struct {
    writermem responseWriter

    Request   *http.Request    // HTTP 请求
    Writer    ResponseWriter   // HTTP 响应

    Params   Params
    handlers HandlersChain  // 关键: 数组: 内包含方法集合
    index    int8

    engine *Engine  // 关键: 引擎

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

    // 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
}

其包含了 Gin 请求及响应的上下文信息和 Engine 指针数据

• Request *http.Request : HTTP 请求
• Writer ResponseWriter : HTTP 响应
• handlers HandlersChain : 是 type HandlerFunc func(*Context) 方法集即路由设置的回调函数
• engine *Engine : gin框架对象

Gin 官方文档 几乎所有的示例都是在讲解 Context 的使用方法，可用说研究 Context 源码对用好 Gin 框架会起到只管重要的作用。

感兴趣的朋友可以自行阅读 Context.go

3 参考资料

• https://golang.org/pkg/net/http/
• https://www.haohongfan.com/po...
• https://github.com/hhstore/bl...
• https://draveness.me/golang/d...