Gin Context生命周期与请求处理

Context贯穿请求处理全过程，理解其生命周期对编写高效安全的代码至关重要。

Context生命周期概览

创建 → 获取 → 重置 → 处理请求 → 响应 → 归还
(池初始化)  (pool.Get)  (reset)  (handleHTTPRequest)  (Write)  (pool.Put)

创建与初始化

Engine初始化时创建池

func New() *Engine {
    engine := &Engine{
        // ...
    }

    // Context池初始化
    engine.pool.New = func() any {
        return engine.allocateContext()
    }

    return engine
}

func (engine *Engine) allocateContext() *Context {
    return &Context{engine: engine}
}

Context结构

type Context struct {
    Request   *http.Request
    Writer    ResponseWriter

    Params   Params
    handlers HandlersChain
    index    int8
    fullPath string

    engine   *Engine
    Keys     map[string]any

    Errors   errorMsgs
    Accepted []string

    queryCache url.Values
    formCache  url.Values
}

请求处理流程

请求入口

func (engine *Engine) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    // 1. 从池获取Context
    c := engine.pool.Get().(*Context)

    // 2. 重置Context状态
    c.Writer.reset(w)
    c.Request = r
    c.reset()

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

    // 4. 归还Context
    engine.pool.Put(c)
}

Context重置

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

请求处理阶段

阶段一：路由匹配

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

    // 遍历方法树查找路由
    for _, tree := range engine.trees {
        if tree.method != httpMethod {
            continue
        }

        value := tree.root.getValue(rPath, c.Params, c.unescape)

        if value.handlers != nil {
            c.handlers = value.handlers
            c.Params = value.params
            c.fullPath = value.fullPath
            c.Next()
            c.Writer.WriteHeaderNow()
            return
        }
    }

    // 404处理
    engine.handle404(c)
}

阶段二：中间件执行

func (c *Context) Next() {
    c.index++
    for c.index < int8(len(c.handlers)) {
        c.handlers[c.index](c)
        c.index++
    }
}

阶段三：响应写入

type ResponseWriter interface {
    Header() http.Header
    Write([]byte) (int, error)
    WriteHeader(statusCode int)

    // Gin扩展
    Status() int
    Size() int
    Written() bool
    WriteHeaderNow()
    Pusher() http.Pusher
}

生命周期钩子

Before响应钩子

func (w *responseWriter) Before(before func(ResponseWriter)) {
    w.beforeHandlers = append(w.beforeHandlers, before)
}

// 使用示例
func middleware(c *gin.Context) {
    c.Writer.Before(func(w gin.ResponseWriter) {
        w.Header().Set("X-Response-Time", time.Since(startTime).String())
    })
    c.Next()
}

defer清理钩子

func middleware(c *gin.Context) {
    // 请求开始
    start := time.Now()

    defer func() {
        // 请求结束
        duration := time.Since(start)
        log.Printf("Request took %v", duration)
    }()

    c.Next()
}

并发安全注意事项

危险：异步使用Context

// 错误示例
func badHandler(c *gin.Context) {
    go func() {
        // Context已被归还，访问不安全
        c.JSON(200, gin.H{"message": "async"})
    }()
    c.Next()
}

正确：传递必要数据

// 正确示例
func goodHandler(c *gin.Context) {
    userID := c.GetString("userID")
    traceID := c.GetString("traceID")

    go func(uid, tid string) {
        // 使用传递的值，不访问Context
        processAsync(uid, tid)
    }(userID, traceID)

    c.Next()
}

Context复用机制

请求1 → Context获取 → 处理 → 归还 → 请求2 → 同一Context获取 → ...
         ↓                    ↑
      重置状态              清空数据

注意：请求处理完成后Context立即归还，禁止在goroutine中引用。

要点总结

• Context通过sync.Pool实现对象复用
• reset()确保每次请求Context状态干净
• 生命周期：获取→重置→处理→响应→归还
• 禁止异步持有Context引用
• 使用Before钩子在响应前修改头部