Gin + zap 实现日志链路追踪：RequestID 与 TraceID 完整方案

package logger

import (
	"os"

	"go.uber.org/zap"
	"go.uber.org/zap/zapcore"
	"gopkg.in/natefinished/lumberjack.v2"
)

var defaultLogger *zap.Logger

// InitLogger 初始化全局 Logger
func InitLogger(logPath string, level string) {
	// 日志级别映射
	var zapLevel zapcore.Level
	switch level {
	case "debug":
		zapLevel = zapcore.DebugLevel
	case "info":
		zapLevel = zapcore.InfoLevel
	case "warn":
		zapLevel = zapcore.WarnLevel
	case "error":
		zapLevel = zapcore.ErrorLevel
	default:
		zapLevel = zapcore.InfoLevel
	}

	// 编码器配置
	encoderConfig := zapcore.EncoderConfig{
		TimeKey:        "time",
		LevelKey:       "level",
		NameKey:        "logger",
		CallerKey:      "caller",
		MessageKey:     "msg",
		StacktraceKey:  "stacktrace",
		LineEnding:     zapcore.DefaultLineEnding,
		EncodeLevel:    zapcore.LowercaseLevelEncoder,
		EncodeTime:     zapcore.ISO8601TimeEncoder,
		EncodeDuration: zapcore.SecondsDurationEncoder,
		EncodeCaller:   zapcore.ShortCallerEncoder,
	}

	// 文件输出（使用 lumberjack 做日志切割）
	fileWriter := &lumberjack.Logger{
		Filename:   logPath,
		MaxSize:    128, // 单文件最大 128MB
		MaxBackups: 30,
		MaxAge:     7, // 保留 7 天
		Compress:   true,
	}

	// 构建多输出核心：同时写文件和控制台
	core := zapcore.NewTee(
		zapcore.NewCore(
			zapcore.NewJSONEncoder(encoderConfig),
			zapcore.AddSync(fileWriter),
			zapLevel,
		),
		zapcore.NewCore(
			zapcore.NewConsoleEncoder(encoderConfig),
			zapcore.AddSync(os.Stdout),
			zapLevel,
		),
	)

	defaultLogger = zap.New(core, zap.AddCaller(), zap.AddCallerSkip(1))
}

// GetLogger 获取全局 Logger
func GetLogger() *zap.Logger {
	return defaultLogger
}

package middleware

import (
	"context"

	"github.com/gin-gonic/gin"
	"github.com/google/uuid"
	"go.uber.org/zap"
)

const (
	// TraceIDHeader 从请求头获取上游传递的 TraceID
	TraceIDHeader = "X-Trace-ID"
	// RequestIDHeader 请求 ID 响应头
	RequestIDHeader = "X-Request-ID"
	// LoggerKey 存储在 context 中的 Logger 键
	LoggerKey = "zapLogger"
)

// RequestIDMiddleware 为每个请求注入 RequestID 和 TraceID
func RequestIDMiddleware(baseLogger *zap.Logger) gin.HandlerFunc {
	return func(c *gin.Context) {
		// 优先从请求头获取 TraceID（上游服务传递过来的）
		traceID := c.GetHeader(TraceIDHeader)
		if traceID == "" {
			traceID = uuid.New().String()
		}

		// 每个请求独立生成 RequestID
		requestID := uuid.New().String()

		// 基于全局 Logger 派生子 Logger，自动携带 ID 字段
		reqLogger := baseLogger.With(
			zap.String("trace_id", traceID),
			zap.String("request_id", requestID),
		)

		// 将 ID 写入 gin.Context，方便 handler 中直接获取
		c.Set("trace_id", traceID)
		c.Set("request_id", requestID)

		// 将带有 ID 的 Logger 存入 context
		ctx := context.WithValue(c.Request.Context(), LoggerKey, reqLogger)
		c.Request = c.Request.WithContext(ctx)

		// 在响应头中返回 ID，方便前端或调用方排查问题
		c.Header(RequestIDHeader, requestID)
		c.Header(TraceIDHeader, traceID)

		c.Next()
	}
}

package logger

import (
	"context"

	"go.uber.org/zap"
)

const loggerKey = "zapLogger"

// WithContext 从 context 中取出带有链路信息的 Logger
// 如果 context 中没有，就返回全局默认 Logger
func WithContext(ctx context.Context) *zap.Logger {
	if ctx == nil {
		return defaultLogger
	}
	if ctxLogger, ok := ctx.Value(loggerKey).(*zap.Logger); ok {
		return ctxLogger
	}
	return defaultLogger
}

// InfoCtx 带 context 的 Info 级别日志
func InfoCtx(ctx context.Context, msg string, fields ...zap.Field) {
	WithContext(ctx).Info(msg, fields...)
}

// ErrorCtx 带 context 的 Error 级别日志
func ErrorCtx(ctx context.Context, msg string, fields ...zap.Field) {
	WithContext(ctx).Error(msg, fields...)
}

// WarnCtx 带 context 的 Warn 级别日志
func WarnCtx(ctx context.Context, msg string, fields ...zap.Field) {
	WithContext(ctx).Warn(msg, fields...)
}

// DebugCtx 带 context 的 Debug 级别日志
func DebugCtx(ctx context.Context, msg string, fields ...zap.Field) {
	WithContext(ctx).Debug(msg, fields...)
}

package main

import (
	"net/http"

	"your-project/logger"
	"your-project/middleware"

	"github.com/gin-gonic/gin"
	"go.uber.org/zap"
)

func main() {
	// 初始化 Logger
	logger.InitLogger("./logs/app.log", "info")

	r := gin.New()

	// 注册中间件
	r.Use(middleware.RequestIDMiddleware(logger.GetLogger()))

	// 注册路由
	r.GET("/api/user/:id", GetUser)

	r.Run(":8080")
}

func GetUser(c *gin.Context) {
	ctx := c.Request.Context()
	userID := c.Param("id")

	// 日志会自动带上 trace_id 和 request_id
	logger.InfoCtx(ctx, "开始查询用户信息",
		zap.String("user_id", userID),
	)

	// 调用 service 层，把 ctx 传下去
	user, err := FindUserByID(ctx, userID)
	if err != nil {
		logger.ErrorCtx(ctx, "查询用户失败",
			zap.String("user_id", userID),
			zap.Error(err),
		)
		c.JSON(http.StatusInternalServerError, gin.H{"error": "查询失败"})
		return
	}

	logger.InfoCtx(ctx, "查询用户成功",
		zap.String("user_id", userID),
	)

	c.JSON(http.StatusOK, gin.H{"user": user})
}

package httpclient

import (
	"context"
	"net/http"

	"your-project/middleware"
)

// DoRequest 发起带有链路信息的 HTTP 请求
func DoRequest(ctx context.Context, method, url string) (*http.Response, error) {
	req, err := http.NewRequestWithContext(ctx, method, url, nil)
	if err != nil {
		return nil, err
	}

	// 从 context 中取出 traceID 并注入请求头
	if traceID, ok := ctx.Value("trace_id").(string); ok {
		req.Header.Set(middleware.TraceIDHeader, traceID)
	}

	return http.DefaultClient.Do(req)
}

package middleware

import (
	"time"

	"your-project/logger"

	"github.com/gin-gonic/gin"
	"go.uber.org/zap"
)

// AccessLogMiddleware 记录请求的基础信息
func AccessLogMiddleware() gin.HandlerFunc {
	return func(c *gin.Context) {
		start := time.Now()
		path := c.Request.URL.Path
		query := c.Request.URL.RawQuery

		c.Next()

		cost := time.Since(start)
		ctx := c.Request.Context()

		logger.InfoCtx(ctx, "access_log",
			zap.Int("status", c.Writer.Status()),
			zap.String("method", c.Request.Method),
			zap.String("path", path),
			zap.String("query", query),
			zap.String("ip", c.ClientIP()),
			zap.String("user_agent", c.Request.UserAgent()),
			zap.Duration("cost", cost),
			zap.Int("body_size", c.Writer.Size()),
		)
	}
}