编辑“︁Gin内置中间件”︁

{{DISPLAYTITLE:Gin内置中间件}}

== 概述 ==
'''Gin内置中间件'''是[[Gin框架]]预先封装的一系列常用中间件组件，用于处理HTTP请求生命周期中的通用逻辑（如日志记录、异常恢复等）。这些中间件通过标准接口集成到路由处理流程中，开发者无需重复实现基础功能。

Gin的中间件系统基于洋葱模型（Onion Model）设计，请求和响应会依次通过所有注册的中间件层。内置中间件经过高度优化，可直接在生产环境中使用。

== 核心内置中间件列表 ==
以下是Gin v1.9.0版本提供的主要内置中间件：

{| class="wikitable"
|-
! 中间件名称 !! 功能描述 !! 适用场景
|-
| <code>Logger()</code> || 记录HTTP请求日志（方法、路径、状态码、延迟等） || 开发调试/生产监控
|-
| <code>Recovery()</code> || 捕获panic并返回500错误，防止进程退出 || 生产环境必备
|-
| <code>BasicAuth()</code> || HTTP基础认证中间件 || 简单权限控制
|-
| <code>CustomRecovery()</code> || 可自定义处理逻辑的Recovery变体 || 特殊错误处理需求
|}

== 详细解析 ==

=== Logger中间件 ===
记录请求的详细信息到标准输出（可配置输出位置）：

<syntaxhighlight lang="go">
package main

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

func main() {
    router := gin.Default() // 默认包含Logger和Recovery中间件
    
    // 手动添加Logger的等效方式：
    // router.Use(gin.Logger())
    
    router.GET("/ping", func(c *gin.Context) {
        c.String(200, "pong")
    })
    
    router.Run(":8080")
}
</syntaxhighlight>

示例输出（控制台）：
<pre>
[GIN] 2023/08/20 - 15:04:05 | 200 |     1.023ms |       127.0.0.1 | GET      "/ping"
</pre>

参数说明：
* <code>200</code> - HTTP状态码
* <code>1.023ms</code> - 请求处理耗时
* <code>127.0.0.1</code> - 客户端IP

=== Recovery中间件 ===
自动恢复从panic中恢复，避免服务崩溃：

<syntaxhighlight lang="go">
func main() {
    router := gin.New() // 不使用Default()初始化
    router.Use(gin.Recovery()) // 手动添加
    
    router.GET("/panic", func(c *gin.Context) {
        panic("模拟异常")
    })
    
    router.Run(":8080")
}
</syntaxhighlight>

当访问<code>/panic</code>时，会返回：
<pre>
{
    "error": "模拟异常"
}
</pre>
而非直接退出进程。

=== BasicAuth中间件 ===
实现HTTP基础认证：

<syntaxhighlight lang="go">
func main() {
    authorized := gin.New()
    accounts := gin.Accounts{
        "admin": "secret123",
        "user":  "password456",
    }
    authorized.Use(gin.BasicAuth(accounts))
    
    authorized.GET("/secret", func(c *gin.Context) {
        c.String(200, "认证通过!")
    })
}
</syntaxhighlight>

访问时需要提供正确的用户名密码：
<pre>
curl -u admin:secret123 http://localhost:8080/secret
</pre>

== 中间件执行流程 ==
<mermaid>
sequenceDiagram
    participant Client
    participant Logger
    participant Recovery
    participant Handler
    
    Client->>Logger: HTTP请求
    Logger->>Recovery: 传递请求
    Recovery->>Handler: 执行业务逻辑
    Handler-->>Recovery: 返回响应/panic
    Recovery-->>Logger: 错误处理
    Logger-->>Client: 返回最终响应
</mermaid>

== 高级配置 ==

=== 自定义Logger格式 ===
通过<code>LoggerWithFormatter</code>定制日志格式：

<syntaxhighlight lang="go">
router.Use(gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string {
    return fmt.Sprintf("[%s] %s \"%s %s\" %d %s\n",
        param.TimeStamp.Format(time.RFC3339),
        param.ClientIP,
        param.Method,
        param.Path,
        param.StatusCode,
        param.Latency,
    )
}))
</syntaxhighlight>

=== 自定义Recovery行为 ===
使用<code>CustomRecovery</code>处理特定错误类型：

<syntaxhighlight lang="go">
router.Use(gin.CustomRecovery(func(c *gin.Context, err any) {
    if strings.Contains(fmt.Sprint(err), "数据库错误") {
        c.JSON(500, gin.H{"error": "数据库操作失败"})
    } else {
        c.AbortWithStatus(500)
    }
}))
</syntaxhighlight>

== 性能考虑 ==
内置中间件已进行以下优化：
* Logger使用缓冲IO减少系统调用
* Recovery避免内存分配（通过<code>sync.Pool</code>复用对象）
* 所有中间件均无阻塞操作

== 最佳实践 ==
1. 生产环境必须启用<code>Recovery</code>
2. 开发环境建议使用<code>Logger</code>
3. 高并发场景可考虑替换为更高效的日志中间件（如zap）
4. 基础认证建议配合HTTPS使用

== 参见 ==
* [[Gin框架中间件原理]]
* [[自定义Gin中间件开发]]
* [[HTTP中间件设计模式]]

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