Gin 源码学习（四）丨Gin 对请求的处理流程

在上一篇文章 Gin 源码学习（三）丨路由是如何构建和匹配的？ 中，讲解了 Gin 的路由是如何实现的，那么，当路由成功匹配后，或者匹配失败后，在 Gin 内部会对其如何处理呢？

在这一篇文章中，将讲解 Gin 对一个 HTTP 请求的具体处理流程是怎样的。

下面，将对一个请求进入 Gin 的处理范围后的内容，进行一步步展开，讲解 Gin 对请求的处理流程。

Go 版本：1.14

Gin 版本：v1.5.0

目录

• 请求的处理流程
• 小结

请求的处理流程

在上一篇文章中，我们讲到 Gin 其实实现了 Go 自带函数库 net/http 库中的 Handler 接口，并且从实现的源代码中可以发现，当一个 HTTP 请求到达 Gin 处理的范围时，首先是在 Gin 的 Engine 类型中的 ServeHTTP(w http.ResponseWriter, req *http.Request) 方法中对 Gin 保存上下文信息的 gin.Context 进行属性设置和重置操作，然后才是使用 engine.handleHTTPRequest(c *Context) 方法来对 HTTP 请求进行处理的，下面，我们一步一步来对相关源代码进行分析：

// ServeHTTP conforms to the http.Handler interface.
// 符合 http.Handler 接口的约定
func (engine *Engine) ServeHTTP(w http.ResponseWriter, req *http.Request) {
	// 从对象池中获取已存在的上下文对象
	c := engine.pool.Get().(*Context)
	// 重置该上下文对象的 ResponseWriter 属性
	c.writermem.reset(w)
	// 设置该上下文对象的 Request 属性
	c.Request = req
	// 重置上下文中的其他属性信息
	c.reset()

	// 对请求进行处理
	engine.handleHTTPRequest(c)

	// 将该上下文对象重新放回对象池中
	engine.pool.Put(c)
}

// 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.
// 上下文是 Gin 最重要的部分.
// 它允许我们在中间件之间传递变量, 管理流程, 例如验证请求的 JSON 并呈现 JSON 响应.
type Context struct {
	// 对 net/http 库中的 ResponseWriter 进行了封装
	writermem responseWriter
	// 请求对象
	Request   *http.Request
	// 非 net/http 库中的 ResponseWriter
	// 而是 Gin 用来构建 HTTP 响应的一个接口
	Writer    ResponseWriter

	// 存放请求中的 URI 参数
	Params   Params
	// 存放该请求的处理函数切片, 包括中间件加最终处理函数
	handlers HandlersChain
	// 用于标记当前执行的处理函数
	index    int8
	// 请求的完整路径
	fullPath string

	// Gin 引擎对象
	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

	// queryCache use url.ParseQuery cached the param query result from c.Request.URL.Query()
	// 用于缓存请求的 URL 参数
	queryCache url.Values

	// formCache use url.ParseQuery cached PostForm contains the parsed form data from POST, PATCH,
	// or PUT body parameters.
	// 用于缓存请求体中的参数
	formCache url.Values
}
复制代码

上面源代码中，展示了 engine.ServeHTTP(w http.ResponseWriter, req *http.Request) 方法的执行过程以及 gin.Context 类型的内部结构，需要注意的是， gin.Context 实现了 Go 的 Context 接口，但是并没有对其做并发安全处理，因此，应该避免多个 goroutine 同时访问同一个 Context，如果存在这种情况，需使用 gin.Context.Copy() 方法，对 gin.Context 进行复制使用。

并且，Gin 使用对象池来存放上下文信息，这是一个非常巧妙的设计思想，因为在 Gin 中，会将请求的许多处理信息存放于 gin.Context 中，而 Go 是一门带有 GC（垃圾回收）的语言，假如在访问量较大的场景下，如果不使用对象池来缓冲 gin.Context 对象的话，那么为每一个请求创建一个 gin.Context 对象，并且在完成请求的处理后，将该 gin.Context 对象交给 GC 去处理，这无疑对 GC 增添了许多压力。由于 gin.Context 只是用于保存当前请求的处理信息，用于上下文之间的参数传递，属于完全可以复用的对象，因此，使用对象池对其进行存放可以在一定程度上减少 GC 压力。

下面先来看一下在 engine.ServeHTTP(w http.ResponseWriter, req *http.Request) 方法中对 gin.Context 初始化时设置了什么样的初始值：

const (
	// 表示未写入
	noWritten     = -1
	// 200 状态码
	defaultStatus = http.StatusOK
)

type responseWriter struct {
	// net/http 库中的 ResponseWriter
	http.ResponseWriter
	// 响应内容大小
	size   int
	// 响应状态码
	status int
}

func (w *responseWriter) reset(writer http.ResponseWriter) {
	w.ResponseWriter = writer
	w.size = noWritten
	w.status = defaultStatus
}

func (c *Context) reset() {
	c.Writer = &c.writermem
	c.Params = c.Params[0:0]
	c.handlers = nil
	c.index = -1
	c.fullPath = ""
	c.Keys = nil
	c.Errors = c.Errors[0:0]
	c.Accepted = nil
	c.queryCache = nil
	c.formCache = nil
}
复制代码

这里需要留意的是 gin.Context.index 的初始值，Gin 通过该值来调用处理函数和判断当前上下文是否终止。

下面，我们来看 Gin 对请求的处理流程，先来看一下 engine.handleHTTPRequest(c *Context) 方法，该方法在前面的几篇 Gin 源码学习的文章中出现过多次，所以这里也是同样，只保留其与当前文章主题相关的源代码：

func (engine *Engine) handleHTTPRequest(c *Context) {
	// 省略...

	// 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 {
			continue
		}
		root := t[i].root
		// Find route in tree
		value := root.getValue(rPath, c.Params, unescape)
		if value.handlers != nil {
			c.handlers = value.handlers
			c.Params = value.params
			c.fullPath = value.fullPath
			// 开始对请求执行中间件和处理函数
			c.Next()
			// 设置响应头信息
			c.writermem.WriteHeaderNow()
			return
		}
		// 省略...
		break
	}

	// 省略...
	c.handlers = engine.allNoRoute
	// 处理 404 错误
	serveError(c, http.StatusNotFound, default404Body)
}
复制代码

在上一篇文章中讲到过 Gin 请求路由的匹配是在 root.getValue(path string, po Params, unescape bool) 方法中实现的，并且，当返回的 value 对象中的 handlers 属性不为 nil 时，则表示该请求存在处理函数，然后将 value 对象中的处理函数切片集、请求参数以及请求的完整路径信息存放至该请求的上下文对象中，接着调用 context.Next() 方法，下面来看一下该方法的源代码：

// Next should be used only inside middleware.
// It executes the pending handlers in the chain inside the calling handler.
// Next 只能在中间件内部使用
// 它在调用处理程序内的链中执行挂起的处理程序
// 类似于递归调用或函数装饰器
func (c *Context) Next() {
    // index 初始值为 -1
	c.index++
	for c.index < int8(len(c.handlers)) {
		c.handlers[c.index](c)
		c.index++
	}
}
复制代码

context.Next() 方法的逻辑比较简单，其实就是遍历存放于 Gin 上下文中的中间件/处理函数切片，并调用，在上一篇文章中，我们也讲过， context.handlers 切片中，在有多个 HandlerFunc 的时候，除了最后一个为该路由的处理函数之外，其余的都为中间件。

这里需要注意的点是，该 Next() 方法，在使用的时候，只能在中间件内部使用，也就是说，在日常开发中，该方法只能在自己编写的中间件中出现，而不能出现在其它地方。

下面，我们以 gin.Default() 创建 gin.Engine 时添加的两个默认中间件 Logger 和 Recovery ，并结合一个模拟身份验证的中间件 Auth 为例，来对 Gin 中间件的工作流程进行详细讲解，先来看一下 gin.Default() 方法添加的默认中间件 Logger 的相关源代码：

func Default() *Engine {
	debugPrintWARNINGDefault()
	engine := New()
	engine.Use(Logger(), Recovery())
	return engine
}

// Logger instances a Logger middleware that will write the logs to gin.DefaultWriter.
// By default gin.DefaultWriter = os.Stdout.
// Logger 是一个中间件, 该中间件会将日志写入 gin.DefaultWriter.
// 默认的 gin.DefaultWriter 为 os.Stdout, 即标准输出流, 控制台
func Logger() HandlerFunc {
	return LoggerWithConfig(LoggerConfig{})
}

// LoggerConfig defines the config for Logger middleware.
// Logger 中间件的相关配置
type LoggerConfig struct {
	// Optional. Default value is gin.defaultLogFormatter
	// 用于输出内容的格式化, 默认为 gin.defaultLogFormatter
	Formatter LogFormatter

	// Output is a writer where logs are written.
	// Optional. Default value is gin.DefaultWriter.
	// 日志输出对象
	Output io.Writer

	// SkipPaths is a url path array which logs are not written.
	// Optional.
	// 忽略日志输出的 URL 切片
	SkipPaths []string
}

// LoggerWithConfig instance a Logger middleware with config.
// 使用 LoggerConfig 配置的 Logger 中间件
func LoggerWithConfig(conf LoggerConfig) HandlerFunc {
	formatter := conf.Formatter
	if formatter == nil {
		formatter = defaultLogFormatter
	}

	out := conf.Output
	if out == nil {
		out = DefaultWriter
	}

	notlogged := conf.SkipPaths

	// 是否输出至终端
	isTerm := true

	if w, ok := out.(*os.File); !ok || os.Getenv("TERM") == "dumb" ||
		(!isatty.IsTerminal(w.Fd()) && !isatty.IsCygwinTerminal(w.Fd())) {
		isTerm = false
	}

	// 标记忽略日志的 path
	var skip map[string]struct{}

	if length := len(notlogged); length > 0 {
		skip = make(map[string]struct{}, length)

		for _, path := range notlogged {
			skip[path] = struct{}{}
		}
	}

	return func(c *Context) {
		// Start timer
		// 记录开始时间
		start := time.Now()
		path := c.Request.URL.Path
		raw := c.Request.URL.RawQuery

		// Process request
		// 继续执行下一个中间件
		c.Next()

		// Log only when path is not being skipped
		// 如果 path 在 skip 中, 则忽略日志记录
		if _, ok := skip[path]; !ok {
			param := LogFormatterParams{
				Request: c.Request,
				isTerm:  isTerm,
				Keys:    c.Keys,
			}

			// Stop timer
			// 记录结束时间
			param.TimeStamp = time.Now()
			// 计算耗时
			param.Latency = param.TimeStamp.Sub(start)

			// 客户端 IP
			param.ClientIP = c.ClientIP()
			// 请求方法
			param.Method = c.Request.Method
			// 请求状态码
			param.StatusCode = c.Writer.Status()
			// 错误信息
			param.ErrorMessage = c.Errors.ByType(ErrorTypePrivate).String()
			// 响应体大小
			param.BodySize = c.Writer.Size()

			if raw != "" {
				path = path + "?" + raw
			}

			param.Path = path

			// 日志打印
			fmt.Fprint(out, formatter(param))
		}
	}
}
复制代码

其实中间件也就是装饰器或闭包，实质上就是一种返回类型为 HandlerFunc 的函数，通俗地讲，就是一种返回函数的函数，目的就是为了在外层函数中，对内层函数进行装饰或处理，然后再将被装饰或处理后的内层函数返回。

由于 HandlerFunc 函数只能接受一个 gin.Context 参数，因此，在上面源代码中的 LoggerWithConfig(conf LoggerConfig) 函数中，使用 LoggerConfig 配置，对 HandlerFunc 进行装饰，并返回。

同样地，在返回的 HandlerFunc 匿名函数中，首先是记录进入该中间件时的一些信息，包括时间，然后再调用 context.Next() 方法，挂起当前的处理程序，递归去调用后续的中间件，当后续所有中间件和处理函数执行完毕时，再回到此处，如果要记录该 path 的日志，则再获取一次当前的时间，与开始记录的时间进行计算，即可得出本次请求处理的耗时，再保存其它信息，包括请求 IP 和响应的相关信息等，最后将该请求的日志进行打印处理，这就是使用 gin.Default() 实例一个 gin.Engine 默认添加的 Logger() 中间件的处理流程。

下面，我们来看一下，另一个默认中间件 Recovery() 的相关源代码：

// Recovery returns a middleware that recovers from any panics and writes a 500 if there was one.
// Recovery 中间件用于捕获处理流程中出现 panic 的错误
// 如果连接未断开, 则返回 500 错误响应
func Recovery() HandlerFunc {
	// DefaultErrorWriter = os.Stderr
	return RecoveryWithWriter(DefaultErrorWriter)
}

// RecoveryWithWriter returns a middleware for a given writer that recovers from any panics and writes a 500 if there was one.
// 使用传递的 out 对 Recovery 中间件进行装饰
func RecoveryWithWriter(out io.Writer) HandlerFunc {
	var logger *log.Logger
	if out != nil {
		logger = log.New(out, "\n\n\x1b[31m", log.LstdFlags)
	}
	return func(c *Context) {
		defer func() {
			if err := recover(); err != nil {
				// Check for a broken connection, as it is not really a
				// condition that warrants a panic stack trace.
				// 用于标记连接是否断开
				var brokenPipe bool
				// 从错误信息中判断连接是否断开
				if ne, ok := err.(*net.OpError); ok {
					if se, ok := ne.Err.(*os.SyscallError); ok {
						if strings.Contains(strings.ToLower(se.Error()), "broken pipe") || strings.Contains(strings.ToLower(se.Error()), "connection reset by peer") {
							brokenPipe = true
						}
					}
				}
				// 省略, 日志打印相关...

				// If the connection is dead, we can't write a status to it.
				if brokenPipe {	// 如果连接已断开, 则已经无法为其写入状态码
					// 添加错误信息至上下文中, 用于日志输出
					c.Error(err.(error)) // nolint: errcheck
					// 终止该上下文
					c.Abort()
				} else {	// 连接未断开
					// 终止该上下文并写入 500 错误状态码
					c.AbortWithStatus(http.StatusInternalServerError)
				}
			}
		}()
		// 继续执行下一个中间件
		c.Next()
	}
}
复制代码

与 LoggerWithConfig(conf LoggerConfig) 函数一样， RecoveryWithWriter(out io.Writer) 函数仅为了对最终返回的中间件 HandlerFunc 函数进行装饰，在该中间件中，可分为两个逻辑块，一个是 defer ，一个是 Next() ， Next() 与 Logger() 中间件中的 Next() 作用类似，这里在 defer 中使用 recover() 来捕获在后续中间件中 panic 的错误信息，并对该错误信息进行处理。

在该中间件中，首先是判断当前连接是否已中断，然后是进行相关的日志处理，最后，如果连接已中断，则直接设置错误信息，并终止该上下文，否则，终止该上下文并返回 500 错误响应。

下面，我们来看一下 context.Abort() 方法和 context.AbortWithStatus(code int) 方法的相关源代码：

// 63
const abortIndex int8 = math.MaxInt8 / 2

// 终止上下文
func (c *Context) Abort() {
	c.index = abortIndex
}

// 判断上下文是否终止
func (c *Context) IsAborted() bool {
	return c.index >= abortIndex
}

// 终止上下文并将 code 写入响应头中
func (c *Context) AbortWithStatus(code int) {
	c.Status(code)
	c.Writer.WriteHeaderNow()
	c.Abort()
}
复制代码

context.Abort() 方法将当前上下文的 index 值设置为 63，用于标志上下文的终止。

context.AbortWithStatus(code int) 也是终止当前的上下文，只不过额外的使用了 code 参数，对响应的头信息进行了设置。

最后，我们再来看一个模拟身份校验的中间件 Auth ，其实现的相关源代码如下：

type RequestData struct{
	Action string `json:"action"`
	UserID int `json:"user_id"`
}

func main() {
	router := gin.Default()
	// 注册中间件
	router.Use(Auth())

	router.POST("/action", func(c *gin.Context) {
		var RequestData RequestData
		if err := c.BindJSON(&RequestData); err == nil {
			c.JSON(http.StatusOK, gin.H{"code": 200, "msg": "success"})
		}
	})

	router.Run(":8000")
}

func Auth() gin.HandlerFunc {
	// TODO: 可模仿 Logger() 或 Recovery() 中间件, 结合该函数的调用参数, 在此处做一些配置操作
	return func(c *gin.Context) {
		// TODO: 可模仿 Logger() 中间件, 在此处对请求的 path 进行忽略处理
		if auth(c.Request) {
			c.Next()
		} else {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"msg": "Unauthorized"})
		}
	}
}

func auth(req *http.Request) bool {
	// TODO: 对 http.Request 中的信息进行校验, 如 cookie, token...
	return req.Header.Get("Auth") == "colelie"
}
复制代码

首先是 Auth() 函数，该函数用于装饰并返回 gin.HandlerFunc 函数，在该函数内，返回了一个 gin.HandlerFunc 匿名函数，在该匿名函数中，通过调用 auth(req *http.Request) 函数对请求信息进行校验，这里只是一个简单地对请求头中的 Auth 进行验证。

所以，在该案例中，当我们访问 /action 接口时，首先会进入 Logger() 中间件，然后进入 Recovery() 中间件，再进入 Auth() 中间件，当前面的中间件都没有发生对上下文的终止操作时，才会进入我们声明的 router.POST("/action"， func) 处理函数。

当我们向 /action 接口发起一个普通的 POST 请求时，会收到如下响应：

这是由于在 Auth() 中间件中身份校验没通过，我们为该请求的头部信息中添加一个 Key 为 Auth ，Value 为 colelie 的字段，会收到如下响应：

可以发现，同样的，出现了错误响应，而这次的错误响应码为 400，这是为什么呢？

在 Gin 源码学习（二）丨请求体中的参数是如何解析的？ 中，我们讲过，在使用 MustBind 一类的绑定函数时，如果在参数解析过程中出现错误，会调用 c.AbortWithError(http.StatusBadRequest, err) 方法，终止当前的上下文并返回 400 响应错误码，在上面的声明的对 /action 的处理函数中，使用了 context.BindJSON(obj interface{}) 方法对请求参数进行绑定操作，下面，我们在为请求添加能够绑定成功的请求体，会收到如下响应：

这次，得到了正确的响应内容。

小结

在这篇文章中，我们围绕 gin.Context 的内部结构、Gin 中间件和处理函数的工作流程，讲解了 Gin 对请求的处理流程。

首先，在 gin.Engine 中，使用对象池 sync.Pool 来存放 gin.Context 这样做的目的是为 Go GC 减少压力。

然后，在 Gin 内部，当路由匹配成功后，将调用 context.Next() 方法，开始进入 Gin 中间件和处理函数的执行操作，并且，需要注意的是，在日常开发中，该方法，只能在中间件中被调用。

最后，以使用 gin.Default() 方法创建 gin.Engine 时携带的两个默认中间件 Logger() 和 Recovery() ，和我们自己编写的一个模拟身份校验的中间件 Auth() ，结合注册的 path 为 /action 的路由，对 Gin 中间件和处理函数的工作流程进行了讲解。

至此，Gin 源码学习的第四篇也就到此结束了，感谢大家对本文的阅读~~

欢迎扫描以下二维码关注笔者的个人订阅号，获取最新文章推送：