编辑“︁Gin日志中间件”︁

= Gin日志中间件 =

'''Gin日志中间件'''是[[Gin框架]]内置的请求日志记录工具，用于自动记录HTTP请求的详细信息，包括请求方法、路径、状态码、响应时间等关键指标。作为中间件（Middleware），它在处理流程中位于路由处理器之前，能够无侵入式地为Web应用提供标准化日志输出，是调试、性能监控和安全审计的重要工具。

== 核心功能 ==
Gin日志中间件通过`gin.Logger()`函数实现，主要功能包括：
* 记录HTTP请求方法（GET/POST等）和路径
* 输出响应状态码（200/404/500等）
* 记录请求处理延迟（Latency）
* 显示客户端IP和User-Agent
* 支持自定义日志格式

== 基础用法 ==
以下是最简单的启用示例：

<syntaxhighlight lang="go">
package main

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

func main() {
    r := gin.Default() // 默认已包含Logger和Recovery中间件
    
    r.GET("/hello", func(c *gin.Context) {
        c.String(200, "Hello World")
    })
    
    r.Run(":8080")
}
</syntaxhighlight>

当访问`/hello`时，控制台会输出类似：
<pre>
[GIN] 2023/10/15 - 15:04:05 | 200 |     1.0025ms |             ::1 | GET      "/hello"
</pre>

== 日志格式说明 ==
默认日志格式包含以下字段（按顺序）：
{| class="wikitable"
|-
! 字段 !! 示例 !! 说明
|-
| 时间戳 || 2023/10/15 - 15:04:05 || 请求到达时间
|-
| 状态码 || 200 || HTTP响应状态
|-
| 延迟 || 1.0025ms || 请求处理耗时
|-
| 客户端IP || ::1 || 支持IPv4/IPv6
|-
| 方法路径 || GET "/hello" || HTTP方法和请求路径
|}

== 自定义配置 ==
通过`gin.LoggerWithConfig()`可实现深度定制：

<syntaxhighlight lang="go">
r := gin.New()
r.Use(gin.LoggerWithConfig(gin.LoggerConfig{
    Output: os.Stdout,           // 输出目标
    SkipPaths: []string{"/test"}, // 跳过特定路径
    Format: "[${time}] ${status} - ${latency} ${method} ${path}\n", // 自定义格式
}))
</syntaxhighlight>

=== 可用变量 ===
自定义格式时可用占位符：
* ${time} - 时间戳
* ${status} - HTTP状态码
* ${latency} - 处理延迟
* ${clientIP} - 客户端IP
* ${method} - 请求方法
* ${path} - 请求路径
* ${error} - 错误信息（如有）

== 性能优化建议 ==
1. 生产环境建议将日志写入文件而非控制台：
<syntaxhighlight lang="go">
f, _ := os.Create("gin.log")
gin.DefaultWriter = io.MultiWriter(f)
</syntaxhighlight>

2. 对高频接口（如健康检查）使用SkipPaths跳过日志记录

3. 使用异步日志写入避免阻塞主流程

== 高级应用案例 ==
=== 结合日志分析系统 ===
将Gin日志输出到ELK（Elasticsearch+Logstash+Kibana）栈：

<mermaid>
graph LR
    A[Gin App] -->|JSON日志| B[Logstash]
    B --> C[Elasticsearch]
    C --> D[Kibana Dashboard]
</mermaid>

实现代码：
<syntaxhighlight lang="go">
type logEntry struct {
    Time    string `json:"time"`
    Status  int    `json:"status"`
    Latency string `json:"latency"`
    Method  string `json:"method"`
    Path    string `json:"path"`
}

r.Use(gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string {
    entry := &logEntry{
        Time:    param.TimeStamp.Format(time.RFC3339),
        Status:  param.StatusCode,
        Latency: param.Latency.String(),
        Method:  param.Method,
        Path:    param.Path,
    }
    jsonData, _ := json.Marshal(entry)
    return string(jsonData) + "\n"
}))
</syntaxhighlight>

=== 错误监控集成 ===
当状态码≥500时触发告警：
<syntaxhighlight lang="go">
r.Use(func(c *gin.Context) {
    c.Next()
    if c.Writer.Status() >= 500 {
        notifyError(c) // 调用监控系统API
    }
})
</syntaxhighlight>

== 数学建模 ==
日志采样率计算公式（当QPS过高时）：
<math>
采样率 = \frac{期望日志量}{实际请求量} \times 100\%
</math>

例如系统处理1000QPS，希望保留100条日志：
<math>
采样率 = \frac{100}{1000} \times 100\% = 10\%
</math>

== 最佳实践总结 ==
1. 开发环境使用默认格式便于调试
2. 生产环境采用JSON格式便于解析
3. 重要接口记录详细日志，次要接口适当精简
4. 建立日志分级机制（INFO/WARN/ERROR）
5. 配合日志轮转工具（如logrotate）避免磁盘爆满

通过合理配置Gin日志中间件，开发者可以构建完整的可观测性体系，为系统维护和故障排查提供坚实基础。

[[Category:后端框架]]
[[Category:Gin]]
[[Category:Gin日志与监控]]