// Package logger 结构化日志组件:zap + lumberjack(Day 5)。 // 支持 JSON/Console 格式,stdout/文件双通道输出,文件按大小/天数滚动切割与压缩; // 通过 logger.Init 初始化全局实例,业务代码使用 logger.L() 获取。 package logger import ( "errors" "fmt" "os" "path/filepath" "strings" "go.uber.org/zap" "go.uber.org/zap/zapcore" "gopkg.in/natefinch/lumberjack.v2" ) // std 全局日志实例(Init 后可用;未 Init 时降级为 Nop)。 var std *zap.Logger = zap.NewNop() // stdLevel 全局动态级别(Day 12 热更新:app 通过 logger.Level().SetLevel 调整)。 var stdLevel = zap.NewAtomicLevelAt(zap.InfoLevel) // FileOptions 日志文件滚动切割配置(对应 config.Log.File)。 type FileOptions struct { Path string `mapstructure:"path"` // 文件路径 MaxSizeMB int `mapstructure:"max_size_mb"` // 单文件最大 MB,超出切割 MaxAgeDays int `mapstructure:"max_age_days"` // 旧文件保留天数 MaxBackups int `mapstructure:"max_backups"` // 旧文件最大个数 Compress bool `mapstructure:"compress"` // 是否 gzip 压缩旧文件 } // Options 日志配置(对应 config.Log)。 type Options struct { Level string // debug | info | warn | error Format string // json | console Output []string // stdout / file(可同时) File FileOptions } // Init 按配置构建并安装全局日志实例(级别可经 Level() 动态调整)。 func Init(opt Options) error { lg, level, err := NewWithLevel(opt) if err != nil { return err } std, stdLevel = lg, level return nil } // L 返回全局日志实例。 func L() *zap.Logger { return std } // Level 返回全局动态级别(热更新入口:SetLevel 即时生效,无需重启)。 func Level() zap.AtomicLevel { return stdLevel } // Sync 刷新缓冲(进程退出前调用;文件通道确保落盘)。 func Sync() { _ = std.Sync() } // New 构造独立日志实例(测试或特殊场景使用)。 func New(opt Options, opts ...zap.Option) (*zap.Logger, error) { level, err := parseLevel(opt.Level) if err != nil { return nil, err } return newWithCoreLevel(opt, level, opts...) } // NewWithLevel 同 New,并返回动态级别句柄(配置热更新时 SetLevel 即时生效)。 func NewWithLevel(opt Options, opts ...zap.Option) (*zap.Logger, zap.AtomicLevel, error) { level, err := parseLevel(opt.Level) if err != nil { return nil, zap.AtomicLevel{}, err } atomic := zap.NewAtomicLevelAt(level) lg, err := newWithCoreLevel(opt, atomic, opts...) if err != nil { return nil, zap.AtomicLevel{}, err } return lg, atomic, nil } // newWithCoreLevel 以指定 Core Level 构造(复用 New 的装配逻辑)。 func newWithCoreLevel(opt Options, level zapcore.LevelEnabler, opts ...zap.Option) (*zap.Logger, error) { encoderCfg := zapcore.EncoderConfig{ TimeKey: "ts", LevelKey: "level", NameKey: "logger", CallerKey: "caller", MessageKey: "msg", StacktraceKey: "stack", LineEnding: zapcore.DefaultLineEnding, EncodeLevel: zapcore.LowercaseLevelEncoder, EncodeTime: zapcore.ISO8601TimeEncoder, EncodeDuration: zapcore.MillisDurationEncoder, EncodeCaller: zapcore.ShortCallerEncoder, } var encoder = zapcore.NewJSONEncoder(encoderCfg) if opt.Format == "console" { encoder = zapcore.NewConsoleEncoder(encoderCfg) } var cores []zapcore.Core for _, out := range opt.Output { switch strings.ToLower(strings.TrimSpace(out)) { case "stdout": cores = append(cores, zapcore.NewCore(encoder, zapcore.Lock(os.Stdout), level)) case "file": if opt.File.Path == "" { return nil, errors.New("log.output 含 file 但 log.file.path 为空") } if err := ensureWritable(opt.File.Path); err != nil { // 降级:目录不可写时跳过文件通道,避免持续 write error 刷屏 fmt.Fprintf(os.Stderr, "[logger] WARN 日志文件 %s 不可写(%v),已降级为仅 stdout 输出\n", opt.File.Path, err) continue } w := zapcore.AddSync(&lumberjack.Logger{ Filename: opt.File.Path, MaxSize: opt.File.MaxSizeMB, MaxAge: opt.File.MaxAgeDays, MaxBackups: opt.File.MaxBackups, Compress: opt.File.Compress, }) cores = append(cores, zapcore.NewCore(encoder, w, level)) case "": // 跳过空项 default: return nil, fmt.Errorf("未知日志输出通道: %q(可选 stdout/file)", out) } } if len(cores) == 0 { // file 全部降级时兜底 stdout,保证至少有日志 cores = append(cores, zapcore.NewCore(encoder, zapcore.Lock(os.Stdout), level)) } opts = append(opts, zap.AddCaller()) // 输出调用位置,便于排障 return zap.New(zapcore.NewTee(cores...), opts...), nil } // parseLevel 解析日志级别字符串。 func parseLevel(s string) (zapcore.Level, error) { switch strings.ToLower(strings.TrimSpace(s)) { case "debug": return zapcore.DebugLevel, nil case "info", "": return zapcore.InfoLevel, nil case "warn": return zapcore.WarnLevel, nil case "error": return zapcore.ErrorLevel, nil default: return zapcore.InfoLevel, fmt.Errorf("未知日志级别: %q(可选 debug/info/warn/error)", s) } } // ensureWritable 探测日志文件可写性:自动建目录并以追加模式试开一次。 // 不可写返回错误(触发降级),成功则关闭句柄交由 lumberjack 接管。 func ensureWritable(path string) error { dir := filepath.Dir(path) if err := os.MkdirAll(dir, 0o755); err != nil { return err } f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644) if err != nil { return err } return f.Close() }