Go slog.HandlerOptions ReplaceAttr 怎么统一清洗字段

要统一清洗 log/slog 字段，最合适的入口是创建 TextHandler 或 JSONHandler 时配置 HandlerOptions.ReplaceAttr。它会在属性真正写出前接收每个非分组属性，因此可以集中完成敏感值脱敏、内置键重命名、类型归一化和噪声字段删除，而不必让每个日志调用点重复处理。

官方文档：https://pkg.go.dev/log/slog#HandlerOptions

升级范围：从调用点清洗迁移到 Handler 策略

假设项目里既有 logger.Info("login", "token", token)，也有 logger.WithGroup("user").Info(...)。若每个调用点手动把令牌替换成星号，迟早会有新代码忘记处理；若业务层先把值转成字符串，日志层还会失去原始类型。更稳妥的改造是：业务代码只描述事实，Handler 在输出边界执行统一策略。

这不是要求一次性改掉所有日志字段，而是把“输出前最后一道规则”集中起来。迁移初期可先覆盖最明确的敏感键和内置键，确认输出兼容后，再逐步加入命名与类型规范。

变更表：哪些字段会进入 ReplaceAttr

官方约定还给出两个关键边界：属性值在回调前已经执行过 Value.Resolve，所以通常不需要再次解析 LogValuer；若回调返回零值 slog.Attr{}，该属性会从最终输出中消失。

旧代码风险：清洗散落后会出现三类不一致

第一类是漏清洗。新增调用点只要忘了调用包装函数，就可能把口令、令牌或会话标识原样写入日志。第二类是重复清洗：业务层已经截断一次，日志适配层又截断一次，最终值难以排查。第三类是同名字段误伤，例如顶层 id 代表请求编号，而 user.id 代表用户编号，只看 a.Key 会把两者当成同一个字段。

此外，内置字段也由 Handler 生成。只清洗业务参数无法统一 time、level、source 和 msg 的命名。ReplaceAttr 让业务属性与内置属性在同一输出边界接受策略，但策略必须明确分组路径与内置键的差异。

新写法：把清洗规则集中成一个策略

下面的实现先拼出只在当前调用内使用的完整路径，再按字段执行规则。示例只保留少量可解释规则：删除顶层时间、把 msg 改为 message、脱敏任意层级的敏感键，并把 user.email 做局部隐藏。

package logx

import (
    "log/slog"
    "strings"
)

func replaceAttr(groups []string, a slog.Attr) slog.Attr {
    // groups 由 Handler 临时提供，只读取，不保存也不修改。
    path := strings.Join(appendCopy(groups, a.Key), ".")

    // 顶层时间由采集系统补充，返回零值 Attr 即删除。
    if len(groups) == 0 && a.Key == slog.TimeKey {
        return slog.Attr{}
    }

    // 统一内置消息键，避免不同语言客户端字段名不一致。
    if len(groups) == 0 && a.Key == slog.MessageKey {
        a.Key = "message"
        return a
    }

    switch strings.ToLower(a.Key) {
    case "password", "token", "authorization", "secret":
        return slog.String(a.Key, "[REDACTED]")
    }

    // 对特定分组路径使用更细的规则，避免误伤其他 email 字段。
    if path == "user.email" && a.Value.Kind() == slog.KindString {
        return slog.String(a.Key, maskEmail(a.Value.String()))
    }
    return a
}

func appendCopy(groups []string, key string) []string {
    // 新建切片，防止 append 修改 Handler 提供的临时 groups 底层数组。
    path := make([]string, 0, len(groups)+1)
    path = append(path, groups...)
    return append(path, key)
}

func maskEmail(email string) string {
    at := strings.IndexByte(email, '@')
    if at 

接入点只需配置一次。TextHandler 与 JSONHandler 都使用同一个 HandlerOptions 语义，因此可以让本地文本日志和生产 JSON 日志共享策略。

package main

import (
    "log/slog"
    "os"
)

func main() {
    opts := &slog.HandlerOptions{
        AddSource:   true,
        ReplaceAttr: replaceAttr, // 所有输出字段统一经过策略层。
    }
    handler := slog.NewJSONHandler(os.Stdout, opts)
    logger := slog.New(handler)

    logger.Info("login",
        slog.String("token", "secret-value"),
        slog.Group("user",
            slog.Int("id", 42),
            slog.String("email", "alice@example.com"),
        ),
    )
}

兼容边界：groups 只读、Group 名不会被回调改写

groups 表示当前属性外层已经打开的分组名称。官方文档明确要求不要保留或修改这个切片，因为它由 Handler 在处理记录时临时管理。若要拼完整路径，必须像示例那样复制后再追加字段名，不能直接 append(groups, a.Key) 后把结果保存到全局缓存。

ReplaceAttr 不会接收到 Group 属性本身，只会接收到它的内容。因此可以根据 user.email 清洗值，却不能靠这个回调把组名 user 改成 account。组名迁移应在创建属性或封装 Logger 时完成。

内置字段也有出现条件：记录时间为零时不会传入 time；未开启 AddSource 时不会传入 source。规则应该允许字段不存在，不应把每条日志都必须出现四个内置键当作前提。

并发注意：策略函数不要依赖未保护的可变状态

Handler 的方法可能被多个 goroutine 并发调用，ReplaceAttr 也应按并发路径设计。最简单的方案是只读取启动时构造好的不可变配置，并在函数内创建临时值。若规则需要动态黑名单或计数器，应使用原子替换、锁或其他并发安全结构，不能直接读写普通 map。

type Cleaner struct {
    sensitive map[string]struct{} // 初始化后只读，避免并发写入。
}

func NewCleaner(keys ...string) *Cleaner {
    set := make(map[string]struct{}, len(keys))
    for _, key := range keys {
        set[strings.ToLower(key)] = struct{}{}
    }
    return &Cleaner{sensitive: set}
}

func (c *Cleaner) ReplaceAttr(_ []string, a slog.Attr) slog.Attr {
    // 只读不可变映射，可安全供多个日志 goroutine 共享。
    if _, ok := c.sensitive[strings.ToLower(a.Key)]; ok {
        return slog.String(a.Key, "[REDACTED]")
    }
    return a
}

回归检查：用输出测试固定清洗规则

测试重点不是回调被调用了多少次，而是最终日志是否满足契约。由于内置时间会变化，测试可通过规则删除时间，再解码 JSON 检查键和值。这样既覆盖 ReplaceAttr，又覆盖 Handler 的实际序列化结果。

func TestReplaceAttr(t *testing.T) {
    var buf bytes.Buffer
    handler := slog.NewJSONHandler(&buf, &slog.HandlerOptions{
        ReplaceAttr: replaceAttr, // 测试真实 Handler 输出，而非只测辅助函数。
    })
    logger := slog.New(handler)

    logger.Info("login",
        slog.String("token", "abc"),
        slog.Group("user", slog.String("email", "alice@example.com")),
    )

    var got map[string]any
    if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
        t.Fatalf("解析日志 JSON 失败: %v", err)
    }
    if got["message"] != "login" {
        t.Fatalf("message = %v，期望 login", got["message"])
    }
    if got["token"] != "[REDACTED]" {
        t.Fatalf("token 未脱敏: %v", got["token"])
    }
    if _, exists := got[slog.TimeKey]; exists {
        t.Fatal("顶层 time 应被删除")
    }

    user, ok := got["user"].(map[string]any)
    if !ok || user["email"] != "a***@example.com" {
        t.Fatalf("user.email 清洗结果异常: %#v", got["user"])
    }
}

还应补充表驱动用例：顶层与分组内同名键、零值时间、关闭与开启 AddSource、嵌套两层以上 Group、实现 LogValuer 的值，以及返回零值 Attr 后空组是否被省略。测试输出比断言内部调用顺序更不容易受实现细节影响。

迁移清单

• 盘点必须脱敏、必须删除、必须改名和必须保留原类型的字段。
• 为分组字段定义完整路径规则，不只按裸键名匹配。
• 先在一个 Handler 上启用 ReplaceAttr，并对比现有采集与查询规则。
• 确认下游是否依赖 msg、time 等旧键，再执行重命名或删除。
• 保持回调无共享可变状态；动态配置必须使用并发安全更新方式。
• 用最终 JSON/Text 输出测试覆盖脱敏、删除、分组路径和内置字段。
• 稳定后移除调用点的重复清洗，避免双重截断或二次编码。

常见问题

ReplaceAttr 能修改 Group 名吗？

不能直接修改。回调不会针对 Group 容器调用，只会处理组内属性，并通过 groups 告知其外层路径。

怎样删除一个日志字段？

在匹配规则里返回零值 slog.Attr{}。不要返回一个空字符串值，因为那仍然会输出该键。

需要手动调用 Value.Resolve 吗？

通常不需要。内置 Handler 在调用 ReplaceAttr 前已经解析 Value；若回调返回了新的未解析 Attr，Handler 还会再次解析返回值。

ReplaceAttr 适合做复杂外部查询吗？

不适合。它位于每条日志的输出热路径，应该执行快速、确定且无阻塞的转换。远程查询、磁盘访问和重型正则会直接放大日志开销。

总结：ReplaceAttr 的价值不是“再包一层日志函数”，而是把最终输出契约放在 Handler 边界。只要正确处理分组路径、零值删除、内置字段和并发安全，就能让整个项目以一套规则稳定清洗结构化日志。