Go slog.Handler.WithGroup 怎么组织嵌套字段：日志上下文与输出验证

日志平台里最难用的字段，往往不是没有写，而是层级没有写清：同一条记录里既有请求的 method，又有下游请求的 method，搜索时只能靠约定俗成的前缀。Go 1.21 引入的 log/slog 用 Logger.WithGroup 把这些字段放进命名分组；真正需要排查时，还要看它在 TextHandler 和 JSONHandler 下分别长什么样。

先复现一个字段冲突现场

假设服务同时记录入口请求和下游请求。如果直接写两个 method，文本日志看起来只是重复键，JSON 日志还可能因为处理器策略不同而覆盖或变得难以检索。先用分组把边界写出来：

package main

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

func main() {
    logger := slog.New(slog.NewTextHandler(os.Stdout, nil))
    logger = logger.With("service", "checkout-api")

    logger.WithGroup("request").LogAttrs(context.Background(), slog.LevelInfo, "received",
        slog.String("method", "POST"),
        slog.String("path", "/orders"),
    )
}

可见结果应包含 service=checkout-api、request.method=POST 和 request.path=/orders。这里先核对输出形状，不要急着写自定义处理器；标准处理器已经能覆盖大多数服务日志场景。

WithGroup 在 TextHandler 与 JSONHandler 中有什么差别

分组的逻辑没有因为输出格式改变：后续属性都属于 request。改变的是展示方式。文本处理器用点号把路径压平，JSON 处理器保留对象层级，这正好对应“人看日志”和“程序检索日志”两种使用方式。

text := slog.New(slog.NewTextHandler(os.Stdout, nil))
json := slog.New(slog.NewJSONHandler(os.Stdout, nil))

text.WithGroup("request").Info("received",
    "method", "POST", "path", "/orders")
json.WithGroup("request").Info("received",
    "method", "POST", "path", "/orders")

TextHandler 的核心字段类似 request.method=POST；JSONHandler 的核心结构类似 "request":{"method":"POST","path":"/orders"}。验收时要用实际输出检查，而不是根据处理器名称猜格式。

把稳定字段和请求字段分开绑定

服务名、版本、机房这类字段在进程生命周期内通常不变，可以在创建 Logger 时用 With 绑定。请求 ID、HTTP 方法和路径则应该在请求范围内加入 request 分组。这样既减少重复代码，也让检索条件稳定。

base := slog.New(slog.NewJSONHandler(os.Stdout, nil)).With(
    slog.String("service", "checkout-api"),
    slog.String("version", "2026.08"),
)

requestLog := base.WithGroup("request").With(
    slog.String("id", "req-7f3a"),
    slog.String("method", "POST"),
)
requestLog.Info("handler finished", slog.Int("status", 200))

这条记录里，service 和 version 在根层，id、method、status 在 request 下。不要把用户输入直接作为分组名；分组名应来自有限的程序常量，否则日志字段会不断膨胀。

自定义 Handler 时分层检查三个方法

当日志输出缺少嵌套层级，或者同一字段出现两次，问题通常在包装 Handler 没有保留上下文。排查顺序可以固定成三层。

先看 WithAttrs 是否复制了已有属性

Logger.With 会让 Handler 收到预绑定属性。自定义 Handler 的 WithAttrs 应返回一个带有这些属性的新 Handler，不能修改共享实例，否则并发请求可能互相串字段。

再看 WithGroup 是否保留了分组栈

WithGroup("request") 之后，后续属性都要在这个分组语义里处理；连续调用多个分组时，还要按顺序保留分组栈。空分组名在标准语义中不应凭空制造一层。

最后看 Handle 是否只写一条记录

一个 Record 应该对应一次序列化输出。处理器不应在 Handle 中重复追加已由 WithAttrs 预处理的字段，也不能因为字段为空就改变根层与分组层的规则。

可用一个小测试做反向验证：先绑定 service，再打开 request 分组，写入 method，最后检查根层只有一个 service，请求对象只有一个 method。这个测试比只比较整行字符串更耐格式变化。

常见问题：slog 分组日志的边界

WithGroup 会为每个请求自动创建一条日志吗？

不会。它只改变后续属性的命名范围，是否产生记录仍由 Info、Log 或 LogAttrs 调用决定。

TextHandler 和 JSONHandler 的分组语义一样吗？

分组关系一致，但呈现不同：文本输出通常使用点号路径，JSON 输出通常使用嵌套对象。日志采集规则应针对实际格式配置。

为什么自定义 Handler 里 WithGroup 看起来没有效果？

常见原因是包装 Handler 没有实现或转发分组状态，或者在 Handle 时只处理了当前记录、丢掉了之前的分组栈。先用标准 JSONHandler 对比，再逐层检查包装方法。

请求路径适合直接放进分组名吗？

不适合。分组名应保持低基数，路径、用户 ID 等高变化值应作为属性值记录，并按隐私和日志成本要求脱敏。

把输出形状固定成可检索的约定

WithGroup 的价值不只是让日志更好看，它把字段归属变成了可以测试的契约：稳定字段留在根层，请求和下游字段进入固定分组，文本与 JSON 各自按消费者需要展示。上线前用一条真实样例同时验收键名、层级和敏感字段处理，后面的日志查询会省掉不少猜测。