Go slog 如何避免把用户隐私写进日志：字段白名单、LogValuer 与审计边界

线上排查接口问题时，结构化日志确实比一串拼接字符串好用；但如果把请求对象、用户对象直接交给 slog，手机号、邮箱、Cookie 甚至访问令牌也可能跟着进入日志。更稳妥的做法是先划定日志资产，再用字段白名单和 LogValuer 控制输出，最后用审计测试确认敏感值不会回流。

先划清日志里真正需要保护的资产

一条请求日志通常需要 request_id、路由、耗时、状态码和少量业务编号。手机号、邮箱、身份证号、Cookie、Authorization 值和完整请求体则属于高风险字段。它们一旦进入集中式日志，往往会被索引、复制到告警系统，生命周期比业务数据更长。

这里先做一个小决定：日志记录“用户 42 完成了支付”，而不是记录整份 User 结构。前者能定位链路，后者只是把数据边界交给每个调用方。

攻击路径通常不是恶意代码，而是一次顺手打印

最容易出问题的写法类似这样：

logger.Info("checkout failed", "request", req, "user", user)

调用方本来只想保留上下文，结果结构体新增字段后，日志内容也悄悄扩大。另一个常见路径是把 map[string]any 作为“调试详情”传入，字段名虽然不固定，值却会原样落盘。

因此风险不只来自一处格式化函数，而来自三个入口：调用方传入完整对象、类型默认展开所有字段、Handler 没有最后的审计边界。

用 LogValuer 让业务对象默认只暴露白名单

下面的示例只允许输出订单编号和状态。即使其他代码把 Order 作为属性传给日志，也不会把邮箱、收货地址带出来。

package main

import (
    "log/slog"
    "os"
)

type Order struct {
    ID          string
    Status      string
    Email       string
    ShippingAddr string
}

func (o Order) LogValue() slog.Value {
    return slog.GroupValue(
        slog.String("id", o.ID),
        slog.String("status", o.Status),
    )
}

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
    order := Order{ID: "ord_1038", Status: "paid", Email: "a@example.com", ShippingAddr: "上海市"}
    logger.Info("order updated", "order", order)
}

预期日志中应能找到 ord_1038 和 paid，但找不到邮箱与地址。这个实现的价值在于“默认安全”：新增调用点时不必重新记住一套脱敏规则。

Handler 层负责最后一道风险分级

LogValuer 适合控制类型的默认表现，Handler 则适合处理全局约束，例如禁止某些属性名、截断过长字符串，或为值增加统一的哈希策略。可以在创建 JSON Handler 时使用 ReplaceAttr：

opts := &slog.HandlerOptions{
    ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
        switch a.Key {
        case "authorization", "cookie", "email", "phone":
            return slog.String(a.Key, "[REDACTED]")
        default:
            return a
        }
    },
}
logger := slog.New(slog.NewJSONHandler(os.Stdout, opts))

不要把 Handler 过滤当成调用方的免责理由。字段白名单应该先发生在业务对象和调用代码中，Handler 只是防止遗漏。对于必须关联同一用户的场景，记录稳定的内部编号或经过审查的摘要值，比直接记录原始身份信息更合适。

把日志审计写成可失败的测试

人工翻日志很难覆盖所有分支，至少应为关键对象写一个输出测试：创建内存 Handler，记录一条日志，然后断言敏感值和敏感字段名都不出现。

func TestOrderLogDoesNotLeakPrivateFields(t *testing.T) {
    var buf bytes.Buffer
    logger := slog.New(slog.NewJSONHandler(&buf, nil))
    logger.Info("order updated", "order", Order{
        ID: "ord_1038", Status: "paid", Email: "a@example.com", ShippingAddr: "上海市",
    })
    got := buf.String()
    if strings.Contains(got, "a@example.com") || strings.Contains(got, "上海市") {
        t.Fatalf("private value leaked: %s", got)
    }
}

测试不应只查某一个值，还可以维护一组禁止出现的字段名，例如 cookie、authorization 和 phone。如果团队允许日志字段持续演进，这类测试能在代码审查之后再加一道门。

上线前的验证清单和回退边界

• 抽样检查业务对象的 LogValue 是否只返回白名单。
• 检查所有公共 Handler 是否配置了最后一道属性处理逻辑。
• 用测试和脱敏后的真实样本核对 JSON 字段名、值和日志级别。
• 发现泄露时先降低相关日志级别或停用字段，再清理已有副本并复查采集链路。

回退时不要直接恢复“打印完整对象”。如果新字段确实影响排障，优先新增一个明确命名、经过审查的日志值，例如 order_debug，并为它补一条输出测试。

相关问答

LogValuer 能代替所有日志脱敏吗？

不能。它主要控制某个类型如何转成 slog.Value，动态 map、第三方类型和调用方拼接的字符串仍需在调用代码或 Handler 层检查。

为什么不直接把敏感字段删掉？

统一替换为明确的占位值更容易审计，也能让读日志的人知道该字段被主动隐藏，而不是误以为数据缺失。

最后核对一次

把日志边界拆成“对象默认输出、调用方选择字段、Handler 统一兜底、测试持续拦截”四层，排障信息和隐私保护才能同时成立。真正上线前，重点看新增字段是否会绕过这四层，而不是只检查某一条示例日志。