logger —— 多 Core 装配:控制台 + info/warn/error/audit/access 分文件
zap 之上的一层薄封装:把"主日志 / 访问日志 / 审计日志"拆成互不干扰的落盘通道, 并把按天分目录 + 按大小滚动 + 压缩 + 过期清理收在一个 rotator 里。
功能
logger 解决四件事:
- 多 Core 装配 —— 一个
*zap.Logger,tee 出多个 core:- 控制台(stdout)仅在
env=dev/env=test挂载 info.log(level ≥ info)、warn.log(level ≥ warn)、error.log(level ≥ error)audit.log、access.log—— 独立通道,按 logger 名路由
- 控制台(stdout)仅在
- 落盘策略(
TimeRotator):按天分目录 → 按大小滚动 → 可选 gzip → 过期目录清理- 同目录历史文件按
max_backups保留。
- 同目录历史文件按
- 通道路由(
route.go):Audit()/Access()拿到具名 logger,只写自己那一份文件, 结构化字段原样带过去(path / method / status / user 都在)。 - 退出语义:
SyncFlush()(fsync 到盘)+Close()(关文件句柄),rotator 关掉后仍可自愈复用。
不解决:脱敏不在本包(在 pkg/desensitize + middleware/audit_capture.go);
链路追踪 / 指标也不在(在 otelx / metricsx)。
配置
yaml 侧(logger: 块)
logger:
level: info # debug / info / warn / error
format: json # json / console
dir: logs
max_size_mb: 100
max_backups: 30
max_age_days: 90
compress: true
env: dev
viper 里没有 logger.* 的 SetDefault —— 兜底值全在 logger.New 内部。
| 键 | 类型 | yaml 示例值 | 代码兜底 | 说明 |
|---|---|---|---|---|
level |
string | info |
"" ⇒ 等价 info |
只作用于 stdout core,见「注意事项」。文件 core 的级别是写死的 |
format |
string | json |
"" ⇒ 等价 json |
json / console。audit / access 恒为 JSON,不受它影响 |
dir |
string | logs |
"" → logs |
日志根目录;实际文件落在 ${dir}/${YYYY-MM-DD}/<level>.log |
max_size_mb |
int | 100 |
0 → 100 |
单文件大小上限,超过即滚动 |
max_backups |
int | 30 |
0 → 30 |
同一日期目录内保留的历史文件数(按 mtime 删最早的) |
max_age_days |
int | 90 |
0 → 90 |
按本地日历天保留的天数 |
compress |
bool | true |
false(env=prod 时强制 true) |
滚动后异步 gzip。prod 下写 false 会被强制改回 true |
env |
string | dev |
"" ⇒ 不挂 stdout core |
dev/test 挂 stdout core;prod 强制开启压缩 |
代码侧(构造选项)
logger.Config 字段与 yaml 一一对应(Level / Format / Dir / MaxSizeMB /
MaxBackups / MaxAgeDays / Compress / Env),兜底值如上表。
log, err := logger.New(logger.Config{
Level: "info",
Format: "json",
Dir: "logs",
MaxSizeMB: 100,
MaxBackups: 30,
MaxAgeDays: 90,
Compress: true,
Env: "prod",
})
logger.Default = log // 全局注入
zap.ReplaceGlobals(log) // 第三方库走 zap.L()
使用方法
三个通道
// 主日志:进 info.log / warn.log / error.log(按级别分流)
log.Info("服务启动", zap.String("app", "示例"), zap.Int("port", 8080))
// 访问日志:只进 access.log(恒 JSON)
logger.Access().Info("GET /rapid-admin/v1/system/users",
zap.String("method", "GET"),
zap.String("path", "/rapid-admin/v1/system/users"),
zap.Int("status", 200),
zap.Int64("cost_ms", 12))
// 审计日志:只进 audit.log(恒 JSON)
logger.Audit().Info("删除用户",
zap.Uint64("actor_id", 1001),
zap.String("target", "sys_user"),
zap.Uint64("target_id", 2002))
logger.L() 是全局 logger 的快捷访问;logger.Default 还没注入时它返
zap.NewNop()(静默不输出)。
错误级别自带堆栈
log.Error("数据库写入失败", zap.String("table", "sys_user"), zap.Error(os.ErrPermission))
zap.AddStacktrace(zap.ErrorLevel) 是 New 里写死的 ⇒ error 及以上自动带 stacktrace。
初始化失败不想处理 error 时
logger.Must(l, err) // err != nil ⇒ panic("init logger: ...")
退出前:刷盘 + 关句柄
defer func() {
_ = logger.SyncFlush() // 1. fsync 所有 rotator
_ = log.Sync() // 2. 刷 tee
_ = logger.Close() // 3. 关文件句柄
}()
完整示例见 examples/logger/main.go。
注意事项
- ⚠️
logger.level只管 stdout core,不管文件。三个文件 core 的级别写死在logger.go:info.log≥ Info、warn.log≥ Warn、error.log≥ Error。 dev 下level: debug能看到 debug 打到 stdout;但 prod 根本没有 stdout core ⇒level: debug在生产完全无效,info.log里永远不会有 debug 行。 想在生产看 debug,得改代码里的 core 级别,不是改 yaml。 - ⚠️ audit / access 是 core 级路由,不是 hook。zap 的 hook 签名是
func(zapcore.Entry) error,拿不到每次调用的结构化字段 ——zapcore.hooked.Write(ent, _ []Field)把 fields 直接丢了。 早期版本因此让 audit.log / access.log 里 path / method / status / user 全部消失。 现在改用namedCore(route.go):Check阶段按LoggerName选核心,Write(ent, fields)时字段原样带过去。 - ⚠️ 空名 logger 两条独立通道都不进。只有
logger.Audit()/logger.Access()(或自己Named("audit")/Named("access"))才会路由过去;log.Info(...)走的是三个文件 core。路由规则是精确等值匹配。 - ⚠️ audit / access 恒为 JSON,
format: console也不影响它们 —— 这两份是给机器读的(审计检索 / 访问日志分析),人读的 console 只给 dev/test。 - ⚠️
log.Sync()刷不到 audit / access。zap.Logger.Sync()只刷 tee 里的 core; 两个独立 rotator 不在 tee 里 ⇒ 进程退出时最后几条审计/访问日志可能丢。logger.SyncFlush()专门兜这两个。退出三步的顺序不能改:SyncFlush()→log.Sync()→Close()。写成三个独立defer会因 LIFO 把顺序搞反 (关句柄抢在刷盘前面跑)。 - ⚠️
Close()之后 rotator 仍可自愈:下次Write发现currentFile == nil会重新 rotate 打开。但Write的判据必须是currentDay != today || currentFile == nil—— 少了后半边,重开文件失败后currentFile == nil但currentDay仍是今天 ⇒ 跳过 rotate ⇒ 每次写都返ErrInvalid(os.File对 nil 接收者不 panic)⇒ 日志从此静默全丢,无任何告警。 - ⚠️ 过期目录按日期串比较,不解析成
time.Time。time.Parse("2006-01-02", …)对只有日期的布局按 UTC 解析,而 cutoff 来自本地时间 ⇒ 边界行为随"当天几点"漂移 (东八区 vs 美西最多差 14 小时)。现在的规则(expiredDir):目录名<= cutoff(今天 − maxAge 天)即删 ⇒ 今天、昨天、……、前 (maxAge-1) 天保留。 名字解析不出日期的目录不删(别的子目录不能被误伤)。 - ⚠️
max_backups是"同一天目录内"的计数,不是全局备份数。 匹配规则:文件名以<level>.开头且以.log结尾 ——rotateSize产出的info.150405.000.log匹配得上。 - ⚠️ 压缩是异步的(
go compressFile(...))⇒ 进程退出瞬间可能还有.gz没写完;compressFile成功后才删源文件。 - ⚠️
logger.L()在Default未注入时返 Nop logger —— 静默不输出。 所以 init 阶段的告警会被丢掉(sonyflake因此把机号告警推迟到第一次Next())。 - ⚠️ 本包没有脱敏钩子。审计日志里的请求体/查询串脱敏在
pkg/desensitize+internal/api/middleware/audit_capture.go里做, 由 audit 中间件调,不在 logger 里。
相关
- 源码:
internal/pkg/logger/(logger.go装配 /rotator.go滚动 /route.go通道路由) - 可运行示例:
examples/logger/main.go——go run ./examples/logger - 脱敏词表 → desensitize
- 链路追踪(header 同源) → otelx
- 指标 → metricsx