1. 三层架构┌─────────────────────────────────────────────────────────────┐ │ zap 包门面层 / 用户 API │ │ │ │ Logger ── Sugar() ── SugaredLogger │ │ │ Build() │ │ Config ── Options ── Field构造函数(zap.String/Int/Any...) │ └──────────────────────────┬──────────────────────────────────┘ │ 依赖只依赖接口 ┌──────────────────────────▼──────────────────────────────────┐ │ zapcore 包内核层 / SPI │ │ │ │ Core接口═══ Entry/CheckedEntry ─── Level/LevelEnabler │ │ │ioCore │对象池 │ │ Encoder接口── jsonEncoder / consoleEncoder │ │ WriteSyncer接口── Lock / Multi / Buffered │ │ Field结构体── FieldType 枚举 │ │ 装饰器 Coresampler / tee(multiCore) / hooked / │ │ levelFilter / lazyWith / nopCore │ └──────────────────────────┬──────────────────────────────────┘ │ 使用 ┌──────────────────────────▼──────────────────────────────────┐ │ buffer / internal性能弹药库 │ │ buffer.Buffer Pool零分配字节缓冲 │ │ internal/bufferpool全局池 stacktrace栈捕获 │ │ internal/pool泛型池封装 exit安全退出 │ └─────────────────────────────────────────────────────────────┘职责边界对应doc.go:101-111Extending Zap 一节层职责关键认知zap好用的 API、预设配置、字段糖函数只是薄封装没有它也能用 zapcore 直接写日志zapcore4 个核心接口 默认实现 装饰器所有扩展点都在这新编码格式/新输出/新行为实现接口bufferinternal性能原语对象池、零分配编码、栈捕获这个分层是依赖倒置的教科书zap 包 import zapcorezapcore 对 zap 一无所知。2. 四大核心接口zapcore一切扩展都围绕这 4 个接口// ① 决定记不记zapcore/level.go:227-229 type LevelEnabler interface { Enabled(Level) bool } // ② 决定怎么编码zapcore/encoder.go:455-466 type Encoder interface { ObjectEncoder // AddString/AddInt/... 几十个方法 Clone() Encoder // 派生With 上下文用 EncodeEntry(Entry, []Field) (*buffer.Buffer, error) // 一条日志 → 字节 } // ③ 决定写到哪zapcore/write_syncer.go:32-35 type WriteSyncer interface { io.Writer Sync() error } // ④ 组装以上三者决定整体行为zapcore/core.go:25-45 type Core interface { LevelEnabler // 内嵌能判断级别 With([]Field) Core // 带上下文派生 Check(Entry, *CheckedEntry) *CheckedEntry // 预检我要不要这条日志 Write(Entry, []Field) error // 真正写出 Sync() error // 刷盘 }zapcore.NewCore(enc, ws, enab)core.go:58-64把三个组件拼成最小可用的ioCore——zap 的一切 logger 最终都是这个组合的某种包装。3. 一条日志的完整生命周期以logger.Info(hello, zap.String(k,v))为例追踪全流程行号对应源码业务代码: logger.Info(hello, zap.String(k,v)) │ ▼ ① logger.go:245-249 if ce : log.check(InfoLevel, msg); ce ! nil { // 快路径级别不够直接 nil ce.Write(fields...) } │ ▼ ② check() logger.go:322-422 【慢路径仅级别通过时进入】 ├─ 331: if lvl DPanicLevel !core.Enabled(lvl) → return nil ← 禁用零成本的秘密 ├─ 337-343: 构造 Entry{LoggerName, Time(取自clock), Level, Message} ├─ 343: ce core.Check(ent, nil) │ │ │ ▼ ③ 各 Core 的 Check 链ioCore: core.go:87-92 │ ioCore.Enabled(lvl) 通过 → ce.AddCore(ent, c) ← CheckedEntry 从池里取出 │ 记下我同意写这条日志 │ 装饰器 Core 在这里插入自己的逻辑sampler 决定采样、tee 扇出、... ├─ 347-356: Panic/Fatal/DPanic 级别 → 挂终止钩子(ce.After) ├─ 366: ce.ErrorOutput log.errorOutput ├─ 368-371: 需要 caller/stack 吗 ├─ 379: stacktrace.Capture(...) ← 采集调用栈贵只在需要时 └─ 394-419: ce.Caller 栈第一帧需要则格式化完整堆栈进 ce.Stack │ ▼ ④ ce.Write(fields...) zapcore/entry.go:246-293 ├─ 267: ce.dirty true ← 防复用标记 ├─ 270-272: 执行 before 钩子可改写 Entry/Fields ├─ 275-277: for each core: core.Write(ent, fields) │ │ │ ▼ ⑤ ioCore.Write core.go:94-110 │ ├─ 95: buf enc.EncodeEntry(ent, fields) ← 编码见 13 篇 │ ├─ 99: c.out.Write(buf.Bytes()) ← 写出见 14 篇 │ ├─ 100: buf.Free() ← 缓冲归还池 │ └─ 104-108: 级别 Error → 自动 Sync ├─ 278-286: 写失败 → 错误打到 ce.ErrorOutput ├─ 288-291: 执行 after 钩子panic / os.Exit / goexit └─ 292: putCheckedEntry(ce) ← CheckedEntry 归还池 │ ▼ 完毕Fatal 情况下进程已退出记住五个关键对象Logger门面→Core策略→CheckedEntry预检凭证→Encoder编码→WriteSyncer输出。4. 关键类型关系图┌──────────┐ 1 n ┌─────────────────┐ │ Logger │───core──▶│ Core(接口) │◀──── 实现者 │ logger.go│ └─────────────────┘ ioCore/sampler/tee/ └────┬─────┘ ▲ ▲ hooked/lazyWith/... │Sugar()/Desugar() │ │装饰 ┌──────▼───────┐ ┌─────┴───┴────┐ │SugaredLogger │ │ ioCore │ │ sugar.go │ │ core.go │ └──────────────┘ │ ┌──────────┐ │ │ │Encoder │ │ ──▶ jsonEncoder / consoleEncoder │ ├──────────┤ │ │ │WriteSyncr│ │ ──▶ locked/multi/buffered/file... │ ├──────────┤ │ │ │LevelEnabr│ │ ──▶ Level / AtomicLevel / Func │ └──────────┘ │ └──────────────┘ Entry一条日志的元数据 ──▶ CheckedEntryEntry 同意写入的 cores 终止钩子 Field一个键值对指令──▶ 编码时通过 Field.AddTo(enc) 展开成字节5. 为什么这样设计设计动机设计动机Check/Write 两段式Check 先收集所有愿意写的 Core 到 CheckedEntryWrite 一次写全。避免级别判断和写出耦合也让采样/过滤类 Core 能在 Check 阶段拦截Core 是接口而非结构体装饰器模式遍地开花sampler过滤tee扇出hooked观测lazyWith延迟……组合优于配置Encoder 独立于 Core同一份 Entry 可输出 json/console/任意格式多个 Core 可共享编码逻辑Field 是指令不是数据zap.Int只打包 {key,type,integer}不发生任何编码编码推迟到 Write 且按 Type 分发——零反射零分配的根源万物皆池CheckedEntry、jsonEncoder、buffer、stacktrace、errArrayElem 全部池化——热路径几乎零 GC 压力zap 包依赖 zapcore 而非反向库作者可只用 zapcore 造自己的轮子doc.go:110-1116. 源码阅读路线建议按依赖顺序读每篇对应本系列文档① zapcore/level.go 15 分钟类型如此简单int8 Enabled ② zapcore/field.go 30 分钟FieldType 枚举 Field.AddTo 的 switch ③ zapcore/core.go 15 分钟接口 ioCore 百行实现 ④ zapcore/entry.go 30 分钟Entry/CheckedEntry 池 ⑤ logger.go 45 分钟★ 重点check() 慢路径 ⑥ sugar.go 30 分钟sweetenFields ⑦ zapcore/encoder.go json_encoder.go 60 分钟★ 重点 ⑧ zapcore/write_syncer.go sink.go 30 分钟 ⑨ 装饰器sampler/tee/hook/increase_level/lazy_with各 15 分钟 ⑩ buffer/ internal/ 30 分钟性能原语建议用 IDE 的Go to Definition跟着 ⑤ 的调用链走一遍比看十篇文章都有效。7. 动手实验// 实验 1直接用 zapcore不用 zap 包——证明 zap 只是门面 package main import ( os go.uber.org/zap/zapcore ) func main() { enc : zapcore.NewJSONEncoder(zapcore.EncoderConfig{ MessageKey: msg, LevelKey: level, EncodeLevel: zapcore.LowercaseLevelEncoder, EncodeTime: zapcore.EpochTimeEncoder, }) core : zapcore.NewCore(enc, os.Stdout, zapcore.InfoLevel) ent : zapcore.Entry{Level: zapcore.InfoLevel, Message: bare zapcore} if ce : core.Check(ent, nil); ce ! nil { ce.Write(zapcore.Field{Key: k, Type: zapcore.StringType, String: v}) } // {level:info,ts:...,msg:bare zapcore,k:v} } // 实验 2观察禁用级别的零成本 // 把上面 Level 换成 ErrorLevelCheck 返回 nilWrite 不执行 // —— 这就是 logger.Info 在 Info 被禁用时的全部开销8. 小结三层地图zap门面/ zapcore内核/ bufferinternal弹药四大接口LevelEnabler / Encoder / WriteSyncer / Core一条日志的 5 步生命周期check → CheckedEntry → Write → Encode → Sink外加两个池的借还Check/Write 两段式与万物皆可装饰的设计哲学