4. Gin 框架中间件：Engine、RouterGroup 与自定义中间件

Gin 的中间件机制是其核心扩展点，也是构建微服务链路治理（日志、鉴权、限流、链路追踪）的基础。本章深入剖析 Gin 的 Engine 与 RouterGroup 的中间件注册原理、控制流函数 c.Next() 与 c.Abort() 的执行语义，并手写一个生产级自定义中间件。

4.1 Engine 与 RouterGroup：中间件的注册载体

Gin 的 Engine 是整个路由树的根节点，它本身就是一个顶级的 RouterGroup。所有中间件最终都挂载在某个 RouterGroup 上，形成链式调用栈。

4.2 c.Next() 与 c.Abort()：控制流的核心语义

Gin 的 Context 内部维护了一个索引 index，指向 HandlersChain 的当前执行位置。理解 Next() 和 Abort() 对 index 的影响，是编写正确中间件的关键。

• c.Next()：将 index 加 1，并递归调用下一个处理器。当前中间件在 c.Next() 之前的代码在“请求前”执行，之后的代码在“响应后”执行（后置钩子）。
• c.Abort()：将 index 设置为 abortIndex（一个很大的值，通常为 64），阻止后续所有处理器执行。但已执行的处理器不受影响。
• c.IsAborted()：判断当前请求是否已被终止，常用于中间件中提前返回。

4.3 自定义 Gin 中间件：从基础到生产级

Gin 中间件的签名是 func(c *gin.Context)。一个生产级中间件通常包含：前置处理、调用 c.Next()、后置处理、异常恢复。

4.3.1 基础结构：请求耗时统计中间件

func RequestTimer() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        // 前置：记录请求开始
        c.Set("request_start", start)

        // 调用下一个处理器
        c.Next()

        // 后置：计算耗时
        duration := time.Since(start)
        path := c.Request.URL.Path
        status := c.Writer.Status()
        log.Printf("[TIMER] %s | %d | %v", path, status, duration)
    }
}

4.3.2 生产级中间件：带超时控制的鉴权中间件

以下中间件实现了：从 Header 提取 Token、调用外部认证服务（带超时）、将用户信息注入 Context、认证失败时 Abort。

func AuthMiddleware(authServiceAddr string, timeout time.Duration) gin.HandlerFunc {
    client := &http.Client{Timeout: timeout}

    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing token"})
            return
        }

        // 调用外部认证服务
        req, _ := http.NewRequestWithContext(c.Request.Context(),
            http.MethodGet, authServiceAddr+"/verify", nil)
        req.Header.Set("Authorization", token)

        resp, err := client.Do(req)
        if err != nil || resp.StatusCode != http.StatusOK {
            c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "auth failed"})
            return
        }

        // 将用户信息注入 Context
        c.Set("user_id", resp.Header.Get("X-User-Id"))
        c.Set("user_role", resp.Header.Get("X-User-Role"))

        c.Next()
    }
}

4.4 中间件注册方式对比

4.5 中间件性能调优要点

• 避免在中间件中分配大量临时对象：使用 sync.Pool 复用对象，减少 GC 压力。
• 谨慎使用 c.Set() 和 c.Get()：每次调用都会在 map 中查找，高频路径下建议直接使用 c.Request.Context() 传递值。
• 中间件链不宜过长：每个中间件都会增加调用栈深度和内存分配。建议将功能相近的中间件合并。
• 使用 c.Copy() 的时机：只有在需要将 Context 传递给 goroutine 时才使用 c.Copy()，否则直接使用 c 即可。