编辑“︁Gin全局中间件”︁

{{DISPLAYTITLE:Gin全局中间件}}

== 概述 ==
'''Gin全局中间件'''是指应用于Gin框架所有路由的中间件函数，会在每个HTTP请求到达路由处理器之前或之后执行。全局中间件通常用于实现跨路由的通用功能，如日志记录、身份验证、错误恢复等。在Gin框架中，通过<code>gin.Engine.Use()</code>方法注册全局中间件。

== 核心特性 ==
* '''执行顺序'''：按照注册顺序依次执行
* '''作用范围'''：影响所有路由请求
* '''典型应用'''：
** 请求日志记录
** 跨域资源共享(CORS)处理
** 请求超时控制
** 身份验证
** 数据压缩
** 错误恢复

== 基本语法 ==
全局中间件的基本注册语法如下：

<syntaxhighlight lang="go">
package main

import "github.com/gin-gonic/gin"

func GlobalMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        // 中间件逻辑
        c.Next() // 继续处理后续中间件或路由
    }
}

func main() {
    r := gin.Default()
    r.Use(GlobalMiddleware()) // 注册全局中间件
    
    r.GET("/", func(c *gin.Context) {
        c.String(200, "Hello World")
    })
    
    r.Run(":8080")
}
</syntaxhighlight>

== 执行流程 ==
<mermaid>
graph LR
    A[客户端请求] --> B[全局中间件1]
    B --> C[全局中间件2]
    C --> D[路由处理器]
    D --> E[响应客户端]
</mermaid>

== 代码示例 ==
=== 基础示例：请求日志 ===
以下示例展示如何创建记录请求信息的全局中间件：

<syntaxhighlight lang="go">
func RequestLogger() gin.HandlerFunc {
    return func(c *gin.Context) {
        start := time.Now()
        
        // 处理请求前
        path := c.Request.URL.Path
        method := c.Request.Method
        
        c.Next() // 处理请求
        
        // 处理请求后
        latency := time.Since(start)
        status := c.Writer.Status()
        
        fmt.Printf("[%s] %s | %d | %v\n", 
            method, path, status, latency)
    }
}

func main() {
    r := gin.Default()
    r.Use(RequestLogger()) // 注册全局日志中间件
    
    r.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "pong"})
    })
    
    r.Run(":8080")
}
</syntaxhighlight>

'''输出示例'''：
<pre>
[GET] /ping | 200 | 123.456µs
</pre>

=== 高级示例：JWT认证 ===
实现全局JWT认证中间件：

<syntaxhighlight lang="go">
func JWTAuthMiddleware() gin.HandlerFunc {
    return func(c *gin.Context) {
        tokenString := c.GetHeader("Authorization")
        if tokenString == "" {
            c.AbortWithStatusJSON(401, gin.H{"error": "未提供认证令牌"})
            return
        }
        
        token, err := jwt.Parse(tokenString, func(token *jwt.Token) (interface{}, error) {
            return []byte("your_secret_key"), nil
        })
        
        if err != nil || !token.Valid {
            c.AbortWithStatusJSON(401, gin.H{"error": "无效令牌"})
            return
        }
        
        c.Next()
    }
}

func main() {
    r := gin.Default()
    r.Use(JWTAuthMiddleware()) // 全局JWT验证
    
    r.GET("/protected", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "受保护内容"})
    })
    
    r.Run(":8080")
}
</syntaxhighlight>

== 执行控制 ==
Gin中间件中可以使用以下方法控制执行流程：
* <code>c.Next()</code> - 继续执行后续中间件或路由处理器
* <code>c.Abort()</code> - 中止当前请求的后续处理
* <code>c.AbortWithStatus(code int)</code> - 中止并返回状态码

== 实际应用场景 ==
=== 场景1：跨域处理 ===
全局CORS中间件示例：

<syntaxhighlight lang="go">
func CORSMiddleware() 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, OPTIONS")
        c.Writer.Header().Set("Access-Control-Allow-Headers", "Content-Type, Authorization")
        
        if c.Request.Method == "OPTIONS" {
            c.AbortWithStatus(204)
            return
        }
        
        c.Next()
    }
}
</syntaxhighlight>

=== 场景2：请求超时控制 ===
全局超时中间件示例：

<syntaxhighlight lang="go">
func TimeoutMiddleware(timeout time.Duration) gin.HandlerFunc {
    return func(c *gin.Context) {
        ctx, cancel := context.WithTimeout(c.Request.Context(), timeout)
        defer cancel()
        
        c.Request = c.Request.WithContext(ctx)
        
        done := make(chan struct{})
        go func() {
            c.Next()
            close(done)
        }()
        
        select {
        case <-done:
            return
        case <-ctx.Done():
            c.AbortWithStatus(504)
            c.String(504, "请求超时")
        }
    }
}
</syntaxhighlight>

== 性能考虑 ==
使用全局中间件时需注意：
1. '''中间件数量'''：过多的全局中间件会增加每个请求的处理时间
2. '''内存使用'''：全局中间件中的变量会存在于所有请求生命周期中
3. '''执行顺序'''：关键中间件（如认证）应注册在靠前位置

== 数学表示 ==
中间件处理流程可以表示为函数组合：
<math>
M_{global} = m_n \circ m_{n-1} \circ ... \circ m_1
</math>
其中：
* <math>M_{global}</math> 表示全局中间件链
* <math>\circ</math> 表示函数组合操作
* <math>m_i</math> 表示单个中间件函数

== 最佳实践 ==
1. 将通用功能实现为全局中间件
2. 避免在全局中间件中进行耗时的初始化操作
3. 为中间件添加清晰的日志记录
4. 合理使用<code>c.Abort()</code>提前终止无效请求
5. 考虑使用中间件工厂函数（如上面的<code>TimeoutMiddleware</code>示例）

== 常见问题 ==
'''Q: 如何跳过特定路由的全局中间件？'''
A: 可以在中间件中通过检查路由路径实现条件跳过，但不推荐。更好的做法是将该中间件注册为路由组中间件而非全局中间件。

'''Q: 全局中间件能修改响应内容吗？'''
A: 可以，但需要在<code>c.Next()</code>之后操作，因为此时响应已生成。示例：

<syntaxhighlight lang="go">
func ResponseModifier() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Next()
        
        if strings.Contains(c.GetHeader("Content-Type"), "application/json") {
            originalBody := c.Writer.Body()
            // 修改响应体逻辑
            modifiedBody := modifyJSON(originalBody)
            c.Writer.Write(modifiedBody)
        }
    }
}
</syntaxhighlight>

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin中间件]]