编辑“︁Gin自定义日志格式”︁（章节）

= Gin自定义日志格式 =

== 介绍 ==  
Gin是一个高性能的Go语言Web框架，内置了基础的日志功能。但在实际开发中，开发者往往需要根据业务需求自定义日志格式，例如添加请求ID、时间戳、特定字段或调整输出结构。本文将详细介绍如何在Gin中实现自定义日志格式，涵盖基础配置、高级定制及实际应用场景。

== 基础日志配置 ==  
Gin默认使用`gin.Default()`初始化引擎，其中包含了一个基础的日志中间件（`Logger()`）。若需自定义日志，可通过`gin.LoggerWithFormatter`函数实现。

=== 代码示例：基础自定义格式 ===  
以下示例展示了如何定义一个简单的JSON格式日志：  

<syntaxhighlight lang="go">
package main

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

func main() {
	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,
		)
	}))

	r.GET("/ping", func(c *gin.Context) {
		c.String(200, "pong")
	})

	r.Run(":8080")
}
</syntaxhighlight>

=== 输出示例 ===  
访问`/ping`后，日志输出类似：  
<pre>
127.0.0.1 - [Mon, 01 Jan 2023 12:00:00 UTC] "GET /ping HTTP/1.1 200 1.2ms "Mozilla/5.0" "
</pre>

== 高级定制 ==  
开发者可以通过`LogFormatterParams`结构体访问更多字段，例如：  

* `param.Request.Header`：请求头  
* `param.BodySize`：响应体大小  
* `param.Keys`：Gin上下文中存储的键值对  

=== 实际案例：添加请求ID ===  
在微服务架构中，为日志添加请求ID有助于链路追踪。以下是实现方式：  

<syntaxhighlight lang="go">
r.Use(func(c *gin.Context) {
	// 生成请求ID并存入上下文
	requestID := uuid.New().String()
	c.Set("RequestID", requestID)
	c.Next()
})

r.Use(gin.LoggerWithFormatter(func(param gin.LogFormatterParams) string {
	requestID, _ := param.Keys["RequestID"].(string)
	return fmt.Sprintf("[%s] %s %s %d\n",
		requestID,
		param.Method,
		param.Path,
		param.StatusCode,
	)
}))
</syntaxhighlight>

== 日志格式设计建议 ==  
1. **结构化日志**：优先使用JSON格式，便于日志分析工具处理。  
2. **关键字段**：包含`status_code`、`latency`、`path`和`client_ip`。  
3. **错误隔离**：通过`param.ErrorMessage`单独记录错误信息。  

=== Mermaid 流程图：日志处理流程 ===  
<mermaid>
graph LR
    A[请求进入] --> B[生成请求ID]
    B --> C[记录请求开始时间]
    C --> D[处理业务逻辑]
    D --> E[计算延迟]
    E --> F[格式化日志输出]
</mermaid>

== 数学表达 ==  
日志延迟（Latency）的计算公式：  
<math>
\text{Latency} = T_{\text{end}} - T_{\text{start}}
</math>  
其中<math>T_{\text{start}}</math>和<math>T_{\text{end}}</math>分别代表请求开始和结束的时间戳。

== 总结 ==  
Gin的自定义日志功能允许开发者灵活适配不同场景，从简单的格式调整到复杂的链路追踪均可实现。通过结合中间件和`LogFormatterParams`，能够高效地满足业务需求。

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