Go slog.WithGroup 如何组织嵌套日志：字段分组、Handler 与输出验收

日志里同时出现两组 id 时，问题通常不在字段本身，而在它们没有边界：请求的 id、用户的 id 和订单的 id 混在一行，检索时很难判断谁属于谁。Go 1.21 带来的 log/slog 用结构化属性解决了这件事，其中 Logger.WithGroup 可以把后续字段放进命名分组，输出既能读，也方便日志系统按路径过滤。

WithGroup 解决的是字段归属，不只是换一种打印格式

先看一条没有分组的日志：slog.Info("request finished", "id", requestID, "id", userID)。即使底层处理器允许重复键，读日志的人也必须回到代码里猜两个 id 的来源。把调用改成分组后，语义就清楚了：

logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
logger.WithGroup("request").With(
    slog.String("id", "req-9f2"),
    slog.String("method", "GET"),
).WithGroup("user").Info("request finished", "id", "u-18")

更常见的写法是先为请求建立上下文 logger，再在同一条事件里添加用户组。组不是人为拼出的键名，而是交给 Handler 记录的结构信息。

requestLogger := logger.WithGroup("request").With(
    slog.String("id", "req-9f2"),
    slog.String("method", "GET"),
)

requestLogger.LogAttrs(
    context.Background(),
    slog.LevelInfo,
    "request finished",
    slog.Group("user", slog.String("id", "u-18")),
    slog.Int("status", 200),
)

这段代码的关键是：request 组来自 logger 的长期属性，user 组来自这一条日志的临时属性。两者的生命周期不同，排查线上请求时更容易复用。

TextHandler 与 JSONHandler 会怎样表达同一组字段

slog 把日志前端和输出后端分开。调用方只描述消息与属性，具体怎么落盘由 Handler 决定。下面用同一组数据切换两个标准处理器，先观察差异，再决定日志采集端要按什么路径解析。

func newLogger(jsonOutput bool) *slog.Logger {
    var handler slog.Handler
    if jsonOutput {
        handler = slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{})
    } else {
        handler = slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{})
    }
    return slog.New(handler)
}

func writeLog(logger *slog.Logger) {
    logger.WithGroup("request").LogAttrs(
        context.Background(), slog.LevelInfo, "finished",
        slog.String("id", "req-9f2"),
        slog.Group("user", slog.String("id", "u-18")),
    )
}

文本处理器适合人工查看，通常会把组名和字段名按层次拼接；JSON 处理器则保留对象层级。不要只在终端里看一眼就下结论，实际验收应把输出送进解析器，确认 request.id 和 request.user.id 的路径稳定。

自定义 Handler 最容易漏掉的，是 WithGroup 的状态

如果项目要把日志写入自己的缓冲区或事件模型，可以实现 slog.Handler。这里有一个判断标准：WithGroup 不能原地修改共享 Handler 后返回自己，否则不同请求的组路径可能互相污染。通常应返回一个携带新组路径的 Handler 副本。

type groupHandler struct {
    next   slog.Handler
    groups []string
}

func (h *groupHandler) Enabled(ctx context.Context, level slog.Level) bool {
    return h.next.Enabled(ctx, level)
}

func (h *groupHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
    return &groupHandler{next: h.next.WithAttrs(attrs), groups: append([]string{}, h.groups...)}
}

func (h *groupHandler) WithGroup(name string) slog.Handler {
    groups := append([]string{}, h.groups...)
    if name != "" { groups = append(groups, name) }
    return &groupHandler{next: h.next.WithGroup(name), groups: groups}
}

func (h *groupHandler) Handle(ctx context.Context, record slog.Record) error {
    // 实际项目里在这里把 groups 和 record.Attrs() 写入事件模型。
    return h.next.Handle(ctx, record)
}

这个示例把组状态保存在新实例里，避免并发日志写入时共享切片被追加。真实 Handler 还要处理属性分组、LogValuer 展开、敏感字段脱敏和 WithAttrs 的预格式化；先把层级状态做对，再谈性能。

旧式 key-value 写法什么时候仍然够用

只有两三个不会重复的字段时，slog.Info("started", "port", 8080) 足够直接。字段一多，建议改用 slog.String、slog.Int 和 slog.Group，这样类型和层级都显式，静态检查也更容易发现键值数量写错。

不要把所有属性都塞进一个大组。请求组、用户组和数据库组分别表达生命周期和归属；如果日志平台的查询语法不支持嵌套对象，可以在自定义 Handler 的最后一步展平为 request.id，但这应是输出适配，而不是调用方自己拼接。

上线前用一条验收日志确认三件事

1. 同名字段是否都带有清晰组路径，例如 request.id 与 request.user.id。
2. TextHandler 和 JSONHandler 是否都保留了分组语义，而不是出现重复键覆盖。
3. 并发请求下，上一条日志的组名是否没有泄漏到下一条。

可以在测试里写入固定的 req-9f2 和 u-18，再将 JSON 输出解码为 map[string]any 检查字段路径。这里不要只比较整行字符串，时间、来源文件和格式化细节可能随处理器选项变化。

相关问题

WithGroup 和 slog.Group 有什么区别？

WithGroup 作用在 logger 或 handler 的后续属性上，适合一批共享字段；slog.Group 是一条日志里的单个分组属性，适合局部事件数据。

空字符串作为组名会发生什么？

标准 Handler 会把空组中的属性内联到当前层级。它适合条件性地取消一层包装，但不适合表达稳定的业务命名空间。

为什么自定义 Handler 不建议直接修改 groups 切片？

logger 通常会被多个 goroutine 共享。原地追加可能让不同请求看到彼此的分组路径，返回带独立状态的新 Handler 更安全。

小结

WithGroup 的价值是让字段归属进入日志结构：公共上下文用 logger 组，局部数据用 slog.Group，输出端再根据 TextHandler、JSONHandler 或自定义 Handler 做格式适配。只要把组路径、并发隔离和最终解析结果一起验收，结构化日志就不会停留在“看起来像键值对”的层面。