Go log/slog用Group组织结构化日志字段的实现方式

在 Go 的结构化日志里，字段一多就容易出现 id、status 互相覆盖或含义不清。log/slog 的做法是把同一对象的键值放进命名组：单条记录用 slog.Group，模块级日志用 Logger.WithGroup。这样 TextHandler 会输出带点号的限定键，JSONHandler 会输出嵌套对象。

实现这类日志的关键不是给字段改成长名字，而是先划分稳定的对象边界，再选择记录级分组或 Logger 级分组。

先确定日志组的边界

以一次订单请求为例，HTTP 方法和路径属于 request，订单编号和状态属于 order。组名应该表达业务对象或模块，而不是表达某一行代码。组内的键可以保持简短，但不要把不同对象的同名键混在同一层。

本文示例使用标准库 log/slog 的 JSONHandler；如果接入文本日志，只需替换 Handler，字段分组的调用方式不变。

用 slog.Group 构造单条记录的字段组

slog.Group 返回一个带名称的属性组，可以直接交给 InfoContext、LogAttrs 等输出方法。下面把一条订单日志拆成两个命名空间：

package main

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

func main() {
    // JSONHandler 把 Group 输出为嵌套对象，便于日志系统按对象字段检索。
    logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))

    // 每次记录明确声明 request 与 order 的边界，避免两个对象都使用 id 时混淆。
    logger.InfoContext(context.Background(), "order accepted",
        slog.Group("request",
            slog.String("method", "POST"),
            slog.String("path", "/orders"),
        ),
        slog.Group("order",
            slog.String("id", "o-2048"),
            slog.String("state", "accepted"),
        ),
    )
}

这里每个组都是当前记录的一部分，不会影响下一条日志。JSON 输出的结构重点是 request.method 和 order.id 不再处于同一平面；换成 TextHandler 后，它们会表现为 request.method=POST 和 order.id=o-2048。

用 WithGroup 约束模块级日志键

如果一个解析模块连续写很多条日志，重复传入 slog.Group("parser", ...) 会让调用点变长。这时可以创建派生 Logger：

func parse(logger *slog.Logger, input string) error {
    // WithGroup 返回使用同一 Handler 的新 Logger，后续字段自动带 parser 前缀。
    parserLogger := logger.WithGroup("parser")

    // 记录模块内的通用键；不必在每次调用时重复写 parser 组。
    parserLogger.Info("input received", "size", len(input))
    return nil
}

WithGroup 不会修改原来的 Logger，因此同一个根 Logger 可以派生出 parser、storage 等不同模块 logger。它适合稳定的模块边界；一次性、只属于单条事件的对象仍然更适合 slog.Group。

根据 Handler 选择输出和复查边界

同一组在不同 Handler 下的外观不同，但语义仍由组名决定。TextHandler 用点号限定键，JSONHandler 用对象层级表达组。接入日志采集器时，要确认下游查询语法是否支持嵌套字段；不要因为文本展示方便，就把所有字段重新拼成带点号的字符串。

最后再检查两件事：敏感字段不要因为放进 Group 就失去脱敏；组名和键名要作为日志契约管理，避免同一模块今天叫 order、明天叫 orders。

相关问题

slog.Group 和 WithGroup 怎么选？

字段只服务一条记录时用 slog.Group；一组日志都属于同一模块时用 WithGroup，这样更容易维护一致的命名空间。

TextHandler 会把组变成 JSON 吗？

不会。TextHandler 通常把组和字段拼成点号路径，JSONHandler 才会把组呈现为嵌套对象；两者共享同一组语义。

小结

先按业务对象划分组，再用 slog.Group 表达单条记录，用 WithGroup 表达模块边界。最后根据下游日志系统选择 TextHandler 或 JSONHandler，并把组名、键名和脱敏规则当作长期接口维护。