结构化日志值

结构化日志真正让人困惑的，往往不是字段太多，而是“没有值”和“值就是 nil”在业务上是不是一回事。使用 Go 的 log/slog 时，可以先记住一个判断：slog.Any("user", nil) 生成的是一个 key 为 user、Value 为 nil 的 Attr，它不是空 Attr；自定义 Handler 不应该因为 Value 是 nil 就把这个字段无条件丢掉。

官方地址：https://pkg.go.dev/log/slog

我在把日志接到结构化存储时，最先遇到的问题就是字段语义被压扁：缺少 user、明确记录 user=null、以及传入了 typed nil 指针，最后都变成了同一个空白字段。下面只围绕 Attr、slog.Value 和 Handler 把这个边界拆开。

先分清空 Attr 与带 key 的 nil

slog.Attr 是 key-value 对，空 Attr 的判断条件是 key 和 value 都是零值。官方 Handler 约定也明确要求：如果 Attr 的 key、value 都是零值，就忽略它；这个判断可以通过 a.Equal(slog.Attr{}) 完成。

但 slog.Any("user", nil) 的 key 并不是空字符串，所以它不满足空 Attr 条件。它表达的是“日志事件里有一个 user 字段，它当前的值是 nil”。这两个状态在排障和数据分析中经常不同：

这个区分是结构化日志的第一道边界：字段缺失通常意味着调用方没有提供它，字段为 null 则可能意味着调用方明确知道“当前没有值”。如果 Handler 把两者都删除，后端就无法再恢复这层语义。

nil 在 slog.Value 里是什么形态

slog.Value 的零值对应 nil，KindAny 的数值设计也保证了 zero Value 可以表示 nil。对普通的未装箱 nil，下面三个观察点最有用：

func describeNilAttr() {
	attr := slog.Any("user", nil)
	value := attr.Value

	// key 非空，所以这个 Attr 不是空 Attr，不能只看 Value 是否为零。
	fmt.Println(attr.Key == "")

	// nil Value 的 Kind 是 KindAny；KindAny 也覆盖其他任意类型。
	fmt.Println(value.Kind() == slog.KindAny)

	// 对未装箱 nil，Any 返回的接口值为 nil。
	fmt.Println(value.Any() == nil)
}

这里的 KindAny 不是“只代表 nil”。它表示 Value 里保存的是任意 Go 值，未装箱的 nil 只是其中一个重要情况。因此 Handler 不能只写成“KindAny 就丢弃”：一个自定义结构体、一个错误值，甚至一个 typed nil 指针，也可能走到这个 Kind。

自定义 Handler 先 Resolve，再判断输出

Handler 的 Handle 方法收到的是 slog.Record。遍历属性时，先调用 Value.Resolve 是更稳妥的边界，因为属性值可能实现 slog.LogValuer，它会在真正输出前才展开成最终 Value。Resolve 返回后，Value 不再是 KindLogValuer，这时再决定如何写入后端。

func collectFields(r slog.Record) (map[string]any, error) {
	fields := make(map[string]any)

	r.Attrs(func(attr slog.Attr) bool {
		// 只有 key 和 value 都是零值时才跳过；带 key 的 nil 仍然保留。
		if attr.Equal(slog.Attr{}) {
			return true
		}

		// 先解析 LogValuer，避免把延迟值本身写进输出。
		value := attr.Value.Resolve()
		if attr.Key == "" {
			// 本示例只收集扁平字段；分组 Attr 需要单独递归展开。
			return true
		}

		// nil 会作为 map 中的 nil，交给 JSON 编码器输出 null。
		fields[attr.Key] = value.Any()
		return true
	})

	return fields, nil
}

这个片段只负责把字段收集成一个扁平 map，重点是判断顺序，而不是完整实现一个可替换的 Handler。生产 Handler 还要处理分组、重复 key、保留字段、并发访问和写入错误；这些边界不应通过“遇到 nil 就跳过”来简化。

为 nil 选择输出策略，而不是让格式化函数替你决定

不同后端可以有不同的表示，但策略应该是显式的。JSON 结构通常适合保留 null，因为下游仍然能区分字段存在与字段缺失；文本日志可以格式化为 ，但要注意这只是显示文本，不再是可直接查询的 JSON null。对于不允许空值的业务字段，Handler 也可以按 key 做有条件的丢弃，但不要把它写成通用 nil 规则。

如果你的 Handler 使用 ReplaceAttr 或自定义序列化器，也要保留同样的语义：返回零 Attr 才表示删除该属性；只是把 Value 改造成 nil，并不等于删除带 key 的 Attr。这个区别能避免脱敏、字段重命名和空值清理互相覆盖。

typed nil 不等于未装箱 nil

Go 接口有一个常见陷阱：接口里装着一个 nil 指针时，接口本身仍可能是非 nil。传入 slog.Any("user", (*User)(nil)) 后，Value 的 Kind 仍可能是 KindAny，但 Value.Any() 返回的是带有动态类型信息的接口值，而不是一个真正的 nil 接口。

type User struct {
	ID string
}

func inspectTypedNil() {
	var user *User
	value := slog.AnyValue(user)
	raw := value.Any()

	// raw 可能携带 *User 的动态类型，因此不能只用 raw == nil 判断。
	fmt.Println(value.Kind() == slog.KindAny)
	fmt.Println(raw == nil)

	// 如果业务必须识别 typed nil，应按允许的指针、切片或 map 类型做反射判断。
	if raw != nil {
		rv := reflect.ValueOf(raw)
		fmt.Println(rv.Kind() == reflect.Pointer && rv.IsNil())
	}
}

是否把 typed nil 归类为 null，是数据契约问题，不是 slog 替你做出的统一结论。日志 Handler 可以保留动态类型，也可以把所有允许的 nil-able 类型归一化为 null，但必须在文档和测试中固定下来。

自定义 Handler 的收尾清单

1. 空 Attr：用 attr.Equal(slog.Attr{}) 判断，不要只看 attr.Value.Kind()。
2. 带 key 的 nil：key 有业务含义时继续处理，按后端约定输出 null 或占位文本。
3. 延迟值：先调用 Value.Resolve()，再读取 Kind() 或 Any()。
4. KindAny：它不只代表 nil，不能因为 KindAny 就统一删除字段。
5. typed nil：如果要合并到 null 语义，明确支持的动态类型，并避免泛化反射规则。
6. 分组属性：扁平 map 示例不等于完整 Handler；Group 应按你的键路径规则递归处理。
7. 并发与写入：Handler 方法可能并发调用，输出 writer 和内部状态需要自己的同步策略。

结论：先判断字段是否存在，再判断值是什么

“结构化日志值”这个问题可以压缩成两层判断：第一层看 Attr 是否为空，只有 key 和 value 都是零值才丢弃；第二层看带 key 的 Value 是普通值、未装箱 nil、LogValuer 还是 typed nil。自定义 Handler 先 Resolve，再按明确的数据契约决定输出，才能让日志中的 null、缺失和类型信息保持可解释。

相关问题

slog.Any("user", nil) 会自动被 Handler 丢弃吗？

不应因为 Value 是 nil 就丢弃。它有非空 key，因此不是空 Attr；是否输出取决于 Handler 或后端的字段策略。

KindAny 能直接代表 nil 吗？

不能。KindAny 也可以承载其他任意类型。对未装箱 nil，可以继续观察 Value.Any() == nil；对 typed nil，还要考虑动态类型。

为什么自定义 Handler 要调用 Value.Resolve？

因为值可能实现 LogValuer，Resolve 会把延迟计算的值展开成最终 Value。否则 Handler 可能把 LogValuer 本身当成业务数据输出。