4. 日志系统设计：基于 zap 的日志封装、分级、结构化与轮转归档

在支付中间件中，日志不是辅助工具，而是核心可观测性基础设施。每一笔交易的请求轨迹、状态变更、异常堆栈、性能耗时都需要被精确记录。Go 生态中 zap 以“零分配”和极致性能著称，但原生 zap 的 API 对业务层不够友好。本章将围绕 zap 做一层工程封装，解决日志分级、结构化、动态级别切换、文件轮转与归档等落地问题。

4.1 为什么选择 zap 作为底层库

4.2 日志分级与动态级别切换

支付系统日志通常分为 6 级，但业务层只暴露 4 级：Debug、Info、Warn、Error。底层保留 DPanic 和 Fatal 用于内部异常。

// 业务层日志接口
type Logger interface {
    Debug(msg string, fields ...Field)
    Info(msg string, fields ...Field)
    Warn(msg string, fields ...Field)
    Error(msg string, fields ...Field)
    With(fields ...Field) Logger
}

// 内部级别映射
const (
    LevelDebug = zap.DebugLevel
    LevelInfo  = zap.InfoLevel
    LevelWarn  = zap.WarnLevel
    LevelError = zap.ErrorLevel
)

动态级别切换通过 zap.AtomicLevel 实现，支持运行时通过配置中心或 API 热更新，无需重启进程。

// 初始化时绑定 AtomicLevel
atom := zap.NewAtomicLevel()
atom.SetLevel(zap.InfoLevel)

// 运行时切换（例如通过 HTTP 接口）
func SetLogLevel(level string) error {
    lvl, err := zap.ParseLevel(level)
    if err != nil {
        return err
    }
    atom.SetLevel(lvl)
    return nil
}

4.3 结构化日志与支付字段规范

结构化日志的核心是让每条日志成为可被机器解析的键值对集合。支付中间件强制要求以下公共字段出现在每条日志中：

// 封装结构化日志写入
func (l *zapLogger) Info(msg string, fields ...Field) {
    // 自动注入公共字段
    commonFields := []zap.Field{
        zap.String("trace_id", l.traceID),
        zap.String("span_id", l.spanID),
        zap.String("order_no", l.orderNo),
        zap.String("channel", l.channel),
        zap.Int64("amount", l.amount),
        zap.Int64("cost_ms", l.costMS),
        zap.String("env", l.env),
    }
    allFields := append(commonFields, fields...)
    l.sugaredLogger.Infow(msg, allFields...)
}

4.4 日志轮转与归档策略

支付日志文件增长极快，单节点单日日志量可达 10GB 以上。必须使用 lumberjack 作为 zap 的 WriteSyncer，实现按大小轮转和按时间归档。

// lumberjack 配置
logWriter := &lumberjack.Logger{
    Filename:   "/var/log/payment/payment.log",   // 日志文件路径
    MaxSize:    500,                               // 每个文件最大 500MB
    MaxBackups: 30,                                // 保留最近 30 个文件
    MaxAge:     7,                                 // 保留最近 7 天
    Compress:   true,                              // 是否压缩归档
    LocalTime:  true,                              // 使用本地时间
}

// 将 lumberjack 作为 zap 的 WriteSyncer
core := zapcore.NewCore(
    encoder,
    zapcore.AddSync(logWriter),
    atom,
)

4.5 日志系统整体架构

下图展示了基于 zap 的支付日志系统完整链路：从业务调用到最终归档。

4.6 完整封装示例

以下代码展示了如何将上述所有要素整合为一个可复用的日志初始化函数：

func NewPaymentLogger(cfg *LogConfig) (Logger, error) {
    // 1. 编码器配置
    encoderConfig := zap.NewProductionEncoderConfig()
    encoderConfig.TimeKey = "timestamp"
    encoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
    encoderConfig.EncodeLevel = zapcore.CapitalLevelEncoder

    // 2. 选择输出格式（JSON 用于生产，Console 用于开发）
    var encoder zapcore.Encoder
    if cfg.Format == "json" {
        encoder = zapcore.NewJSONEncoder(encoderConfig)
    } else {
        encoder = zapcore.NewConsoleEncoder(encoderConfig)
    }

    // 3. 动态级别
    atom := zap.NewAtomicLevel()
    atom.SetLevel(cfg.Level)

    // 4. 文件轮转
    logWriter := &lumberjack.Logger{
        Filename:   cfg.FilePath,
        MaxSize:    cfg.MaxSize,
        MaxBackups: cfg.MaxBackups,
        MaxAge:     cfg.MaxAge,
        Compress:   cfg.Compress,
    }

    // 5. 多输出：文件 + 控制台（可选）
    ws := zapcore.NewMultiWriteSyncer(
        zapcore.AddSync(logWriter),
        zapcore.AddSync(os.Stdout),
    )

    // 6. 构建 core
    core := zapcore.NewCore(encoder, ws, atom)

    // 7. 添加调用者信息
    logger := zap.New(core, zap.AddCaller(), zap.AddCallerSkip(1))

    return &zapLogger{
        sugaredLogger: logger.Sugar(),
        env:           cfg.Env,
    }, nil
}

4.7 日志系统关键设计决策

• 统一接口 vs 直接使用 zap： 业务层只依赖 Logger 接口，底层实现可随时替换，方便单元测试 mock。
• 同步 vs 异步写日志： 支付核心链路使用同步写，保证日志不丢失；非核心链路可异步写，但需设置缓冲区大小和丢日志告警。
• 日志采样： 对于 Debug 和 Info 级别的高频日志（如健康检查），可配置采样率，避免磁盘 IO 成为瓶颈。
• 错误日志告警： Error 级别日志必须对接告警系统，支付中间件要求 Error 日志 1 分钟内触发告警。