首页 > Golang > Go教程

Golang结构化日志中间件实现详解

时间：2025-08-16 23:51:57 323浏览收藏

在Go语言开发中，服务可观测性至关重要，结构化日志是基础。本文深入探讨如何利用高性能的 `uber-go/zap` 库，实现一个高效且实用的Golang结构化日志中间件。该中间件能够自动记录HTTP请求的关键信息，包括请求方法、路径、客户端IP、响应状态码、处理耗时以及User-Agent等，并以JSON格式输出，方便与ELK、Loki等日志收集系统对接，提升搜索和分析效率。文章提供了详细的代码示例，展示了如何包装`responseWriter`捕获状态码，以及如何根据状态码级别输出不同类型的日志。此外，还探讨了可选优化方案，例如排除健康检查路径、集成链路追踪等，助力开发者构建更健壮、可观测性更强的Go服务。

答案：通过zap实现Go语言结构化日志中间件，记录请求方法、路径、IP、状态码、耗时等信息并以JSON格式输出，结合responseWriter包装捕获状态码，根据级别输出日志，支持客户端IP解析及可选优化如排除健康检查路径、链路追踪等，提升服务可观测性。

怎样用Golang记录访问日志结构化日志中间件实现

在Go语言开发中，记录访问日志是服务可观测性的基础。使用结构化日志（如JSON格式）能更好地对接日志收集系统（如ELK、Loki等），便于搜索和分析。通过编写一个结构化日志中间件，可以自动记录每次HTTP请求的关键信息。

结构化日志中间件设计目标

一个实用的访问日志中间件应记录以下信息：

请求方法（GET、POST等）
请求路径和查询参数
客户端IP地址
响应状态码
处理耗时
User-Agent等关键请求头

日志输出为JSON格式，便于后续处理。

使用 zap 实现结构化日志中间件

uber-go/zap 是高性能的结构化日志库，适合生产环境。以下是基于 zap 的中间件实现：

package main

import (
    "net"
    "net/http"
    "net/http/httputil"
    "strings"
    "time"

    "github.com/ulule/limiter/v3"
    "go.uber.org/zap"
)

// Logger 中间件，记录结构化访问日志
func Logger(logger *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()

            // 获取客户端IP
            ip := getRealIP(r)

            // 包装 ResponseWriter 以捕获状态码
            rw := &responseWriter{ResponseWriter: w, statusCode: http.StatusOK}

            // 调用下一个处理器
            next.ServeHTTP(rw, r)

            // 构建日志字段
            fields := []zap.Field{
                zap.String("method", r.Method),
                zap.String("path", r.URL.Path),
                zap.String("query", r.URL.RawQuery),
                zap.String("ip", ip),
                zap.String("user_agent", r.Header.Get("User-Agent")),
                zap.Int("status", rw.statusCode),
                zap.Duration("duration", time.Since(start)),
            }

            // 根据状态码选择日志级别
            if rw.statusCode >= 500 {
                logger.Error("server error", fields...)
            } else if rw.statusCode >= 400 {
                logger.Warn("client error", fields...)
            } else {
                logger.Info("access", fields...)
            }
        })
    }
}

// 获取真实客户端IP
func getRealIP(r *http.Request) string {
    xff := r.Header.Get("X-Forwarded-For")
    if xff != "" {
        i := strings.Index(xff, ",")
        if i > 0 {
            return strings.TrimSpace(xff[:i])
        }
        return xff
    }

    xrip := r.Header.Get("X-Real-IP")
    if xrip != "" {
        return xrip
    }

    ip, _, _ := net.SplitHostPort(r.RemoteAddr)
    return ip
}

// 包装 ResponseWriter 以捕获状态码
type responseWriter struct {
    http.ResponseWriter
    statusCode int
}

func (rw *responseWriter) WriteHeader(code int) {
    rw.statusCode = code
    rw.ResponseWriter.WriteHeader(code)
}

在项目中使用中间件

将日志中间件集成到HTTP服务中：

func main() {
    // 创建 zap 日志实例
    logger, _ := zap.NewProduction()
    defer logger.Sync()

    mux := http.NewServeMux()
    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello, World!"))
    })

    // 应用日志中间件
    handler := Logger(logger)(mux)

    http.ListenAndServe(":8080", handler)
}

运行后，访问服务会输出类似以下的JSON日志：

{
  "level":"info",
  "ts":1712345678.123,
  "caller":"main.go:50",
  "msg":"access",
  "method":"GET",
  "path":"/",
  "query":"",
  "ip":"127.0.0.1",
  "user_agent":"curl/7.68.0",
  "status":200,
  "duration":0.000123
}

可选优化

可根据实际需求扩展功能：

排除健康检查路径（如 /health）减少日志噪音
记录请求体或响应体（注意性能和隐私）
结合 context 记录 trace ID 实现链路追踪
按日志级别输出到不同文件

基本上就这些。一个简洁高效的结构化日志中间件能显著提升服务的可观测性，zap 提供了性能和功能的平衡，适合大多数Go项目使用。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~

Http请求 Go 中间件 ZAP 结构化日志