编辑“︁Gin中间件概念”︁

{{DISPLAYTITLE:Gin中间件概念}}

== 概述 ==
'''Gin中间件'''是Gin框架的核心机制之一，指在HTTP请求到达路由处理函数前或后执行的函数链。中间件允许开发者以模块化方式处理通用逻辑（如认证、日志、错误恢复等），实现[[横切关注点]]（Cross-Cutting Concerns）与业务逻辑的解耦。

中间件在Gin中的执行顺序遵循洋葱模型（Onion Model），即请求从外到内穿过中间件栈，响应则从内到外返回。数学上可表示为：
<math>M_1 \circ M_2 \circ \cdots \circ M_n (Request) \rightarrow Response</math>
其中<math>\circ</math>表示函数组合。

== 核心特性 ==
* '''执行顺序控制'''：通过<code>Use()</code>方法注册的中间件按声明顺序执行
* '''短路机制'''：中间件可通过<code>c.Abort()</code>终止后续处理
* '''上下文共享'''：通过<code>gin.Context</code>对象在中间件间传递数据
* '''分组应用'''：支持路由组级别的中间件嵌套

== 基本用法 ==
=== 定义中间件 ===
中间件是签名为<code>func(*gin.Context)</code>的函数，通常返回一个闭包：

<syntaxhighlight lang="go">
// 示例：记录请求耗时的中间件
func Logger() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        
        // 请求处理前逻辑
        c.Next() // 执行后续中间件和路由处理
        
        // 请求处理后逻辑
        latency := time.Since(start)
        log.Printf("请求 %s 耗时 %v", c.Request.URL.Path, latency)
    }
}
</syntaxhighlight>

=== 注册中间件 ===
全局中间件和路由组中间件的注册方式：

<syntaxhighlight lang="go">
func main() {
    r := gin.Default()
    
    // 全局中间件（对所有路由生效）
    r.Use(Logger())
    
    // 路由组中间件
    api := r.Group("/api", AuthMiddleware()) 
    {
        api.GET("/users", getUserList)
    }
    
    r.Run(":8080")
}
</syntaxhighlight>

== 执行流程 ==
<mermaid>
sequenceDiagram
    participant Client
    participant Middleware1
    participant Middleware2
    participant Handler
    participant Middleware2
    participant Middleware1
    participant Client
    
    Client->>Middleware1: 请求进入
    Middleware1->>Middleware2: c.Next()
    Middleware2->>Handler: c.Next()
    Handler-->>Middleware2: 返回响应
    Middleware2-->>Middleware1: 继续后续处理
    Middleware1-->>Client: 最终响应
</mermaid>

== 实际案例 ==
=== 认证中间件 ===
<syntaxhighlight lang="go">
func JWTAuth() gin.HandlerFunc {
    return func(c *gin.Context) {
        token := c.GetHeader("Authorization")
        if token == "" {
            c.AbortWithStatusJSON(401, gin.H{"error": "未提供认证令牌"})
            return
        }
        
        claims, err := validateToken(token)
        if err != nil {
            c.AbortWithStatusJSON(403, gin.H{"error": "无效令牌"})
            return
        }
        
        c.Set("userID", claims.UserID) // 存储用户信息到上下文
        c.Next()
    }
}
</syntaxhighlight>

=== 跨域中间件 ===
<syntaxhighlight lang="go">
func Cors() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Writer.Header().Set("Access-Control-Allow-Origin", "*")
        c.Writer.Header().Set("Access-Control-Allow-Methods", "GET, POST, PUT, DELETE")
        c.Next()
    }
}
</syntaxhighlight>

== 高级用法 ==
=== 中间件短路 ===
使用<code>Abort()</code>系列方法可中断中间件链：

<syntaxhighlight lang="go">
func MaintenanceMode() gin.HandlerFunc {
    return func(c *gin.Context) {
        if config.InMaintenance {
            c.AbortWithStatusJSON(503, gin.H{"message": "系统维护中"})
            // 不会执行c.Next()
        }
        c.Next()
    }
}
</syntaxhighlight>

=== 条件中间件 ===
通过闭包参数实现动态配置：

<syntaxhighlight lang="go">
func RateLimiter(limit int) gin.HandlerFunc {
    bucket := make(chan struct{}, limit)
    return func(c *gin.Context) {
        select {
        case bucket <- struct{}{}:
            defer func() { <-bucket }()
            c.Next()
        default:
            c.AbortWithStatus(429)
        }
    }
}
</syntaxhighlight>

== 最佳实践 ==
* 每个中间件应专注单一功能
* 避免在中间件中进行耗时同步操作（考虑使用goroutine）
* 通过<code>c.Set()</code>/<code>c.Get()</code>安全传递数据
* 错误处理中间件应注册在最早位置

== 常见问题 ==
'''Q: 中间件和路由处理函数的执行顺序关系？'''
A: 执行顺序遵循声明顺序，但实际流程为：
<mermaid>
graph LR
    A[中间件1前逻辑] --> B[中间件2前逻辑]
    B --> C[路由处理]
    C --> D[中间件2后逻辑]
    D --> E[中间件1后逻辑]
</mermaid>

'''Q: 如何跳过剩余中间件？'''
A: 调用<code>c.Abort()</code>后，当前中间件仍会执行完毕，但后续中间件和路由处理将被跳过。

== 性能考量 ==
中间件数量直接影响请求处理延迟。建议：
* 生产环境禁用调试中间件
* 使用<code>sync.Pool</code>重用中间件对象
* 监控中间件耗时（可通过基准测试工具测量）

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin基础]]