slog.WithGroup 后字段为什么嵌套层级不一致

直接结论：slog.WithGroup 建立的是“后续属性”的分组作用域，不会把此前已经通过 With 绑定的字段重新搬进组内。再加上 JSONHandler 用嵌套对象表示组、TextHandler 用点号限定键名，同一份日志在肉眼看来很容易像是“层级不一致”。如果只有自定义 Handler 的结果不同，还要检查它是否按调用顺序保存了活动组。

触发信号：线上常见的三种“不一致”

我第一次遇到这个问题时，告警平台里同一个 request_id 有时在根级，有时出现在 request 对象里。代码没有并发修改 Logger，真正的差异来自 Logger 的构造顺序。排查时先把现象归到下面三类，通常十分钟内就能缩小范围。

快速判断：先画出 Logger 的分组边界

官方 Handler 契约的关键句是：WithGroup 把新组追加到现有组序列，随后通过 With 或日志记录加入的属性，应由这组名称限定。换言之，调用顺序就是结构的一部分。

下面这段最小程序把根级字段、组内预绑定字段和调用现场字段放在同一条记录中。为避免时间字段干扰比较，示例用 ReplaceAttr 移除顶层时间。

package main

import (
    "log/slog"
    "os"
)

func main() {
    // 只移除顶层时间，保留业务分组和字段结构
    opts := &slog.HandlerOptions{
        ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
            if len(groups) == 0 && a.Key == slog.TimeKey {
                return slog.Attr{}
            }
            return a
        },
    }

    // service 在建立 request 分组之前绑定，因此保持在根级
    base := slog.New(slog.NewJSONHandler(os.Stdout, opts)).
        With("service", "billing")

    // 这之后通过 With 或 Info 添加的字段都进入 request 组
    requestLog := base.WithGroup("request").
        With("id", "r-42")

    // method 是当前日志记录的属性，也受活动分组 request 限定
    requestLog.Info("accepted", "method", "GET")
}

核心结构会是：

{"level":"INFO","msg":"accepted","service":"billing","request":{"id":"r-42","method":"GET"}}

如果把调用顺序改成先 WithGroup("request")，再 With("service", "billing")，那么 service 也会落入 request。这不是随机行为，而是两个不同的 Logger 派生链。

处理步骤一：不要把 Group 和 WithGroup 当成同一作用域

slog.Group 创建的是当前属性列表中的一个组属性；Logger.WithGroup 则返回一个带活动分组的新 Logger，并持续影响后续属性。两者可以生成相似输出，但生命周期不同。混用时最常见的误判，是认为一次 slog.Group 会影响后面的其他参数。

// 只有 method 和 path 属于临时 request 组
logger.Info(
    "served",
    slog.Group("request",
        slog.String("method", "GET"),
        slog.String("path", "/health"),
    ),
    // status 与临时组并列，仍在根级
    slog.Int("status", 200),
)

// 活动分组影响这个派生 Logger 后续添加的全部属性
requestLog := logger.WithGroup("request")
requestLog.Info(
    "served",
    slog.String("method", "GET"),
    slog.String("path", "/health"),
    slog.Int("status", 200),
)

如果团队约定请求字段都在 request 下，优先在请求入口创建一次派生 Logger，再把它传给下游函数。不要让每个调用点自行决定使用 Group 还是 WithGroup。

处理步骤二：把结构语义与输出格式分开验证

内置 Handler 对组的展示不同：JSONHandler 把组编码为 JSON 对象，TextHandler 则把组名和属性名用点号连接。下面两种输出看起来层级不同，语义其实一致。

{"request":{"method":"GET","id":"r-42"}}
request.method=GET request.id=r-42

文本格式还有一个容易忽略的边界：组名或键名本身如果包含点号，输出中不会额外转义。看到 a.b.c 时，单靠文本无法判断它是两层组加一个键，还是键名本身含点。需要在日志管道中重建严格层级时，优先使用 JSON，或通过 ReplaceAttr 对组件中的点号做统一编码。

处理步骤三：固定 Logger 工厂，消除调用顺序漂移

最稳妥的修复不是在每个日志点补组名，而是集中定义 Logger 的构造顺序。下面的工厂明确规定：服务字段在根级，请求字段在 request 组内。

package logging

import "log/slog"

func ForRequest(base *slog.Logger, service, requestID string) *slog.Logger {
    // 先绑定全局维度，保证它始终位于根级
    root := base.With(
        slog.String("service", service),
    )

    // 再建立请求作用域，后续业务字段稳定进入 request 组
    return root.WithGroup("request").With(
        slog.String("id", requestID),
    )
}

使用时不要再次创建同名组，否则会得到 request.request。下游只负责添加字段：

// 工厂已经建立 request 组，下游直接追加业务属性
requestLog := logging.ForRequest(base, "billing", "r-42")
requestLog.Info(
    "accepted",
    slog.String("method", "GET"),
    slog.Int("attempt", 1),
)

自定义 Handler：重点检查 WithAttrs 与 WithGroup

如果内置 Handler 输出稳定，而自定义 Handler 把字段全摊平，问题通常不在 Logger。自定义实现需要返回新 Handler，并保持两类状态：已经绑定的属性，以及按顺序追加的活动组。Handle 处理 Record 属性时，必须使用对应的组序列限定后续键。

还要遵守几个边界：空名称的 WithGroup("") 是无操作；空键 Group 的属性应内联；没有属性的组应忽略。若自定义实现仍输出空对象或凭空新增层级，就与标准 Handler 契约不一致。

回滚路径：先恢复单一输出结构

结构化日志变更可能影响告警查询、索引模板和仪表盘。若上线后查询大面积失效，先把 Logger 工厂回滚到变更前版本，不要同时修改采集规则与应用字段。需要临时止损时，可取消新增的 WithGroup，恢复根级字段；待告警和存储映射调整完成后，再一次性切换到稳定分组结构。

回滚时保留字段名，不要把 request.id 顺手改成 request_id。结构和命名同时变化，会让问题难以归因。

告警确认：用测试锁定结构，不靠肉眼抽样

对 JSON 输出做结构断言最可靠。测试不应比较时间字段或整行字符串，而应解析 JSON 后检查根级与组内键。

func TestRequestLoggerShape(t *testing.T) {
    var buf bytes.Buffer

    // 移除时间，减少与分组无关的动态字段
    opts := &slog.HandlerOptions{
        ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
            if len(groups) == 0 && a.Key == slog.TimeKey {
                return slog.Attr{}
            }
            return a
        },
    }

    // 生成一条具有固定分组契约的日志
    base := slog.New(slog.NewJSONHandler(&buf, opts))
    log := ForRequest(base, "billing", "r-42")
    log.Info("accepted", slog.String("method", "GET"))

    // 解析后分别断言根级字段与 request 对象
    var got map[string]any
    if err := json.Unmarshal(buf.Bytes(), &got); err != nil {
        t.Fatalf("解析日志失败: %v", err)
    }
    if got["service"] != "billing" {
        t.Fatalf("service 应位于根级，实际为 %#v", got["service"])
    }
    request, ok := got["request"].(map[string]any)
    if !ok || request["id"] != "r-42" || request["method"] != "GET" {
        t.Fatalf("request 分组结构不符合约定: %#v", got["request"])
    }
}

复盘项

• 是否存在多个 Logger 工厂，导致 With 与 WithGroup 的顺序不一致？
• 是否把临时 slog.Group 和持久化 WithGroup 混用于同一类字段？
• 日志采集查询是否同时兼容 JSON 嵌套键与文本点号键？
• 自定义 Handler 是否复制状态并保留活动组序列，而不是修改共享实例？
• 是否为根级字段、组内字段、空组和嵌套组建立了契约测试？

判断 slog 分组问题时，记住一条就够了：Logger 的派生顺序决定字段归属，Handler 只决定这种归属如何呈现。先固定 Logger 构造链，再检查输出格式，层级不一致通常就不再神秘。

参考资料

• Go 标准库 log/slog 文档
• Go 官方博客：Structured Logging with slog