Gin请求生命周期管理

请求生命周期是Gin处理HTTP请求的完整流程，理解各阶段有助于正确扩展功能。

生命周期概览

请求到达 → Context获取 → 中间件执行 → 路由匹配 → 处理器执行 → 响应写入 → Context归还

完整生命周期阶段

1. 请求接收

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

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

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

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

2. 中间件执行

func (engine *Engine) handleHTTPRequest(c *Context) {
    // 查找路由
    httpMethod := c.Request.Method
    rPath := c.Request.URL.Path

    value := engine.tre.getValue(rPath, c.Params, c.unescape)

    if value.handlers != nil {
        c.handlers = value.handlers
        c.Params = value.params
        c.Next()  // 执行中间件链
        c.Writer.WriteHeaderNow()
        return
    }
}

3. 中间件链执行流程

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

func (c *Context) Abort() {
    c.index = abortIndex  // 63
}

4. 响应阶段钩子

// 响应写入前回调
type ResponseWriter interface {
    WriteHeaderNow()
    Written() bool
    Status() int
    Size() int
    Before(func(ResponseWriter))
}

// 使用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()
}

生命周期扩展点

完整生命周期示例

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

    // 全局中间件
    r.Use(gin.Recovery())
    r.Use(Logger())

    // 请求生命周期追踪
    r.Use(func(c *gin.Context) {
        start := time.Now()
        traceID := uuid.New().String()
        c.Set("traceID", traceID)

        fmt.Printf("[%s] 请求开始: %s %s\n", traceID, c.Request.Method, c.Request.URL.Path)

        defer func() {
            duration := time.Since(start)
            fmt.Printf("[%s] 请求结束: 耗时 %v, 状态码 %d\n",
                traceID, duration, c.Writer.Status())
        }()

        c.Next()
    })

    r.GET("/api", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "hello"})
    })

    r.Run(":8080")
}

Panic处理机制

// 内置Recovery中间件
func Recovery() HandlerFunc {
    return func(c *Context) {
        defer func() {
            if err := recover(); err != nil {
                // 检查连接是否断开
                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") {
                            c.Abort()
                            return
                        }
                    }
                }

                c.AbortWithStatus(500)
            }
        }()
        c.Next()
    }
}

请求取消处理

func RequestCancellation(c *gin.Context) {
    ctx := c.Request.Context()

    select {
    case <-ctx.Done():
        // 客户端取消请求
        c.JSON(499, gin.H{"error": "client closed request"})
        c.Abort()
        return
    default:
        c.Next()
    }
}

注意：Context在请求结束后归还池中，不要在goroutine中持有Context引用。

要点总结

• 请求生命周期：获取Context → 执行中间件链 → 响应 → 归还
• c.Next()驱动中间件链执行，c.Abort()中断链
• 中间件顺序执行，c.Next()后代码逆序执行（洋葱模型）
• 使用defer确保资源清理和panic恢复
• Context对象池化，请求结束后自动重置归还