编辑“︁Gin日志输出”︁（章节）

= Gin日志输出 =

'''Gin日志输出'''是Gin框架中用于记录HTTP请求和响应信息的核心功能。通过内置的日志中间件，开发者可以轻松追踪应用程序的运行状态、调试问题以及分析性能瓶颈。本条目将详细介绍Gin的日志系统配置、自定义方法及实际应用场景。

== 概述 ==
Gin默认使用`gin.Default()`初始化引擎时自动加载日志中间件（Logger）和崩溃恢复中间件（Recovery）。日志中间件会输出每个请求的以下信息：
* HTTP方法（GET/POST等）
* 请求路径
* 响应状态码
* 处理耗时
* 客户端IP

示例输出格式：
<pre>
[GIN] 2023/10/15 - 15:04:05 | 200 |     1.002ms | 192.168.1.1 | GET /api/users
</pre>

== 基本配置 ==

=== 默认日志 ===
<syntaxhighlight lang="go">
package main

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

func main() {
    r := gin.Default() // 自动加载Logger和Recovery中间件
    r.GET("/ping", func(c *gin.Context) {
        c.String(200, "pong")
    })
    r.Run(":8080")
}
</syntaxhighlight>

输出示例：
<syntaxhighlight lang="text">
[GIN-debug] Listening and serving HTTP on :8080
[GIN] 2023/10/15 - 15:04:05 | 200 |     0.123ms | ::1 | GET /ping
</syntaxhighlight>

=== 禁用日志 ===
通过`gin.New()`创建不带中间件的引擎：
<syntaxhighlight lang="go">
r := gin.New() // 不包含任何默认中间件
</syntaxhighlight>

== 自定义日志格式 ==

Gin允许通过`LoggerWithFormatter`中间件自定义日志格式：

<syntaxhighlight lang="go">
r := gin.New()
r.Use(gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string {
    return fmt.Sprintf("%s - [%s] \"%s %s %s %d %s \"%s\" %s\"\n",
        param.ClientIP,
        param.TimeStamp.Format(time.RFC1123),
        param.Method,
        param.Path,
        param.Request.Proto,
        param.StatusCode,
        param.Latency,
        param.Request.UserAgent(),
        param.ErrorMessage,
    )
}))
</syntaxhighlight>

输出将变为：
<syntaxhighlight lang="text">
192.168.1.1 - [Mon, 15 Oct 2023 15:04:05 UTC] "GET /ping HTTP/1.1 200 123µs "Mozilla/5.0" "
</syntaxhighlight>

== 日志输出控制 ==

=== 输出到文件 ===
<syntaxhighlight lang="go">
f, _ := os.Create("gin.log")
gin.DefaultWriter = io.MultiWriter(f, os.Stdout) // 同时输出到文件和控制台
</syntaxhighlight>

=== 按环境配置 ===
通过GIN_MODE环境变量控制日志详细程度：
<syntaxhighlight lang="bash">
GIN_MODE=release ./app  # 生产环境（禁用调试日志）
GIN_MODE=debug ./app    # 开发环境（显示彩色日志）
</syntaxhighlight>

== 结构化日志 ==

集成第三方日志库如logrus实现结构化日志：

<syntaxhighlight lang="go">
import (
    "github.com/gin-gonic/gin"
    "github.com/sirupsen/logrus"
)

func main() {
    logger := logrus.New()
    r := gin.New()
    r.Use(func(c *gin.Context) {
        start := time.Now()
        c.Next()
        latency := time.Since(start)
        
        logger.WithFields(logrus.Fields{
            "status":  c.Writer.Status(),
            "method":  c.Request.Method,
            "path":    c.Request.URL.Path,
            "ip":      c.ClientIP(),
            "latency": latency,
        }).Info("request completed")
    })
}
</syntaxhighlight>

输出示例：
<syntaxhighlight lang="json">
{
    "level":"info",
    "msg":"request completed",
    "time":"2023-10-15T15:04:05Z",
    "fields":{
        "ip":"192.168.1.1",
        "latency":123000,
        "method":"GET",
        "path":"/ping",
        "status":200
    }
}
</syntaxhighlight>

== 性能考虑 ==

日志操作可能影响性能，建议：
* 生产环境使用异步日志写入
* 避免记录敏感信息（密码、令牌等）
* 对高频请求路径考虑采样记录

<mermaid>
graph TD
    A[请求进入] --> B[记录开始时间]
    B --> C[处理请求]
    C --> D[计算延迟]
    D --> E[格式化日志]
    E --> F[写入输出]
</mermaid>

== 实际案例 ==

=== API监控场景 ===
结合Prometheus实现请求指标收集：
<syntaxhighlight lang="go">
var (
    requests = prometheus.NewCounterVec(
        prometheus.CounterOpts{
            Name: "http_requests_total",
            Help: "Total number of HTTP requests",
        },
        []string{"method", "path", "status"},
    )
)

func init() {
    prometheus.MustRegister(requests)
}

func main() {
    r := gin.New()
    r.Use(func(c *gin.Context) {
        start := time.Now()
        c.Next()
        
        requests.WithLabelValues(
            c.Request.Method,
            c.Request.URL.Path,
            strconv.Itoa(c.Writer.Status()),
        ).Inc()
    })
}
</syntaxhighlight>

=== 错误追踪 ===
将错误日志发送到Sentry：
<syntaxhighlight lang="go">
r.Use(func(c *gin.Context) {
    defer func() {
        if err := recover(); err != nil {
            sentry.CaptureException(err.(error))
            c.AbortWithStatus(500)
        }
    }()
    c.Next()
})
</syntaxhighlight>

== 数学表示 ==

日志延迟计算可表示为：
<math>
latency = t_{end} - t_{start}
</math>

其中：
* <math>t_{start}</math> = 请求开始时间戳
* <math>t_{end}</math> = 响应完成时间戳

== 最佳实践 ==
1. 生产环境应使用JSON格式的结构化日志
2. 重要业务操作建议添加业务ID便于追踪
3. 遵循日志等级规范：
   * DEBUG - 开发调试信息
   * INFO - 常规运行信息
   * WARN - 可恢复的异常
   * ERROR - 需要干预的错误

== 参见 ==
* Gin中间件机制
* 分布式追踪系统
* 日志聚合工具（ELK Stack）

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