Go slog 日志字段怎么安全流转：Attr、Handler 与敏感信息边界

订单接口刚上线时，日志里最先变得难维护的是同一个请求散着打出来的一堆凌乱信息：订单号藏在日志正文字符串里，用户ID塞在日志前缀里，支付卡号甚至直接跟着字段名裸落到了JSON日志中。Go 1.21 之后，log/slog 可以把这些信息统一规整成结构化事件，但字段并不是“传进去就原样输出”，它会经过 slog.Record、Handler 和属性重写几个环节流转。

把 slog.Attr 当成日志事件的输入，把 Handler 当成最后一道输出策略：先统一字段，再在 Handler 层做分组、等级过滤和脱敏，生产日志才不会越写越乱。

先看字段是怎样流过 slog.Handler 的

一条结构化日志大致经历四步：调用点创建属性，Logger 把属性装入 Record，Handler 根据配置处理 Record，最后由文本或 JSON Handler 写入目标存储。这个顺序很重要，因为同一个 key 是否嵌套、是否被过滤、是否被替换，都发生在后两步。

下面的例子模拟订单请求场景。业务代码只描述事实即可，输出格式完全交给 Handler 管控：

package main

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

func writeOrderLog(ctx context.Context, logger *slog.Logger) {
    logger.InfoContext(ctx, "order accepted",
        slog.String("order_id", "O-20260724-018"),
        slog.Int64("user_id", 42),
        slog.Group("payment",
            slog.String("method", "bank_card"),
            slog.String("card_last4", "6812"),
        ),
    )
}

func main() {
    handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})
    writeOrderLog(context.Background(), slog.New(handler))
}

JSON Handler 会把属性写成标准 JSON 对象。slog.Group 表示一个逻辑组，后续如果用 WithGroup，组名还会影响属性的完整路径。这里先记住一个实用检查方法：不要靠肉眼判断“日志看起来像对”，而是直接解析JSON，断言 order_id、user_id 和 payment.method 是否在预期位置。

WithGroup 和 Group 的差别，落在最终 JSON 路径上

slog.Group("payment", ...) 是一次性把属性放进 payment 组；logger.WithGroup("order") 则是给这个 Logger 后续产生的所有属性加一个持久的路径前缀。两者都不是简单的文本拼接，因此不能按普通字符串前缀的思路排查问题。

orderLogger := logger.WithGroup("order")
orderLogger.Info("status changed",
    slog.String("id", "O-20260724-018"),
    slog.String("status", "paid"),
)

// 结果形态：{"order":{"id":"O-20260724-018","status":"paid"}}

如果订单服务和支付服务都要记录同一批字段，建议在边界处创建带组的 Logger 实例，而不是每一处调用都手写 order.id。这样可以集中调整输出格式，也避免一个调用点写成 order_id、另一个写成 id 的字段名不统一问题。

动态值要在读取时确认类型

slog.Any 适合传入暂时没有专用构造器的值，但它会把值的实际类型完全交给 Handler 处理。把一个可变的 map 或未封装的错误对象直接塞进去，输出可能随底层类型和实现变化。金额、状态、ID 这些字段应优先使用 slog.String、slog.Int64 等明确构造器；复杂对象先提取出稳定字段再传入。

用 ReplaceAttr 把敏感字段挡在输出前

脱敏放在业务调用点看似简单，实际很容易漏掉：一个旧接口叫 card_number，另一个新接口叫 pan，还有第三处把 token 放进了自定义组里。更稳妥的做法是让 JSON Handler 统一经过 ReplaceAttr，按属性 key 做最后检查。

func redact(groups []string, attr slog.Attr) slog.Attr {
    switch attr.Key {
    case "card_number", "pan", "authorization", "access_token":
        return slog.String(attr.Key, "[REDACTED]")
    case "card_last4":
        // 只允许保留末四位，完整卡号不应进入这里。
        return slog.String(attr.Key, attr.Value.String())
    default:
        return attr
    }
}

handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
    Level:       slog.LevelInfo,
    ReplaceAttr: redact,
})
logger := slog.New(handler)
logger.Warn("payment retry",
    slog.String("pan", "4111111111111111"),
    slog.String("reason", "gateway_timeout"),
)

需要留意 group 路径参数 groups。如果同一个 key 在不同业务域有不同规则，可以根据 groups 和 attr.Key 联合判断；如果所有支付卡号都应该统一脱敏，就保持规则简单，减少漏网分支。

不要把脱敏函数写成“遇到指定长度字符串就替换”。日志里可能有用户备注、错误信息和订单标题，按值匹配会误伤正常信息，也挡不住换一个字段名继续泄漏的情况。

用测试读取最终 JSON，而不是只测调用参数

字段生命周期的验收点在输出端。下面用 bytes.Buffer 接住 Handler 的输出结果，再解码成 map；实际项目可以把同样的断言放进日志单元测试或接口烟雾测试里。

var buf bytes.Buffer
handler := slog.NewJSONHandler(&buf, &slog.HandlerOptions{
    ReplaceAttr: redact,
})
slog.New(handler).Info("payment retry",
    slog.String("pan", "4111111111111111"),
    slog.Group("order", slog.String("id", "O-18")),
)

var got map[string]any
if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
    t.Fatal(err)
}
if got["pan"] != "[REDACTED]" {
    t.Fatalf("pan was not redacted: %#v", got["pan"])
}
order, ok := got["order"].(map[string]any)
if !ok || order["id"] != "O-18" {
    t.Fatalf("unexpected order group: %#v", got["order"])
}

这类测试至少覆盖三件事：敏感字段确实被替换，分组路径没有被错误扁平化，正常字段仍然保持原值。若日志还要供 Loki、ClickHouse 或告警规则使用，再补一条字段类型断言，避免把数字 ID 无意转成字符串导致查询异常。

几个容易把日志边界弄乱的写法

• 在业务里把整段 JSON 先拼成字符串，再交给 slog.String("payload", ...)。这样下游只能看到一个不可检索的大字段，完全发挥不了结构化日志的优势。
• 只配置 LevelInfo，却以为它会自动隐藏敏感字段。等级过滤和字段脱敏是两件完全独立的事。
• 在 ReplaceAttr 中读取复杂值并做昂贵序列化操作。日志本来是旁路信息，脱敏逻辑不应拖慢请求主路径。
• 只检查开发机终端输出。Text Handler 与 JSON Handler 的分组表现不同，线上实际使用的格式必须单独验收。

常见问题

slog 适合替换已有的 log.Printf 吗？

适合从新接口和需要检索的关键路径开始替换。旧日志如果没有稳定字段，直接批量改写的收益不一定高，先统一字段命名和输出目标更实际。

ReplaceAttr 能不能修改日志消息正文？

它主要处理日志携带的属性。需要统一改消息或增加上下文时，可以包装自定义 Handler，在调用下层 Handler 前调整 Record，但要保持规则短小并补全对应测试。

为什么测试里看到的数字变成了 float64？

这是 JSON 解码到 map[string]any 的默认行为，不代表 Handler 把整数改坏了。对数字字段使用结构体解码或 json.Decoder.UseNumber 做精确断言就可以避免这个问题。

敏感字段只靠日志脱敏够不够？

不够。请求体、错误追踪、消息队列和数据库审计可能有各自的输出路径。ReplaceAttr 是日志出口的一道门，还要在输入校验、权限和存储层控制敏感数据范围。

把日志字段当成一条可验证的数据链

调用点负责表达业务事实，Attr 负责携带稳定类型，Handler 负责格式、分组、等级和脱敏，测试则从最终 JSON 反向确认结果。这样排查日志问题时，能明确知道是字段创建、路径分组还是输出重写出了偏差。