1. Sampler 源码全解
1.1 数据结构（sampler.go:28-42）
Go
const (
_numLevels = _maxLevel - _minLevel + 1 // 7 个级别
_countersPerLevel = 4096 // 每级别 4096 个槽位
)
type counter struct {
resetAt atomic.Int64 // 本周期截止时刻（UnixNano）
counter atomic.Uint64 // 周期内计数
}
type counters [_numLevels][_countersPerLevel]counter // 二维定长数组
func (cs *counters) get(lvl Level, key string) *counter {
i := lvl - _minLevel // 行：级别
j := fnv32a(key) % _countersPerLevel // 列：消息哈希
return &cs[i][j]
}设计要点：
- 预分配
7 × 4096个计数器，永不扩容、无 map、无锁------用哈希槽位换确定性内存
- 4096 槽 + fnv32a 意味着不同消息可能撞槽（假阳性）→ 采样是近似的：官方文档明说 "optimized for speed over absolute precision"（150-151 行）
get返回槽位指针，后续全靠原子操作------整个采样路径零锁
1.2 fnv32a：无分配字符串哈希（51-62）
Go
// 从标准库 hash/fnv 抄的，去掉了 []byte(string) 转换的分配
func fnv32a(s string) uint32 {
const ( offset32 = 2166136261; prime32 = 16777619 )
hash := uint32(offset32)
for i := 0; i < len(s); i++ {
hash ^= uint32(s[i])
hash *= prime32
}
return hash
}FNV-1a：一遍扫描、每字节一次异或一次乘法。抄标准库只为直接吃 string（标准库接口收 \[\]byte 会强制分配）。
1.3 IncCheckReset：计数 + 周期重置（64-81）
Go
func (c *counter) IncCheckReset(t time.Time, tick time.Duration) uint64 {
tn := t.UnixNano()
resetAfter := c.resetAt.Load()
if resetAfter > tn {
return c.counter.Add(1) // ① 周期内：原子 +1
}
c.counter.Store(1) // ② 周期到：重置为 1（自己是本周期第一条）
newResetAfter := tn + tick.Nanoseconds()
if !c.resetAt.CompareAndSwap(resetAfter, newResetAfter) {
// ③ CAS 失败：别的 goroutine 抢先重置了（它也 Store(1)）
return c.counter.Add(1) // 所以我接着 +1
}
return 1
}并发场景推演：两个 goroutine 同时发现超周期------A 先 CAS 成功（返回 1），B 的 Store(1) 和 A 的竞争......最坏情况计数略偏差，但绝不会死锁/崩溃，且周期语义大体正确。这是"lock-free + 尽力正确"的典型取舍。
1.4 sampler Core 的 Check（214-229）
Go
func (s *sampler) Check(ent Entry, ce *CheckedEntry) *CheckedEntry {
if !s.Enabled(ent.Level) { return ce }
if ent.Level >= _minLevel && ent.Level <= _maxLevel {
counter := s.counts.get(ent.Level, ent.Message) // 槽位 = (级别, 消息)
n := counter.IncCheckReset(ent.Time, s.tick) // 本周期第 n 条
if n > s.first && (s.thereafter == 0 || (n-s.first)%s.thereafter != 0) {
s.hook(ent, LogDropped)
return ce // ★ 不 AddCore → 丢弃（前 first 条 & 每 thereafter 条放行）
}
s.hook(ent, LogSampled)
}
return s.Core.Check(ent, ce)
}放行公式：n <= first（前 N 条）或 (n-first) % thereafter == 0（之后每 M 条）。first=100, thereafter=100：每秒同消息 1万条 → 记前 100 + 第 200/300/... 条 ≈ 200 条。
其他方法：
With（203-212）：counts 指针共享------所有子 logger 共用同一套计数器（采样是全局语义，不随 With 分裂）
- Hook（121-125）：
SamplerHook选项注册决策回调，SamplingDecision是 bit field（LogDropped=1<<i, LogSampled=1<<1，87-92）
2. 对象池全景
zap 热路径上的对象几乎全部池化，一张表看全：
|---------------------|-----------------------------------|----------------------------|--------------------------------------------|
| 池 | 位置 | 池化对象 | 归还点 |
| _cePool | zapcore/entry.go:35 | CheckedEntry（cores 预分 4 槽） | ce.Write 末尾（292） |
| _jsonPool | zapcore/json_encoder.go:37 | jsonEncoder | putJSONEncoder（EncodeEntry 后/console 用完） |
| _sliceEncoderPool | zapcore/console_encoder.go:31 | sliceArrayEncoder | console 编码完（41-44） |
| _stackPool | internal/stacktrace/stack.go:33 | Stack（storage 预分 64 帧槽） | stack.Free()（logger.go:380 defer） |
| bufferpool | internal/bufferpool | buffer.Buffer（1KiB 起） | buf.Free()（ioCore.Write:100 等） |
| _errArrayElemPool | error.go:28 | errArrayElem | MarshalLogArray 用完（66） |
| buffer.Pool | buffer/pool.go | 各实例池的底层 | --- |
internal/pool 是对 sync.Pool 的泛型封装（pool.New(func() T)），统一 Get/New 语义，且兼容 Go 版本差异。
池化的纪律（值得抄走的经验）：
- 归还前清引用 （
reset()逐元素置 nil）------防内存泄漏
- 池对象不得逃逸到归还之后（CheckedEntry 的 dirty 检测就是防这个）
- 预分配"够用的容量"（cores=4、storage=64、elems=2）------多数场景免扩容
3. stacktrace：栈捕获的优化
internal/stacktrace/stack.go：
Go
// 33-37：池 + 64 帧预分配
var _stackPool = pool.New(func() *Stack {
return &Stack{storage: make([]uintptr, 64)}
})
// Capture（71-109）
func Capture(skip int, depth Depth) *Stack {
stack := _stackPool.Get()
switch depth {
case First: stack.pcs = stack.storage[:1] // caller 用：只要 1 帧，runtime.Callers 快得多
case Full: stack.pcs = stack.storage // 堆栈用：先用 64 帧
}
numFrames := runtime.Callers(skip+2, stack.pcs)
if depth == Full {
pcs := stack.pcs
for numFrames == len(pcs) { // 帧数 == 容量 → 可能被截断
pcs = make([]uintptr, len(pcs)*2) // 容量翻倍重取
numFrames = runtime.Callers(skip+2, pcs)
}
stack.storage = pcs // 深栈场景：池内 storage 被逐步换成大槽
stack.pcs = pcs[:numFrames]
} else {
stack.pcs = stack.pcs[:numFrames]
}
stack.frames = runtime.CallersFrames(stack.pcs)
return stack
}细节：
storage与pcs分离：池归还的是大数组，使用的是其子切片（44-51 注释）
First深度只采 1 帧------caller 标注便宜、堆栈昂贵的分界就在这
- 深栈自适配：连续深栈时池里会沉淀出大 storage，浅栈时不浪费
zap.Stack() 字段走 stacktrace.Take()（同文件），Skip 可调帧起点。
4. zap 为什么快：九大手段总账
|---|-------------------------|-------------------------------------------------------------|--------------------------|
| # | 手段 | 源码锚点 | 效果 |
| 1 | 禁用日志零成本 | logger.go:331 级别前置短路 | 关掉的 Debug 连 Entry 都不构造 |
| 2 | 强类型 Field + Type 分发 | zapcore/field.go:114 switch | 编码零反射 |
| 3 | 零分配字节编码 | buffer/buffer.go + strconv.AppendXxx | 数字/布尔直接进 byte slice |
| 4 | 手写 JSON 转义 | json_encoder.go:509 快路径整段直通 | 纯 ASCII 串零处理；不转义 HTML 字符 |
| 5 | 万物皆池 | 第 2 节的表 | 热路径 ~0 次分配，GC 压力极小 |
| 6 | 上下文预编码 | ioCore.With → EncodeEntry 字节直拷（json_encoder.go:416-419） | With 的字段每条日志只做 memcpy |
| 7 | Check/Write 两段式 | CheckedEntry 收集同意者 | 采样/过滤在写前拦截，白写的活一点不干 |
| 8 | 无锁采样 + 定长槽 | fnv32a + 原子计数 | 高频日志限流本身不成为瓶颈 |
| 9 | caller 按需、单帧优先 | First/Full 深度区分 | 默认路径不采栈，caller 只采 1 帧 |
配套的"不快"取舍（诚实的代价表）：
Sugar：装箱 + Any 分发（2~3 alloc）
Reflect/Any 兜底：反射 + json.Encoder
console编码：fmt.Fprint 反射
- caller/stack：runtime.Callers 微秒级
- 强类型 API 的"啰嗦"就是性能的价格（人体工学 vs 零分配不可兼得）
5. Any 的泛型技巧（field.go:444-481）
有趣的编译器故事：巨型 type switch 会让 Go 编译器给 zap.Any 分配 ~4.8KB 栈空间（每个 case 一份 Field 构造的栈帧）。解法：
Go
type anyFieldC[T any] func(string, T) Field // 包装成"函数类型"
func (f anyFieldC[T]) Any(key string, val any) Field {
v, _ := val.(T)
return f(key, v) // 统一入口，收敛栈帧
}
// 用法：
case int:
c = anyFieldC[int](Int) // 函数引用不装箱
...
return c.Any(key, value) // 只有一处调用点 → 一个栈帧