Go slog.Group 怎么组织嵌套业务字段

slog.Group 的核心作用，是把同一业务对象的多个属性放到一个稳定键下面。订单日志里同时出现请求、用户、订单和支付字段时，不要把所有键都铺在顶层；可以用 request、order、payment 分组，让 JSON 保留嵌套对象，让文本日志用限定键表达相同层级。

我在改造一批结算日志时，最直接的收益并不是“日志看起来更漂亮”，而是相同的 id、status 不再互相打架。查询时能明确写 order.id 或 payment.status，字段含义比 order_id、payment_status 到处散落更稳定。

官方文档：https://pkg.go.dev/log/slog

结构化日志为什么需要业务分组

log/slog 从 Go 1.21 进入标准库，组属性是它处理结构化字段的一部分。官方定义中，slog.Group 返回一个组值属性：第一个参数是组键，后续参数按普通日志参数转换为属性。它适合把几个键值对收进一个业务对象，也能避免不同对象里的同名键产生歧义。

比如一次结算事件里，订单和支付都可能有 id、status。如果全部平铺，团队很快会发明越来越长的前缀；如果按对象分组，字段模型更接近业务本身。这里的分组只是结构，不是权限隔离，更不会自动脱敏。

先为日志事件划定稳定边界

我通常先列出一个 Record 中长期存在的对象，再决定组名。请求侧保留 request group，订单侧保留 order group；组内再放 method、path、order_id、amount 等稳定字段。Logger 负责产生事件，业务组负责说明字段归属。

组名最好固定、简短、低基数。不要把订单号、用户 ID 之类动态值当成组名，否则日志字段路径会随每条记录变化，检索和聚合都更难维护。动态值应该是属性值，而不是结构键。

单次事件直接使用 slog.Group

只在当前事件中出现一次的嵌套对象，直接放进 Info、Warn 或 LogAttrs 调用即可。下面的写法把请求与订单拆成两个兄弟组，顶层只保留事件本身的时间、级别和消息。

package main

import (
    "log/slog"
    "os"
)

func main() {
    // JSONHandler 会把 Group 输出为真正的嵌套对象。
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

    logger.Info("checkout completed",
        // request 组只描述当前 HTTP 请求。
        slog.Group("request",
            slog.String("method", "POST"),
            slog.String("path", "/checkout"),
        ),
        // order 组保存订单自己的标识和金额，金额使用最小货币单位。
        slog.Group("order",
            slog.String("id", "ord_1048"),
            slog.Int64("amount_cent", 2599),
        ),
    )
}

这里没有必要把组内键再写成 request_method 或 order_id。在 JSON 中它们已经位于对应对象内；在内置 TextHandler 中，处理器会用类似 request.method、order.id 的限定键保持区别。

重复上下文改用 Logger.WithGroup

如果一段业务代码连续记录同一个订单，我更倾向于创建派生 Logger。Logger.WithGroup(name) 会让之后添加到该 logger 的属性都受组名限定；再配合 With 固定订单 ID，可以避免每条日志重复写同一个外层组。

func logPayment(logger *slog.Logger, orderID string) {
    // 派生 logger 不会修改原 logger；order 组与 id 会复用于后续事件。
    orderLog := logger.WithGroup("order").With(
        slog.String("id", orderID),
    )

    orderLog.Info("payment authorized",
        // payment 作为 order 内的子组，表达支付对象自己的字段。
        slog.Group("payment",
            slog.String("channel", "card"),
            slog.String("status", "authorized"),
        ),
    )
}

官方 Handler 契约把 WithGroup("s") 后记录属性的效果，定义为与在单次事件里使用 slog.Group("s", ...) 等价。区别主要在作用范围：slog.Group 只影响当前属性，WithGroup 影响派生 logger 后续添加的属性。空字符串组名不会开启新组，WithGroup("") 会返回接收者。

领域对象用 LogValuer 输出成组字段

当同一个领域对象在很多位置都要记录时，继续手写 slog.Group 容易造成字段漂移。可以让类型实现 LogValuer，并在 LogValue 中返回 slog.GroupValue。这样日志层拿到的是稳定表示，领域对象也能主动排除不应记录的字段。

type Customer struct {
    ID       string
    Tier     string
    Email    string
    Password string
}

func (c Customer) LogValue() slog.Value {
    // 只返回允许进入日志的稳定字段，敏感字段不进入 GroupValue。
    return slog.GroupValue(
        slog.String("id", c.ID),
        slog.String("tier", c.Tier),
    )
}

func logCustomer(logger *slog.Logger, c Customer) {
    // customer 键包住 LogValuer 返回的组值，形成领域对象边界。
    logger.Info("customer loaded", "customer", c)
}

这种方式的代价是日志表示进入了领域类型。对于稳定核心对象很合适；对于一次性 DTO 或不同模块需要完全不同的字段集合，显式 slog.Group 往往更清楚。

JSON 与文本输出有什么区别

HandlerOptions.ReplaceAttr 不会把整个 Group 属性直接交给回调，而是逐个处理组内属性，并提供当前打开的组名切片。需要按路径脱敏时，可以同时判断最后一个组名和属性键。

opts := &slog.HandlerOptions{
    ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
        // 仅在 customer 组内隐藏 email，避免误伤其他同名字段。
        if len(groups) > 0 && groups[len(groups)-1] == "customer" && a.Key == "email" {
            return slog.String("email", "[redacted]")
        }
        return a
    },
}

采用时最容易踩的几个坑

• 层级过深：两层通常已经能表达业务对象与子对象。继续嵌套会让查询路径、索引模板和告警规则都变长。
• 组名动态变化：组名应是 schema，订单号、租户号、区域等数据应放在值里。
• 把分组当脱敏：Group 只改变结构。密码、令牌、完整卡号等不应先进入日志，再指望分组保护。
• 同一对象多套命名：固定使用 order.id 后，就不要在另一些日志里又写顶层 order_id，否则查询仍会分裂。
• 忽略处理器差异：自定义 Handler 必须正确实现组限定语义；接入第三方 Handler 时应确认其 JSON、文本或后端字段映射。

如果属性已经先收集为 []slog.Attr，当前标准库还提供 slog.GroupAttrs，它从 Go 1.25 起可用，并比接收任意参数的 slog.Group 更直接。需要兼容更早 Go 版本时，继续使用 slog.Group 即可。

相关问题

slog.Group 可以嵌套吗？

可以。比如 order 里再放 payment，JSON 会保留嵌套对象，文本处理器会继续限定键。建议只在字段确实属于子对象时嵌套。

组里没有属性会输出空对象吗？

标准 Handler 契约要求忽略没有属性的组，即使它有非空组名；空键组则把内部属性内联到当前层。

WithGroup 和 slog.Group 应该选哪个？

只影响一条事件时用 slog.Group；一组连续日志共享同一业务上下文时，用 Logger.WithGroup 创建派生 logger。

分组会提升日志性能吗？

分组首先是结构设计。官方说明 WithAttrs 与 WithGroup 给 Handler 提供预格式化机会，但实际收益取决于处理器和调用方式，不应仅为性能盲目增加层级。