Field 系统：类型安全与零反射

Field 是 zap 字段系统的核心类型。它只有 16 字节，却承担了「携带任意类型数据且不触发反射」的重任。

16 字节的结构

type Field struct {
	Key       string
	Type      FieldType
	Integer   int64
	String    string
	Interface interface{}
}

Field 用联合体式的内存布局：Integer、String、Interface 三个字段按类型取用其一。由于 string 和 interface{} 都是指针加长度的组合，整个结构紧凑且可内联。

强类型构造器

zap 包为每种类型提供构造器，它们做的事情出奇地简单——填结构体：

func Int(key string, val int) Field {
	return Field{Key: key, Type: IntType, Integer: int64(val)}
}

func String(key, val string) Field {
	return Field{Key: key, Type: StringType, String: val}
}

没有反射、没有分配。调用时编译器直接内联，zap.Int("n", 42) 的成本接近零。

编码时的类型分派

字段编码时，Encoder 根据 Type 走 switch 分支，而不是反射：

func (enc *jsonEncoder) addField(key string, f Field) {
	switch f.Type {
	case IntType:
		enc.AddInt(key, int(f.Integer))
	case StringType:
		enc.AddString(key, f.String)
	case TimeType:
		enc.AddTime(key, time.Unix(0, f.Integer))
	case ReflectType:
		enc.AddReflected(key, f.Interface) // 唯一可能触发反射的分支
	default:
		enc.addUnsupportedType(key, f)
	}
}

ReflectType 是唯一的慢车道——zap.Any() 默认走这里。

为什么接口字段是例外

zap.Any("req", httpRequest{...}) // 触发反射

而：

zap.String("method", req.Method) // 零成本

zap 的哲学是：结构化的价值在于可查询。所有字段最终都要变成可解析的键值对，强类型让这条路径没有惊喜。

lazy：把昂贵的求值推迟

字段的值本身可能很贵——比如读一个监控指标。zap.Lazy 提供延迟求值：

func Lazy(key string, f func() Field) Field {
	return Field{Key: key, Type: LazyType, Interface: lazy{key: key, f: f}}
}

只有当日志确定要写入时（通过了级别过滤与采样），lazy 的闭包才会被调用。这让「构造字段的代价」与「丢弃日志的收益」彻底解耦。

💡 经验法则： 如果构造某个字段需要系统调用、网络请求或大对象遍历，就用 zap.Lazy 包一层。

小结

Field 系统的设计可以用三个词概括：紧凑布局、静态分派、延迟求值。它让「结构化」不再意味着「反射」，也让 zap 的高性能有了最底层的支撑。