Go slog.JSONHandler ReplaceAttr 如何隐藏敏感字段：属性改写与分组边界

线上日志接入 slog.NewJSONHandler 后，最容易被忽略的风险不是 JSON 格式，而是把 password、token 之类的字段原样写进了日志。HandlerOptions.ReplaceAttr 可以在序列化前统一改写或丢弃属性，但它对分组属性的调用方式有明确边界：回调拿到的是当前属性和已经打开的 groups，不是整个 Group 节点。

一次真实故障：密码字段为什么仍出现在 JSON 日志里

假设业务代码把认证信息放在 request 组中：

logger.LogAttrs(ctx, slog.LevelInfo, "login",
    slog.Group("request",
        slog.String("user", "alice"),
        slog.String("password", "secret"),
    ),
)

如果过滤器只判断 a.Key == "password"，看起来应该能命中；但当代码同时处理多种嵌套结构时，真正需要确认的还有这个属性当前处在哪个组里。更糟的是，有人把 Group 当成普通属性处理，试图在遇到组节点时直接改写，结果过滤逻辑根本没有按预期执行。

从 handler.go 看清 ReplaceAttr 的调用时机

Go 官方 log/slog 源码把行为拆成两步。首先，appendAttr 会让属性值执行 Resolve；随后，当值不是 KindGroup 时才调用 ReplaceAttr。所以回调接收的是已经解析过的具体 Attr，不会直接收到整个 Group 属性。

opts := &slog.HandlerOptions{
    ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
        if len(groups) == 1 && groups[0] == "request" && a.Key == "password" {
            return slog.Attr{}
        }
        return a
    },
}

logger := slog.New(slog.NewJSONHandler(os.Stdout, opts))

这里的判断顺序很重要：先检查 groups，再检查 a.Key。返回 slog.Attr{} 是零值 Attr，内置 handler 会把它视为待丢弃字段；返回原来的 a 则继续序列化。

官方源码给出的调用示例也说明了这一点：普通字段的 groups 为 nil，而 Group("g", Int("b", 2)) 中的 b 会以 []string{"g"} 传入。

分组嵌套时，过滤规则应该怎样写

如果日志里还有 response 组，同名的 token 可能并不敏感，或者需要不同的脱敏方式。可以把分组路径拼成自己的判断条件，但不要修改 groups 切片，它由 handler 管理，官方文档明确要求回调不要保留或修改它。

func redact(groups []string, a slog.Attr) slog.Attr {
    if a.Key != "password" && a.Key != "token" {
        return a
    }
    if len(groups) == 1 && groups[0] == "request" {
        return slog.String(a.Key, "[REDACTED]")
    }
    return a
}

这个版本不删除字段，而是保留键名并替换值，便于排查日志结构。若合规要求连字段名也不能出现，才返回零值 Attr。要注意，回调只会收到叶子属性；如果组里嵌套了另一个组，groups 会按打开顺序包含多个名称。

JSONHandler 和 TextHandler 的结果为什么不同

JSONHandler 会把组名写成嵌套 JSON 对象；TextHandler 则通常把组名和键名用点连接。这个差异不改变 ReplaceAttr 的回调边界，却会改变最终日志检索时看到的键。

• JSON 输出更适合按对象路径查询，request.password 会处在 request 对象中。
• Text 输出可能把组路径展平成带点的键，点号本身没有进一步转义。
• 如果业务组名或字段名本身带点，不能仅靠最终文本键反推出原始分组结构。

因此脱敏应放在 ReplaceAttr 的结构化阶段完成，不要等日志落盘后再用字符串替换。后处理既可能漏掉 JSON 嵌套值，也可能误伤消息正文。

上线前的复查：过滤器是否真的覆盖了边界

至少用三条记录验证：顶层 password、request 组内的 password、以及嵌套组中的 token。同时分别挂载 JSONHandler 和 TextHandler，检查它们都没有泄露原值。

还要测试 LogValuer 返回组的情况。由于 handler 会先解析属性值，过滤器看到的仍是组内实际属性；但回调不会把组节点本身当作普通 Attr 传入。这个结论比“回调会遍历所有原始参数”更准确。

常见问题

ReplaceAttr 能不能直接修改 groups？

不能。groups 反映 handler 当前打开的分组路径，官方文档要求不要保留或修改它；只读它来决定过滤规则即可。

返回 slog.Attr{} 和返回脱敏字符串有什么区别？

返回零值 Attr 会删除整个字段；返回 slog.String 会保留字段键，只替换值。日志检索是否依赖该键，是选择两种策略的主要依据。

为什么不能只按 a.Key 过滤 password？

不同组可以拥有同名键。结合 groups 判断，才能把过滤范围限定在 request 等真实业务路径内，避免误删其他上下文。

ReplaceAttr 的安全用法可以归结为一句话：把它当作结构化属性的最后一道边界。先理解 JSONHandler 如何展开 Group，再根据 groups 和 Attr 做改写或删除，过滤器才不会被日志格式变化带偏。