GolangWeb日志记录技巧分享

在 Go Web 开发中，日志不是简单的“打印信息”，而是保障系统可观测性与故障快速定位的核心基础设施；必须摒弃标准 log 包的并发不安全、无缓冲、不轮转等缺陷，转而采用 zap 等高性能结构化日志库，结合中间件精准采集 method、path、status、duration_ms、真实 IP 和 user_agent 等关键字段，通过 lumberjack 实现磁盘安全的自动轮转，并启用异步写入以避免阻塞请求——同时务必注意 realIP 解析的代理头校验、responseWriter 包装捕获准确状态码、进程退出前调用 Sync 防止日志丢失，因为真正影响线上排查效率的，往往不是日志怎么打，而是日志是否全、是否可信、是否拖慢服务。

用 log 包直接写 HTTP 请求日志会丢数据

Go 标准库的 log 默认输出到 os.Stderr，且无缓冲控制和并发保护。在高并发 Web 场景下，多个 goroutine 同时调用 log.Println 可能导致日志行错乱、截断甚至丢失。

• 避免直接在 http.HandlerFunc 里用 log.Printf 打请求日志
• 必须加锁或改用支持并发写入的日志库（如 zap、zerolog）
• 若坚持用标准库，至少将输出重定向到带缓冲的 os.File，并设置 log.SetOutput

中间件里记录结构化请求日志的关键字段不能少

HTTP 日志不是记“谁访问了”，而是要支撑问题定位：响应时间、状态码、路径参数、客户端 IP、User-Agent、错误上下文都得有。裸字符串拼接难解析，建议用结构体序列化为 JSON。

• 必采字段：method、path、status、duration_ms、remote_ip（注意 X-Forwarded-For 处理）、user_agent
• 推荐用 time.Now() 记开始时间，defer 算耗时，别依赖 ResponseWriter 的 Hook（它不保证执行）
• 不要在日志里打印完整 body —— 有安全与性能风险；如需调试，单独加开关控制

zap 配合 gin 或 net/http 的最小可行日志中间件

zap 是目前 Go 生产环境最常用的高性能日志库，但它的 SugaredLogger 不是开箱即用的 HTTP 中间件，需要手动封装。

func Logger(zapLog *zap.Logger) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			start := time.Now()
			ww := &responseWriter{ResponseWriter: w, statusCode: 200}
			next.ServeHTTP(ww, r)

			zapLog.Info("http request",
				zap.String("method", r.Method),
				zap.String("path", r.URL.Path),
				zap.Int("status", ww.statusCode),
				zap.Float64("duration_ms", float64(time.Since(start))/float64(time.Millisecond)),
				zap.String("ip", realIP(r)),
			)
		})
	}
}

• responseWriter 要包装 http.ResponseWriter 才能捕获真实 status code
• realIP 函数需检查 X-Forwarded-For 和 X-Real-Ip，但别盲目信任代理头
• 生产环境务必用 zap.NewProduction()，开发可用 zap.NewDevelopment()

日志轮转和异步写入不是可选项，是上线前必须确认的点

不轮转的日志文件会撑爆磁盘；同步刷盘在高 QPS 下会拖慢整个 HTTP 响应。这两项标准库 log 都不支持，zap 也需额外配置。

• 轮转推荐用 lumberjack：传给 zapcore.AddSync 的 io.Writer 必须是它实例化的 WriteSyncer
• 异步写入靠 zap.NewCore + zapcore.NewTee 或直接用 zap.NewAsync（注意：它会丢最后几条日志，进程退出前要 Sync()）
• 日志路径别硬编码，通过 flag 或 env 注入，比如 --log-dir=/var/log/myapp

真正麻烦的从来不是“怎么打日志”，而是“日志是否全、是否可查、是否影响服务”。轮转策略配错、异步未 Sync、IP 解析逻辑漏掉内网代理——这些地方一出问题，排查成本远高于写日志本身。

以上就是《GolangWeb日志记录技巧分享》的详细内容，更多关于的资料请关注golang学习网公众号！