zap日志 整体架构与数据流

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 枚举                             │
│  装饰器 Core：sampler / tee(multiCore) / hooked /            │
│               levelFilter / lazyWith / nopCore               │
└──────────────────────────┬──────────────────────────────────┘
                           │ 使用
┌──────────────────────────▼──────────────────────────────────┐
│  buffer / internal（性能弹药库）                              │
│  buffer.Buffer + Pool（零分配字节缓冲）                       │
│  internal/bufferpool（全局池）  stacktrace（栈捕获）          │
│  internal/pool（泛型池封装）    exit（安全退出）              │
└─────────────────────────────────────────────────────────────┘

职责边界（对应 doc.go:101-111 "Extending Zap" 一节）：

层	职责	关键认知
zap	好用的 API、预设配置、字段糖函数	只是薄封装，没有它也能用 zapcore 直接写日志
zapcore	4 个核心接口 + 默认实现 + 装饰器	所有扩展点都在这：新编码格式/新输出/新行为=实现接口
buffer+internal	性能原语	对象池、零分配编码、栈捕获

这个分层是依赖倒置的教科书：zap 包 import zapcore，zapcore 对 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.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.Info("hello", zap.String("k","v")) 为例，追踪全流程（行号对应源码）：

记住五个关键对象 ：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（一条日志的元数据） ──▶ CheckedEntry（Entry + 同意写入的 cores + 终止钩子）
   Field（一个键值对指令）──▶ 编码时通过 Field.AddTo(enc) 展开成字节

5. 为什么这样设计？（设计动机）

设计	动机
Check/Write 两段式	Check 先收集所有"愿意写"的 Core 到 CheckedEntry；Write 一次写全。避免"级别判断"和"写出"耦合，也让采样/过滤类 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-111）

6. 源码阅读路线建议

按依赖顺序读（每篇对应本系列文档）：

① 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 换成 ErrorLevel，Check 返回 nil，Write 不执行
// ------ 这就是 logger.Info 在 Info 被禁用时的全部开销

8. 小结

• 三层地图：zap（门面）/ zapcore（内核）/ buffer+internal（弹药）

• 四大接口：LevelEnabler / Encoder / WriteSyncer / Core

• 一条日志的 5 步生命周期：check → CheckedEntry → Write → Encode → Sink，外加两个池的借还

• Check/Write 两段式与"万物皆可装饰"的设计哲学