Go log/slog GroupValue 怎样把相关字段归入嵌套组

如果你想让 Go 的结构化日志同时表达“请求上下文”和“请求内部字段”，可以把内层字段先交给 slog.GroupValue 组成一个 Group，再用 slog.Group 给这组字段绑定名称。这样同一批字段会在 JSONHandler 中保持层级，也能让 TextHandler 的输出更容易阅读。

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

需要特别注意两点：GroupValue 构造时会移除空组，传给它的 Attr 切片在构造后不能继续修改。下面按一个小型请求日志场景说明完整写法。

一、先分清 slog.Group 和 GroupValue

slog.Group("request", ...) 负责创建带名字的属性组，适合直接写在日志调用中；slog.GroupValue(...) 返回一个组类型的 slog.Value，适合先把一组字段保存为值，再把它嵌入另一层属性。

package main

import (
    "log/slog"
    "os"
)

func main() {
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

    // 先把同一请求的字段组成一个可复用的 Group 值。
    requestValue := slog.GroupValue(
        slog.String("request_id", "req-20261027"),
        slog.String("method", "GET"),
        slog.Int("attempt", 1),
    )

    // 再给 GroupValue 绑定 request 名称，形成一层嵌套结构。
    logger.Info("request finished", slog.Attr{
        Key:   "context",
        Value: slog.GroupValue(
            slog.Attr{Key: "request", Value: requestValue},
            slog.String("region", "cn-east"),
        ),
    })
}

这段代码的关键不是多写一层函数，而是让“字段集合”和“字段集合的名称”分离。需要把同一个请求组放进不同外层结构时，可以复用已经准备好的 slog.Value。

二、用 slog.GroupValue 组装一层业务字段

如果字段集合不需要单独保存，可以直接把 GroupValue 放入一个带名称的 Attr。相比把每个键值都铺在日志顶层，这种写法更适合请求、用户、数据库等有明确边界的上下文。

func requestAttrs(requestID string, userID int64) slog.Attr {
    // 返回一个带名字的 request 组，调用方只负责把它加入日志。
    return slog.Attr{
        Key: "request",
        Value: slog.GroupValue(
            slog.String("id", requestID),
            slog.Int64("user_id", userID),
        ),
    }
}

func writeLog(logger *slog.Logger) {
    // request 组和 deployment 组互不混淆，便于 JSON 查询。
    logger.Info("query started",
        requestAttrs("req-20261027", 42),
        slog.Group("deployment",
            slog.String("service", "catalog"),
            slog.String("zone", "az-1"),
        ),
    )
}

这里的 slog.Group 是语法上的便捷构造器，而 GroupValue 是值层面的构造器。二者最终都表现为 KindGroup，区别在于前者同时给组命名，后者只负责承载一组 Attr。

三、可选字段为空时为什么不会留下空组

请求日志经常会遇到可选的用户信息或追踪信息。如果把空组原样写入输出，查询端还要处理大量没有内容的对象。GroupValue 在构造时会识别空组并把它们移除，因此可以安全地组合可选字段。

func optionalUser(userID int64, name string) slog.Attr {
    attrs := make([]slog.Attr, 0, 2)

    // 只有字段有实际值时才加入内层组。
    if userID > 0 {
        attrs = append(attrs, slog.Int64("id", userID))
    }
    if name != "" {
        attrs = append(attrs, slog.String("name", name))
    }

    // GroupValue 会过滤其中的空组，但这里仍返回稳定的组名。
    return slog.Attr{Key: "user", Value: slog.GroupValue(attrs...)}
}

当 attrs 为空时，返回的值是空组；把它作为另一个 GroupValue 的成员传入时，空组会被过滤。工程上更推荐像上面一样只向切片加入有效字段，含义更直接，也避免误把空字符串当成真实值。

四、传入 Attr 切片后不要继续修改

官方源码明确要求：传给 GroupValue 的参数切片在构造后不能再被调用方修改。原因是组值会保存这组 Attr 的底层数据，而不是为每个字段复制一份独立对象。

func stableGroup() slog.Value {
    attrs := []slog.Attr{
        slog.String("trace", "t-001"),
        slog.String("span", "s-009"),
    }

    // 构造完成后，attrs 只读；不要再 append、排序或覆盖元素。
    group := slog.GroupValue(attrs...)

    // 如需下一次构造，创建另一份切片，避免共享可变底层数组。
    return group
}

常见误区是把同一个切片当作临时工作区：第一次构造组后清空它，再填入第二批字段。这样做会让组值引用到被修改的数据。需要复用缓冲区时，应先复制出一份 Attr，或者每次使用新的切片。

五、TextHandler 和 JSONHandler 的输出选择

嵌套组的组织方式不依赖具体 Handler，但最终展示形式不同。JSONHandler 通常保留对象层级，适合日志平台按字段查询；TextHandler 使用带组名的键值表达，适合人读和简单采集。

func newLogger(jsonOutput bool) *slog.Logger {
    if jsonOutput {
        // JSONHandler 适合把 request、user 当作结构化对象。
        return slog.New(slog.NewJSONHandler(os.Stdout, nil))
    }

    // TextHandler 仍然保留组的语义，但呈现为文本键值。
    return slog.New(slog.NewTextHandler(os.Stdout, nil))
}

不要为了让文本输出“看起来扁平”而放弃分组。日志后端是否展开组、组名是否带前缀，属于 Handler 的处理策略；业务代码只需要保持字段边界稳定。

六、快速对照表

常见问题

GroupValue 返回的是普通 map 吗？

不是。它返回的是 slog.Value，其 Kind 为 KindGroup，内部保存的是 Attr 列表。

空组一定会从最终日志中消失吗？

GroupValue 构造时会移除空组；如果业务代码把空字符串或零值作为普通 Attr 写入，那些字段并不等同于空组。

可以在另一个 goroutine 中修改传入切片吗？

不可以。构造后应把这组 Attr 当作不可变数据使用；并发写入会同时带来数据竞争和日志内容不稳定。

Value.Resolve 会递归展开组内的 LogValuer 吗？

不会。官方文档说明，Resolve 得到组后不会递归解析组内 Attr 的值，需要由 Handler 或业务逻辑按实际需求处理。

总结：用 GroupValue 表达一组可复用的字段，用 slog.Group 表达组名和嵌套位置；对可选字段保持空组意识，对 Attr 切片遵守构造后的只读约束，就能让结构化日志既适合机器查询，也保持清晰的业务层级。