Go slog.ReplaceAttr 怎么统一脱敏日志字段

如果项目已经统一使用 log/slog，日志脱敏最稳妥的落点通常不是每个业务调用处，而是 HandlerOptions.ReplaceAttr。它会在 TextHandler 或 JSONHandler 编码属性之前接收每个非分组属性，因此同一套规则可以覆盖普通日志、Logger.With 预置字段和嵌套 Group 中的字段。

实用做法是：用 groups + a.Key 形成完整字段路径，再按路径执行全量替换、局部掩码或返回零值 slog.Attr{} 删除字段。不要把密码、令牌等值拼进 msg，因为 ReplaceAttr 适合处理结构化字段，不适合猜测自由文本里的秘密。

最小可用写法：先挡住明确的敏感键

下面的版本先解决最常见的三类字段：口令、访问令牌和邮箱。它不依赖具体输出格式，换成 slog.NewJSONHandler 后仍然生效。

package main

import (
    "log/slog"
    "os"
    "strings"
)

func fieldPath(groups []string, key string) string {
    // groups 由 slog 管理，文档要求不得修改或长期保存。
    if len(groups) == 0 {
        return strings.ToLower(key)
    }
    return strings.ToLower(strings.Join(groups, ".") + "." + key)
}

func redactAttr(groups []string, a slog.Attr) slog.Attr {
    switch fieldPath(groups, a.Key) {
    case "password", "user.password", "auth.access_token":
        // 保留字段名，便于排查“字段存在但已脱敏”。
        return slog.String(a.Key, "[REDACTED]")
    case "user.email":
        if a.Value.Kind() == slog.KindString {
            return slog.String(a.Key, maskEmail(a.Value.String()))
        }
    case "debug.raw_request":
        // 返回零 Attr，字段不会进入最终日志。
        return slog.Attr{}
    }
    return a
}

func maskEmail(s string) string {
    at := strings.LastIndexByte(s, '@')
    if at 

这里最关键的不是掩码算法，而是规则集中在一个 Handler 出口。调用方仍然使用普通的 slog.String、slog.Group 和 Logger.With；输出端负责保证字段策略一致。对于多人维护的服务，这比要求每位开发者记住“先脱敏再记录”更容易审查。

把脱敏放在 Handler 输出边界

ReplaceAttr 的签名是 func(groups []string, a slog.Attr) slog.Attr。标准库会先解析属性值，再调用这个函数；如果返回零 Attr，该属性会被丢弃。它不会直接接收一个 Group 容器，而会处理 Group 内部的非 Group 属性，所以嵌套字段仍然可以逐项脱敏。

这层边界还有两个容易忽略的事实：

• time、level、source 和 msg 等内置属性也可能进入回调。其中 source 只有在 AddSource 为真时出现，零时间则不会出现。
• a.Value 在回调前已经执行过解析，使用自定义 LogValuer 时，ReplaceAttr 看到的是解析后的值；回调返回的新值还会再次解析。

因此规则最好默认“原样返回”，只处理明确列出的业务路径。不要在末尾把未知字段都转成字符串，否则会破坏数字、布尔值、时间和结构化值的类型，降低日志查询质量。

按完整字段路径选择脱敏动作

只判断 a.Key 容易误伤。比如 user.email 可能需要掩码，而 billing.email 可能是用于内部对账、已经由上游生成的不可逆标识。ReplaceAttr 提供的 groups 正是为了让回调知道当前属性处在哪个分组中。

组合路径时不要执行 append(groups, a.Key) 后再修改切片。官方文档明确说明这个参数不能被保留或修改。直接使用 strings.Join(groups, ".") + "." + a.Key 生成新字符串，既直观，也不会碰到切片共享底层数组的问题。

三类动作可以按信息最小化原则选择：

如果字段名由外部输入产生，建议先把可记录字段限制在白名单内，而不是无限扩充敏感词黑名单。黑名单只能覆盖已经认识的名字，新接入的 credential、secret_value 或业务自定义键可能绕过它。

把规则做成可维护的策略表

字段逐渐增多后，可以把“路径识别”和“如何处理”分开。下面的版本用枚举表达三类动作，避免一个很长的 switch 同时承担匹配、掩码和删除。

type redactMode uint8

const (
    redactAll redactMode = iota
    maskMail
    dropField
)

var redactPolicy = map[string]redactMode{
    "user.password":       redactAll,
    "auth.access_token":   redactAll,
    "http.cookie":         redactAll,
    "user.email":          maskMail,
    "debug.raw_request":   dropField,
}

func redactAttr(groups []string, a slog.Attr) slog.Attr {
    mode, ok := redactPolicy[fieldPath(groups, a.Key)]
    if !ok {
        return a
    }

    switch mode {
    case redactAll:
        return slog.String(a.Key, "[REDACTED]")
    case maskMail:
        // 类型不符合预期时宁可全量隐藏，也不要泄露原值。
        if a.Value.Kind() != slog.KindString {
            return slog.String(a.Key, "[REDACTED]")
        }
        return slog.String(a.Key, maskEmail(a.Value.String()))
    case dropField:
        return slog.Attr{}
    default:
        return a
    }
}

策略表适合放在日志基础包中，由安全审查和业务开发共同维护。若要运行时更新策略，应把整张不可变映射放入 atomic.Value 或通过锁保护，避免 ReplaceAttr 在高并发记录日志时读取正在修改的 map。大多数项目并不需要热更新，启动时固定规则会更简单。

内置字段不要和业务字段混在一起改

ReplaceAttr 也常用于改名 level、删除 time 或缩短 source 路径，但这和敏感字段脱敏是两类职责。若必须同时处理，建议先用独立函数判断内置键，再进入业务策略，让代码审查能清楚看到哪些基础字段被改变。

func replaceForProduction(groups []string, a slog.Attr) slog.Attr {
    // 内置字段不在业务 Group 内，先保持其默认语义。
    if len(groups) == 0 {
        switch a.Key {
        case slog.TimeKey, slog.LevelKey, slog.SourceKey, slog.MessageKey:
            return a
        }
    }
    return redactAttr(groups, a)
}

这段写法刻意不扫描 slog.MessageKey。例如下面的调用已经把令牌放进自由文本，字段回调无法可靠地区分普通单词和秘密：

// 不推荐：秘密已经成为消息文本的一部分。
logger.Info("request failed, token=" + token)

// 推荐：消息保持稳定，敏感值作为结构化字段进入统一策略。
logger.Info("request failed", slog.String("access_token", token))

稳定消息还有额外好处：日志平台更容易聚合相同事件，告警规则也不需要处理不断变化的消息文本。

自定义类型可以再加一道本地保护

ReplaceAttr 是全局出口保护。如果某类值天生不应被明文记录，还可以实现 slog.LogValuer，让它在任何 slog Handler 中都解析为安全值。这适合作为补充，不替代按路径管理的统一策略。

type Secret string

func (Secret) LogValue() slog.Value {
    // 即使调用方忘记使用特定字段名，也不会输出原文。
    return slog.StringValue("[REDACTED]")
}

logger.Info("refresh credentials",
    slog.Any("refresh_token", Secret(token)),
)

两层保护的分工很清楚：敏感类型负责“这个值永远不能明文显示”，ReplaceAttr 负责“这个字段路径在统一出口采用什么策略”。普通字符串仍可能携带敏感信息，所以不能只依赖类型。

用缺失断言验证，而不是只看一眼输出

脱敏测试最重要的断言不是“日志看起来正常”，而是原始秘密绝对不存在。可以让 Handler 写入 bytes.Buffer，同时检查敏感原文缺失和占位符存在。下面只展示测试结构，不把示例输出冒充真实运行记录。

func TestRedactAttr(t *testing.T) {
    var buf bytes.Buffer
    logger := slog.New(slog.NewJSONHandler(&buf, &slog.HandlerOptions{
        ReplaceAttr: redactAttr,
    }))

    logger.Info("login",
        slog.Group("user",
            slog.String("email", "alice@example.com"),
            slog.String("password", "plain-secret"),
        ),
    )

    got := buf.String()
    // 先断言原文不存在，避免只验证替代字段却遗漏泄漏。
    for _, forbidden := range []string{"plain-secret", "alice@example.com"} {
        if strings.Contains(got, forbidden) {
            t.Fatalf("sensitive value leaked: %q", forbidden)
        }
    }
    if !strings.Contains(got, "[REDACTED]") {
        t.Fatal("redaction marker missing")
    }
    if !strings.Contains(got, "a***@example.com") {
        t.Fatal("masked email missing")
    }
}

建议至少覆盖以下情况：

• 顶层键与嵌套 Group 中的同名键是否按不同路径处理；
• Logger.With 预置的敏感字段是否同样脱敏；
• TextHandler 与 JSONHandler 是否都不含原始秘密；
• 非字符串类型误入掩码策略时是否采用安全默认值；
• 返回零 Attr 后，目标字段是否完全缺失；
• 普通数字、布尔值、时间和日志级别是否仍保持原类型与语义。

生产落地清单

1. 在应用创建 Handler 的唯一入口配置 ReplaceAttr，不在各业务包重复创建策略。
2. 为敏感字段建立完整路径表，优先按业务 Group 区分同名键。
3. 密码、令牌和会话标识默认全量替换；没有排查价值的原始载荷直接删除。
4. 禁止把敏感值拼进消息文本，稳定事件名和结构化字段分开记录。
5. 策略未识别的属性原样返回，避免破坏 slog 的类型信息。
6. 用“原文不存在”作为核心测试断言，同时覆盖 Text 与 JSON 两种 Handler。
7. 如果日志还会经过采集器、队列和平台，继续配置访问控制与留存策略；ReplaceAttr 只负责应用输出前的字段处理。

常见问题

ReplaceAttr 会修改 Group 本身吗？

不会直接回调 Group 容器，而是处理其内部的非 Group 属性。当前打开的 Group 名称通过 groups 参数提供。

返回空字符串能删除字段吗？

不能。slog.String(a.Key, "") 仍会输出这个键，只是值为空。要删除字段应返回零值 slog.Attr{}。

为什么不用正则扫描整行日志？

整行扫描已经丢失字段类型和分组语义，容易漏掉转义、编码或新格式。ReplaceAttr 在编码前处理结构化属性，规则更明确，也更容易测试。

groups 可以保存下来异步使用吗？

不可以。官方契约要求这个切片不得保留或修改。需要审计路径时，应在回调内立即复制成独立字符串。

归根结底，统一脱敏不是写一个复杂的字符串替换器，而是守住结构化日志的输出边界：字段以 Attr 进入，按完整路径命中策略，再以安全值或零 Attr 离开。这样规则集中、格式无关，也能通过明确的缺失断言持续回归。