实现带字段脱敏与级别过滤的自定义 Handler

在 Go 的 log/slog 中，字段脱敏和级别过滤最适合放在一个包装型 slog.Handler 里：Enabled 负责在创建完整日志记录前丢弃低级别事件，Handle 负责在记录交给 JSON 或文本输出器前清洗字段。关键不是只实现这两个方法，还要让 WithAttrs 与 WithGroup 保持同样的安全策略，否则预绑定字段可能绕过脱敏。

官方参考：https://pkg.go.dev/log/slog

推荐把“是否记录”和“记录什么”分开：级别阈值在 Enabled 判断，敏感值在 Handle 与 WithAttrs 清洗，最终格式继续交给标准库的 JSONHandler 或 TextHandler。

先界定需要保护的日志资产

日志安全最容易出现两类问题。第一类是密码、令牌、Cookie 等秘密被写进持久化日志；第二类是调试日志在生产环境大量输出，既增加成本，也扩大敏感数据暴露面。自定义 Handler 可以统一设置最后一道防线，但它不能替代调用处的最小化原则：业务代码仍然不应主动记录完整凭证、请求体或个人数据。

这里采用字段名白名单式规则：只有配置为敏感键的 Attr 才脱敏。这样比对整行 JSON 做字符串替换更稳定，因为 Handler 操作的仍是结构化字段，不会误伤普通消息，也不会破坏输出格式。

用 Enabled 在 Record 创建前过滤级别

slog.Handler 的 Enabled 会在日志事件交给 Handle 前被查询。包装 Handler 既要检查自己的最小级别，也要尊重下游 Handler 的判断。最小判断可以写成：

func (h *SecurityHandler) Enabled(ctx context.Context, level slog.Level) bool {
    // 先应用当前包装器的阈值，再保留下游 Handler 的启用规则。
    return level >= h.minLevel.Level() && h.next.Enabled(ctx, level)
}

slog.Leveler 是比固定 slog.Level 更合适的配置类型，因为它既能接收常量，也能接收线程安全的 *slog.LevelVar。需要临时开启 Debug 时，只修改 LevelVar，无须重建 Logger。

级别过滤只能避免 Handler 处理 Record，不能撤销调用参数已经发生的普通 Go 求值。因此，昂贵值应通过延迟求值类型或 LogValuer 设计，不能指望 Enabled 自动消除调用表达式中的全部计算。

递归清洗普通字段与分组字段

只遍历 Record 顶层字段会漏掉 slog.Group 中的秘密。清洗函数要先规范化键名，再递归处理 Group；对实现了 LogValuer 的值，应先调用 Resolve，让最终结构进入同一套规则。

func (h *SecurityHandler) sanitizeAttr(a slog.Attr) slog.Attr {
    // 空 Attr 保持为空，让标准 Handler 按既有规则忽略它。
    if a.Equal(slog.Attr{}) {
        return a
    }

    if _, sensitive := h.sensitive[strings.ToLower(a.Key)]; sensitive {
        // 固定占位符不会泄露原值长度或局部内容。
        return slog.String(a.Key, "[REDACTED]")
    }

    value := a.Value.Resolve()
    if value.Kind() != slog.KindGroup {
        a.Value = value
        return a
    }

    attrs := value.Group()
    clean := make([]slog.Attr, 0, len(attrs))
    for _, child := range attrs {
        // 递归处理嵌套分组中的敏感键。
        clean = append(clean, h.sanitizeAttr(child))
    }
    a.Value = slog.GroupValue(clean...)
    return a
}

这段代码按字段名匹配，大小写统一为小写。实际项目可以把 api_key、access_token、cookie 等命名加入配置，但不要把“值看起来像令牌”当成唯一判断方式：模糊识别容易漏报，也容易把普通业务值替换掉。

完整实现四个 Handler 方法

下面的实现可以直接包裹标准 JSONHandler。它把敏感字段集合复制为只读映射，避免调用方后续修改配置；Handle 新建 Record 并复制必要元数据，不修改可能共享内部状态的原 Record；WithAttrs 在预绑定之前先清洗字段。

package main

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

type SecurityHandler struct {
    next      slog.Handler
    minLevel slog.Leveler
    sensitive map[string]struct{}
}

func NewSecurityHandler(next slog.Handler, minLevel slog.Leveler, keys ...string) *SecurityHandler {
    if minLevel == nil {
        // 未提供阈值时沿用 slog 的常用默认级别 Info。
        minLevel = slog.LevelInfo
    }
    sensitive := make(map[string]struct{}, len(keys))
    for _, key := range keys {
        // 构造时复制并规范化配置，之后只读即可并发共享。
        sensitive[strings.ToLower(key)] = struct{}{}
    }
    return &SecurityHandler{next: next, minLevel: minLevel, sensitive: sensitive}
}

func (h *SecurityHandler) Enabled(ctx context.Context, level slog.Level) bool {
    // 同时满足包装器阈值和下游 Handler 条件才记录。
    return level >= h.minLevel.Level() && h.next.Enabled(ctx, level)
}

func (h *SecurityHandler) Handle(ctx context.Context, record slog.Record) error {
    // 新建 Record，避免修改可能与其他副本共享内部状态的属性区。
    clean := slog.NewRecord(record.Time, record.Level, record.Message, record.PC)
    record.Attrs(func(a slog.Attr) bool {
        clean.AddAttrs(h.sanitizeAttr(a))
        return true
    })
    // 下游写入失败必须原样返回给调用链。
    return h.next.Handle(ctx, clean)
}

func (h *SecurityHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
    clean := make([]slog.Attr, 0, len(attrs))
    for _, a := range attrs {
        // Logger.With 绑定的字段不会进入原 Record，必须在这里清洗。
        clean = append(clean, h.sanitizeAttr(a))
    }
    return &SecurityHandler{
        next: h.next.WithAttrs(clean), minLevel: h.minLevel, sensitive: h.sensitive,
    }
}

func (h *SecurityHandler) WithGroup(name string) slog.Handler {
    // 分组语义交给下游实现，安全配置保持不变。
    return &SecurityHandler{
        next: h.next.WithGroup(name), minLevel: h.minLevel, sensitive: h.sensitive,
    }
}

func (h *SecurityHandler) sanitizeAttr(a slog.Attr) slog.Attr {
    if a.Equal(slog.Attr{}) {
        return a
    }
    if _, ok := h.sensitive[strings.ToLower(a.Key)]; ok {
        return slog.String(a.Key, "[REDACTED]")
    }
    value := a.Value.Resolve()
    if value.Kind() != slog.KindGroup {
        a.Value = value
        return a
    }
    children := value.Group()
    clean := make([]slog.Attr, 0, len(children))
    for _, child := range children {
        // 对任意深度的 slog.Group 继续应用相同字段规则。
        clean = append(clean, h.sanitizeAttr(child))
    }
    a.Value = slog.GroupValue(clean...)
    return a
}

func main() {
    level := new(slog.LevelVar)
    level.Set(slog.LevelInfo)

    base := slog.NewJSONHandler(os.Stdout, nil)
    handler := NewSecurityHandler(base, level,
        "password", "token", "authorization", "cookie",
    )
    logger := slog.New(handler)

    // Debug 低于当前阈值，不会交给下游 Handler。
    logger.Debug("调试连接", "token", "debug-secret")
    logger.Info("用户登录",
        slog.String("user_id", "u-1024"),
        slog.String("password", "plain-secret"),
        slog.Group("request",
            slog.String("method", "POST"),
            slog.String("authorization", "Bearer secret"),
        ),
    )
}

示例中没有额外互斥锁：sensitive 在构造后不再写入，LevelVar 本身支持并发读写，下游标准 Handler 负责自己的写入同步。如果把可变缓存、计数器或文件轮转状态加入自定义 Handler，就必须为新增状态设计同步策略。

接入动态级别并检查审计边界

如果服务需要在故障排查期间临时提高日志详细度，可以保留 LevelVar 的引用并动态更新：

var programLevel slog.LevelVar
programLevel.Set(slog.LevelInfo)

handler := NewSecurityHandler(
    slog.NewJSONHandler(os.Stdout, nil),
    &programLevel,
    "password", "token", "authorization",
)
logger := slog.New(handler)

// 排障窗口开始时临时允许 Debug，结束后应恢复为 Info。
programLevel.Set(slog.LevelDebug)
logger.Debug("缓存诊断", "token", "temporary-secret")
programLevel.Set(slog.LevelInfo)

动态降低阈值会增加日志量，但不会绕过字段脱敏，因为两项控制位于同一个包装 Handler 中。正式接入前可按下面的清单审阅：

• 预绑定字段：logger.With("token", value) 是否仍被替换；
• 嵌套字段：slog.Group 内的 password、authorization 是否进入递归规则；
• 值解析：实现 LogValuer 的类型是否在 Resolve 后再检查分组；
• 级别边界：等于阈值时保留，低于阈值时过滤；
• 错误传递：下游 Handle 返回的写入错误是否完整返回；
• 配置不可变：敏感字段集合是否在 Handler 发布给多 goroutine 后保持只读。

常见问题

能不能只用 HandlerOptions.ReplaceAttr？

可以。若只需要给单个 JSONHandler 或 TextHandler 做字段替换，ReplaceAttr 更短。自定义包装 Handler 更适合同时封装级别策略、复用到不同下游，并明确处理 WithAttrs、动态级别和错误传递。

为什么不直接修改传入的 Record？

Record 的副本可能共享隐藏的属性状态。官方文档建议修改前调用 Clone，或者像本文一样新建 Record 并遍历旧 Attr。新建方式也便于逐个应用递归清洗。

按字段名脱敏能保证没有秘密泄露吗？

不能。调用处把令牌拼进消息文本、使用未登记的字段名，或在任意对象的字符串表示中泄露秘密，都会超出这套规则。Handler 是统一防线，不是记录敏感数据的许可；核心原则仍是只记录排障真正需要的最少信息。

为什么 WithAttrs 也必须清洗？

Logger.With 会把公共属性预先交给 Handler 的 WithAttrs。如果包装器只在 Handle 遍历 Record，这些预绑定字段可能已经进入下游 Handler，因而绕过当前层的脱敏逻辑。

小结

一个可靠的 slog 安全包装器要守住四个接口：Enabled 尽早过滤级别，Handle 清洗每条记录，WithAttrs 阻止预绑定字段绕过规则，WithGroup 保持分组语义。再配合不可变敏感键集合、递归 Group 处理和动态 LevelVar，就能在不重写标准输出器的前提下，把字段脱敏与日志级别策略集中到一处。