Go slog.LogValuer 怎么避免敏感字段泄露：结构化日志降级、组字段与审计检查

线上排查接口错误时，日志里最容易失控的不是一条明显的密码，而是一个“方便调试”的请求对象：它被交给 slog 后，令牌、邮箱和请求头一起进入了结构化输出。slog.LogValuer 能把对象转换成更适合记录的字段，但它不会自动替你判断哪些数据属于敏感信息。

把脱敏边界写进 LogValue，只返回允许进入日志的字段；再用组字段和测试检查最终结构，而不是把原对象直接交给日志器。

先确认 LogValuer 到底负责哪一段

slog.Value 遇到实现了 LogValuer 的值时，会调用它取得用于记录的值。这个接口解决的是“对象如何呈现”，并不负责鉴权、存储加密或日志保留期限。真正的边界应该由类型自己定义：哪些字段能出现在日志里，哪些字段永远不能出现在日志里。

type LoginAttempt struct {
    UserID    string
    Email     string
    Token     string
    ClientIP  string
    Failed    bool
}

func (a LoginAttempt) LogValue() slog.Value {
    return slog.GroupValue(
        slog.String("user_id", a.UserID),
        slog.Bool("failed", a.Failed),
        slog.String("client_ip", maskIP(a.ClientIP)),
    )
}

这里故意没有返回 Email 和 Token。调用方即使写出 logger.Info("login", "attempt", attempt)，日志值也只会暴露类型允许的字段。把规则放在类型边界，比要求每个调用点都记住一份字段清单更可靠。

用 GroupValue 保持键路径稳定

结构化日志的好处是可以按键检索，前提是字段名称不要随着调用方式漂移。用 slog.GroupValue 包住对象字段，最终路径通常会落在 attempt.user_id、attempt.failed 这样的层级里，审计规则也更容易写。

logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
logger.Info("login check", "attempt", LoginAttempt{
    UserID: "u-2048",
    Email:  "person@example.com",
    Token:  "secret-value",
    ClientIP: "192.0.2.45",
    Failed: true,
})

不要在一处把对象作为 attempt 记录，另一处又把它拆成 email、token、ip 三个参数。那样即使类型本身是安全的，绕过类型边界的调用点仍可能把原始字段写进去。

零值、嵌套对象和错误降级要分别处理

LogValue 里最好明确处理空标识、空地址和失败状态。零值不应触发一次额外的完整对象输出，也不要为了“方便排查”在错误分支里拼出原始请求。

func (a LoginAttempt) LogValue() slog.Value {
    attrs := []slog.Attr{
        slog.Bool("failed", a.Failed),
    }
    if a.UserID != "" {
        attrs = append(attrs, slog.String("user_id", a.UserID))
    }
    if a.ClientIP != "" {
        attrs = append(attrs, slog.String("client_ip", maskIP(a.ClientIP)))
    }
    return slog.GroupValue(attrs...)
}

func maskIP(ip string) string {
    if ip == "" { return "" }
    return "masked"
}

如果嵌套值也实现了 LogValuer，要确认它的字段集合同样受控。日志 Handler 可能会解析或替换值，因此不要只依赖某一次文本格式化后的样子来判断安全性。

最小可用审计测试怎么写

测试重点不是比较整行 JSON，而是解析 Handler 收到的记录，检查允许字段和禁止字段。这样格式化器换成文本 Handler 或自定义 Handler 时，安全意图仍然清楚。

func TestLoginAttemptLogValue(t *testing.T) {
    got := (LoginAttempt{
        UserID: "u-2048",
        Email: "person@example.com",
        Token: "secret-value",
        ClientIP: "192.0.2.45",
    }).LogValue()

    if got.Kind() != slog.KindGroup { t.Fatal("want group value") }
    for _, attr := range got.Group() {
        if attr.Key == "token" || attr.Key == "email" {
            t.Fatalf("sensitive key leaked: %s", attr.Key)
        }
    }
}

再补一条集成测试：创建 JSON Handler，记录一条真实日志，确认输出中没有敏感值字符串。单测可以证明返回值没有这些键，集成测则能抓住调用方误把原始字段作为额外参数传入的情况。

常见误区与上线前检查

• 把 LogValuer 当成密码库：它只影响日志值的呈现，不能替代权限控制和日志访问审计。
• 只屏蔽字段名：错误文本、请求 URL 查询串和自定义字符串里仍可能藏着令牌。
• 用固定 IP 脱敏示例当真实策略：生产规则应与隐私要求和排障需要共同确定。
• 只测 JSON 文本：应同时检查结构化键、原始敏感值和错误分支。

相关问题

LogValuer 会自动递归清理所有嵌套字段吗？

不会。嵌套值是否安全取决于它自己的实现和调用方式；对外暴露的对象仍应逐层定义允许字段。

为什么不用 fmt.Stringer 统一控制输出？

Stringer 更偏向文本格式化，结构化日志还需要稳定的键和值类型。对 slog 来说，LogValuer 更适合表达字段边界。

日志中完全没有用户标识会更安全吗？

不一定。可以保留经过业务允许的内部标识或不可逆摘要，关键是让排障价值和隐私风险都经过明确评估。

把脱敏规则留在类型边界

一个可复查的做法是：敏感对象默认不提供原始字段的日志表示，LogValue 只返回允许的组字段；调用点禁止再把原对象拆开输出；测试同时覆盖值转换和真实 Handler。这样日志字段发生变化时，审计差异会落在一个容易定位的地方。