Go 结构化日志 ReplaceAttr 如何做字段脱敏

Go 的 log/slog 已经把结构化日志放进标准库，但“结构化”不等于“自动安全”。登录日志里常见的邮箱、访问令牌、密码或身份证号，只要被作为属性传给 Logger，就可能进入 TextHandler 或 JSONHandler。一个实用的收口点是 slog.HandlerOptions.ReplaceAttr：在属性写入前，按属性键和当前分组路径决定保留、遮盖，或直接删除。

把 ReplaceAttr 挂到实际使用的 Handler 上，并优先采用“敏感字段白名单/明确删除 + 需要保留结构的字段遮盖”的规则。返回零值 slog.Attr{} 会丢弃该属性，返回带新值的 Attr 才是遮盖。

为什么日志里仍会出现明文敏感字段

这类问题通常不是 JSONHandler 失效，而是日志字段已经在调用点被明确加入。排查时可以按三个节点回放：业务代码把值放入 slog.String 或 slog.Any；Logger 把属性交给 Handler；Handler 再把属性编码为文本或 JSON。默认处理器不会替业务代码判断“这个字符串是否敏感”，所以脱敏必须成为 Handler 的统一策略。

真正容易漏掉的是嵌套组。例如 user.email 和 request.email 可能需要不同策略。ReplaceAttr 的第一个参数 groups 是当前打开的分组路径，不能只判断 a.Key == "email" 就把所有同名字段一刀切。

ReplaceAttr 的脱敏逻辑要看字段键和分组路径

下面的规则只做两件事：对令牌和用户邮箱保留字段名但替换值；对密码直接返回零值属性。它没有运行外部服务，也不依赖日志文本二次解析，因此规则和 Handler 的边界比较清楚。

package main

import (
    "log/slog"
    "os"
)

// redactAttr 根据分组路径和字段键决定遮盖或删除，避免把规则散落在业务调用点。
func redactAttr(groups []string, a slog.Attr) slog.Attr {
    // 密码不需要保留结构，返回零值 Attr 会让 Handler 丢弃它。
    if a.Key == "password" {
        return slog.Attr{}
    }

    // token 无论位于哪个组都只输出固定占位符，不回显原始值。
    if a.Key == "token" {
        return slog.String(a.Key, "[REDACTED]")
    }

    // 只处理 user 组中的 email，避免误伤其它业务上下文中的同名字段。
    if a.Key == "email" && len(groups) > 0 && groups[len(groups)-1] == "user" {
        return slog.String(a.Key, "[REDACTED]")
    }

    // 其它属性原样返回，保持正常日志字段可检索。
    return a
}

func main() {
    // ReplaceAttr 绑定在实际输出 Handler 上，JSONHandler 会使用这套规则。
    handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        ReplaceAttr: redactAttr,
    })
    logger := slog.New(handler)

    // user 组中的 email 和 token 会被遮盖，password 会被删除。
    logger.Info("login",
        slog.Group("user",
            slog.String("email", "alice@example.com"),
            slog.String("token", "access-token-value"),
        ),
        slog.String("password", "plain-text-password"),
        slog.String("result", "ok"),
    )
}

这里的关键不是把敏感词写进一个更复杂的正则，而是保留字段上下文：groups 只读不改，a.Value 已经是可处理的属性值；返回新的字符串 Attr 表示遮盖，返回零值 Attr 表示删除。官方文档也说明 ReplaceAttr 不会针对 Group 属性本身调用，而是针对组内属性调用。

隐藏字段与修改值要分开处理

“删除”和“遮盖”对应两种不同的审计需求。密码、完整令牌通常不应进入日志，直接删除可以减少泄露面；邮箱、订单号后四位或用户标识有时还需要用于关联事件，这时可以保留键并替换成固定占位符或经过设计的摘要。不要把原值拼到占位符中，也不要在同一个规则里随机生成不可复查的文本。

对于嵌套字段，建议把敏感字段表写成可读的规则：字段名、允许出现的分组路径、动作、是否需要保留检索能力。这样比“遇到包含 token 的字符串就替换”更可控，也不会误伤业务消息或错误堆栈中的普通文本。

复查边界：哪些日志仍可能绕过这层保护

第一，ReplaceAttr 只处理经过该 Handler 的属性；如果项目还有另一套日志库、另一只 Handler 或直接写文件的调试代码，就需要分别接入策略。第二，日志消息本身可能是一整段拼接文本，敏感值已经埋在 msg 中时，按属性键的规则无法可靠拆解，应该回到调用点改成结构化字段。

第三，脱敏规则要覆盖 Logger.With 预置属性、分组属性和错误对象的序列化结果。上线前至少用固定的敏感字段样本检查三种结果：应删除的键不出现，应遮盖的键只保留占位符，普通字段仍可用于检索。这个复查是规则维护的一部分，不是把真实令牌写进日志后再观察。

常见问题

ReplaceAttr 能直接修改日志消息吗？

可以识别内置的 msg 属性，但更稳妥的做法是不要把敏感数据拼在消息字符串里，而是把它作为独立属性交给脱敏规则。

为什么同名字段不能全部用同一个处理？

因为 ReplaceAttr 同时提供分组路径和属性键；groups 能区分 user.email 与其它上下文中的 email，避免过度脱敏或漏脱敏。

参考资料：https://pkg.go.dev/log/slog；https://go.dev/blog/slog。