Go log/slog属性值为nil时的输出差异排查

Go 的 log/slog 里，nil 属性不是“没有这个字段”。用 slog.Any("value", nil) 传入的是一个已经存在的属性，只是值为空；slog.Group("meta") 没有子属性时通常会被省略；真正没有调用或没有写入的键，则不会出现在记录中。排查时还要把 TextHandler 与 JSONHandler 分开看：前者偏文本展示，后者更适合下游按结构解析。

先把 nil、空组和缺失键分开

这三个状态经常在日志检索中混在一起。Attr 是键值对：键已经写入、值为 nil 时，记录仍然包含这个属性。空组则只有组名，没有子属性；内置处理器没有内容可展开，通常会把它省略。缺失键更简单：代码从未把它加入当前 Record。

同一组 Attr 在 TextHandler 和 JSONHandler 中如何呈现

要复现差异，可以让同一条日志同时写到文本和 JSON 两个处理器。下面的示例只展示结构关系；代码注释解释了为什么分别构造两个 Logger，输出中的时间字段会因环境而变化。

package main

import (
    "os"
    "log/slog"
)

func main() {
    // 两个处理器接收同一组属性，用来对比 nil、普通值和空组的呈现。
    attrs := []any{
        "name", "worker-7",
        "value", nil,
        slog.Group("empty"),
    }

    // TextHandler 便于人读，nil 通常会以  形式显示。
    textLogger := slog.New(slog.NewTextHandler(os.Stdout, nil))
    textLogger.Info("state", attrs...)

    // JSONHandler 保留机器可解析的空值语义，nil 对应 JSON null。
    jsonLogger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
    jsonLogger.Info("state", attrs...)
}

在不计时间字段的前提下，文本输出可以看到 value=，而 JSON 输出会把它写成 "value":null。空组没有子字段，内置处理器不会凭空制造一个业务值；如果改成 slog.Group("meta", "trace_id", nil)，JSON 才会有 meta 对象并在其中保留 trace_id:null。

typed nil 和 LogValuer 是第二层边界

接口里的 typed nil 不能简单等同于接口本身为 nil。例如一个 *User 指针为 nil，再作为 any 传入时，接口里仍然带着动态类型。日志处理器可能按该值的类型、LogValuer 或可序列化形式继续解析，结果不应凭经验猜测。

type User struct {
    ID string
}

func logUser(logger *slog.Logger, user *User) {
    // 指针为 nil 时先显式决定业务语义，避免 typed nil 被当成普通对象传下去。
    if user == nil {
        logger.Info("user lookup", slog.String("user_state", "unknown"))
        return
    }
    logger.Info("user lookup", slog.String("user_id", user.ID))
}

如果业务上需要区分“查不到”“字段未加载”和“字段明确为空”，建议使用枚举式状态字段，或在组内写入明确的 state，不要只依赖不同 Handler 的默认格式。实现自定义 LogValuer 时，也要让 nil 输入返回稳定的 slog.Value，避免不同输出后端出现不可预期的结构。

把日志字段语义固定下来

在高并发服务里，日志量大时最怕同一个字段今天缺失、明天写空字符串、后天又写 null。可以先用下面的检查表统一约定，再让封装层负责落地：

• 字段一定存在但暂时未知：保留键，写 nil 或显式状态，取决于下游查询能力。
• 字段不适用于当前事件：不写该键，避免制造误导性的空值。
• 需要机器聚合：优先使用 JSONHandler，不要从 TextHandler 的字符串里反向猜类型。
• 需要人读日志：允许使用 TextHandler，但在告警规则里明确 只是空值表现。

上线后的复查动作也很具体：抽取同一事件的文本日志和 JSON 日志各一条，检查字段是否稳定；再用一个真实的 typed nil 入口测试封装层，而不是只测试字面量 nil。这样才能确认空值策略没有被接口包装或自定义值解析悄悄改变。

常见问题

为什么日志里看见了 ，却搜不到 JSON 的 null？

通常是读取了 TextHandler 输出，或下游把文本当普通字符串索引。确认实际 Handler 和采集器解析方式，再按 JSON 字段类型查询。

空组能不能代表“对象为空”？

不能稳定代表。内置处理器可能省略没有子属性的组；需要表达空对象时，应确认下游协议，必要时写入显式状态或一个确定的空对象结构。

typed nil 一定会输出成 null 吗？

不一定。它带有动态类型，可能经过类型解析或 LogValuer。要得到稳定结果，先在业务边界把 nil 指针转换成明确字段语义。

缺失字段和 nil 字段哪个更适合日志检索？

取决于事件契约。必备字段通常保留并明确空值；不适用字段保持缺失，避免把不同业务状态都压成同一个 null。