Go log/slog LogValuer 如何避免敏感字段展开

把密码、访问令牌或完整凭据结构体直接交给 log/slog，风险不在 Handler 选择，而在日志值已经带着原始字段进入了序列化流程。更稳妥的做法是让敏感类型实现 slog.LogValuer，在 LogValue 中只返回允许公开的 slog.Value。这样 JSON 和文本 Handler 都只能看到脱敏后的结果。

用 LogValuer 把敏感类型挡在日志边界外

LogValuer 的价值是把“这个类型应该如何出现在日志里”放回类型本身。下面的示例保留用户编号和角色，只把口令完全丢弃。代码中的 LogValue 不应返回原始对象，否则脱敏入口等于被绕开。

package main

import (
    "log/slog"
    "os"
)

type LoginSecret struct {
    UserID   string
    Role     string
    Password string
}

// LogValue 只输出可公开字段；Password 永远不进入返回的 slog.Value。
func (s LoginSecret) LogValue() slog.Value {
    // 空对象也返回稳定结构，避免调用方为了判断 nil 而打印原始值。
    if s.UserID == "" {
        return slog.GroupValue(slog.String("state", "anonymous"))
    }
    // GroupValue 让 Handler 继续按结构化字段输出，但没有敏感字段。
    return slog.GroupValue(
        slog.String("user_id", s.UserID),
        slog.String("role", s.Role),
    )
}

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
    secret := LoginSecret{UserID: "u-42", Role: "operator", Password: "do-not-log"}
    // 传入实现了 LogValuer 的类型，Handler 会解析它的安全 Value。
    logger.Info("login accepted", "account", secret)
}

这里的关键不是字段名叫不叫 Password，而是返回值中根本没有它。若把 secret 先转成 any、字符串或 map 再记录，调用链就可能重新暴露原始内容。

先定义输入、空值和可公开字段的规则

脱敏逻辑最好是一个小而稳定的策略：哪些字段可见、空对象怎么表示、是否允许展示摘要，都写在 LogValue 中。不要在每个调用点分别拼字段，否则新增日志时很容易漏掉密码或令牌。

如果类型包含可变指针或缓存字段，也不要为了“完整诊断”直接返回它们。日志是跨进程、跨存储周期的数据出口，白名单比黑名单更容易在重构后保持安全。

用两个 Handler 核对脱敏结果

LogValue 返回的是 slog.Value，默认 Handler 会在处理属性时解析它。可以分别使用 JSONHandler 和 TextHandler 检查：两种格式都应出现 user_id、role，而不应出现原始口令。这个检查是输出边界核对，不是把示例输出冒充成本机截图。

还要注意 Value.Resolve 的边界：它会继续解析嵌套的 LogValuer，并防止无限递归；如果返回 Group，Group 内属性不会被无条件递归展开。自定义 Handler 应遵循官方 Handler 约定，在输出前解析属性，不要绕过解析直接读取原始接口值。

上线前的四项检查

1. 搜索敏感类型的所有日志调用，确认没有把原始结构体改成字符串或 map。
2. 为 LogValue 增加正常值、空值和新增字段的测试，断言结果中不存在 password、token 等键。
3. 分别跑 JSON 与文本 Handler，检查字段名称和嵌套 Group 是否符合检索习惯。
4. 若使用 ReplaceAttr 做全局兜底，仍把 LogValuer 当作第一道边界，不能依赖键名过滤所有泄露路径。

一句话判断：类型拥有敏感字段时，日志调用点只传该类型，类型的 LogValue 只返回白名单 slog.Value，两个 Handler 的结果都不含 secret，这条链才算闭合。

常见问题

LogValuer 能不能返回 slog.StringValue 的摘要？

可以，但摘要也必须经过脱敏设计，不能把密码、令牌或可逆编码放进去。结构化 Group 通常比拼接字符串更容易审查。

实现了 LogValuer 后还需要 ReplaceAttr 吗？

两者职责不同。LogValuer 负责类型自身的安全表示，ReplaceAttr 适合统一改字段名、时间或全局规则；敏感类型不要只依赖后者。

为什么自定义 Handler 仍要调用 Resolve？

因为 LogValuer 可能嵌套返回另一个 LogValuer。使用 Resolve 能遵守 slog 的递归和循环保护约定，避免把未解析的实现细节直接写入输出。