slog.Group 将结构化日志按业务域分组的方法

当一条日志同时包含请求、用户和订单字段时，最容易出现的问题不是“字段不够”，而是所有键都挤在同一层：id、status、source 很快就会失去上下文。slog.Group 的作用就是把一组属性放进一个命名空间，让 JSON 日志保持稳定的业务层级。

实用的做法是：把同一业务域的字段放入一个 Group，把跨多条日志都相同的字段放到 Logger.With，再用 JSONHandler 输出。这样既能避免同名键互相覆盖，也方便日志平台按 request、user 或 order 过滤。

如果字段属于同一个业务对象，就用 slog.Group("域名", ...) 把它们收拢；如果只是一个全局公共字段，就继续作为普通属性或通过 Logger.With 注入。Group 不是标签，它改变的是日志属性的层级结构。

为什么要给结构化日志划分业务域

slog 的日志记录由消息、级别和键值属性组成。普通写法把所有属性放在同一层，短小示例看不出问题，但在 HTTP 请求、鉴权、订单处理同时出现时，多个 id 和 status 就很难判断归属。

package main

import (
	"os"
	"log/slog"
)

func main() {
	// JSONHandler 让 Group 的层级直接反映到 JSON 对象中。
	logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
	logger.Info("order created",
		// 这些字段属于请求域，避免和业务对象的 id 混淆。
		slog.Group("request", "id", "req-42", "source", "api"),
		// 这些字段属于订单域，后续可以独立检索。
		slog.Group("order", "id", "ord-7", "status", "paid"),
	)
}

这里的重点不是字段数量，而是每个字段的归属。输出会形成 request 和 order 两个嵌套对象；两个对象都可以拥有名为 id 的键，却不会在同一层发生语义冲突。

slog.Group 和普通键值参数有什么区别

slog.Group 返回一个 slog.Attr，其值是一个 GroupValue。把它传给日志方法后，Handler 会把其中的属性作为命名空间的一部分处理。相比之下，下面的 request_id 是平铺字段，查询时不具备 request 这个父级路径。

func logRequest(logger *slog.Logger) {
	// 平铺字段适合真正跨域的公共标识；请求域字段用 Group 收拢。
	logger.Info("request finished",
		"trace_id", "trace-9",
		slog.Group("request",
			// Group 内部的键只在 request 命名空间内解释。
			"method", "GET",
			"path", "/orders",
			"status", 200,
		),
	)
}

使用 JSONHandler 时，概念上的结果类似下面这样。这里的输出是结构示意，不是某次线上运行日志：

trace_id=trace-9
request={method:GET path:/orders status:200}

如果后续把日志转成 JSON，request 会成为对象键，检索规则就可以统一写成 request.status。文本 Handler 也会保留分组语义，只是具体展示格式由 Handler 决定。

用嵌套 Group 表达子业务域

一个业务域内部还可能有更小的边界，例如请求域中的客户端信息。可以继续嵌套 Group，但建议每一层都回答一个明确的问题：这一层代表哪个对象或上下文。为了读取方便，通常两到三层已经足够。

func logWithNestedGroups(logger *slog.Logger) {
	// 嵌套层级对应 request -> client -> network 这样的业务关系。
	logger.Info("request accepted",
		slog.Group("request",
			"id", "req-42",
			slog.Group("client",
				// 同名字段放在各自的子域中，查询路径不会混乱。
				"id", "client-8",
				"network", slog.Group("ip", "value", "192.0.2.8"),
			),
		),
	)
}

嵌套不是越深越好。超过业务对象本身的层级后，日志查询需要记住过多路径，阅读成本反而会上升。如果一个字段只是为了表达来源，直接使用 source 或 component 这样的普通属性通常更清楚。

同名键、空组和混合参数要怎么处理

同名键优先靠命名空间隔离

业务域不同但字段名相同是 Group 最有价值的场景。request.id 和 order.id 表达两个不同对象，不需要人为改成 request_id、order_id。如果同一个 Group 内部重复使用同一个键，则应避免这种写法，改成更明确的字段名，而不是期待日志平台替你猜测语义。

空组不应被当成有效数据

分组中的属性经过过滤后可能全部为空。此时不要把空 Group 当作“对象存在”的证明；日志处理方可能会忽略空组，或者在不同 Handler 中采用不同的展示方式。更稳妥的做法是先判断是否有可记录字段，再决定是否构造该 Group。

func logOptionalUser(logger *slog.Logger, userID string, role string) {
	// 只有真正存在的字段才进入 user 域，避免制造空对象。
	var userAttrs []any
	if userID != "" {
		userAttrs = append(userAttrs, "id", userID)
	}
	if role != "" {
		userAttrs = append(userAttrs, "role", role)
	}
	if len(userAttrs) == 0 {
		// 没有用户属性时仍可记录主消息，但不添加空 Group。
		logger.Info("request without user")
		return
	}
	logger.Info("request with user", slog.Group("user", userAttrs...))
}

混合使用普通属性和 Group

普通属性和 Group 可以出现在同一条日志中。建议把真正横切的字段放在外层，把对象内部字段放到对应 Group，避免把所有字段都包进一个名为 context 的大容器。

把分组规则固定在日志边界

在业务代码各处临时拼接 Group，最终仍可能出现同一个域一会儿叫 user、一会儿叫 account 的问题。更可维护的做法是在日志边界定义小函数，统一域名、字段名和可选字段策略。

func orderAttrs(orderID string, amount int64) slog.Attr {
	// 订单字段集中在一个函数中，调用方不再重复约定键名。
	return slog.Group("order",
		"id", orderID,
		"amount_cents", amount,
	)
}

func logOrder(logger *slog.Logger, orderID string, amount int64) {
	// 公共 trace_id 保持平铺，订单字段保持业务域层级。
	logger.Info("order saved", "trace_id", "trace-9", orderAttrs(orderID, amount))
}

这种封装不改变 Handler 的行为，却把结构约定从调用点收回到一个可复用的边界。以后字段改名、增加脱敏或加入状态字段时，只需要调整这个边界函数。

用最小程序检查最终结构

发布日志 schema 前，可以用一条内存缓冲区接收 JSONHandler 的输出，确认分组路径和字段类型。这个小实验只用于检查本地输出形状，不代表线上日志平台的解析结果。

package main

import (
	"bytes"
	"log/slog"
)

func main() {
	var buf bytes.Buffer
	// 使用缓冲区观察最终 JSON 文本，避免依赖终端或外部日志系统。
	logger := slog.New(slog.NewJSONHandler(&buf, nil))
	logger.Info("saved",
		slog.Group("request", "id", "req-42"),
		slog.Group("order", "id", "ord-7", "status", "paid"),
	)
	// 这里可以把 buf.String() 交给测试断言，检查 request/order 是否为对象。
	_ = buf.String()
}

检查时重点看三件事：业务域是否稳定、同名键是否落在正确的父级下、可选字段为空时是否仍生成了无意义的空对象。确认这三点后，再把同样的结构约定推广到其他日志入口。

总结：Group 的边界比数量更重要

常见问题

slog.Group 会自动把普通字段改成 JSON 对象吗？

会把 Group 内的属性交给 Handler 作为一个分组值处理，但最终文本或 JSON 的具体格式由 Handler 决定。使用 JSONHandler 时，通常表现为嵌套对象。

同一个日志里可以有多个 Group 吗？

可以。只要每个 Group 的名字代表不同业务域，就能在同一条日志中并列出现；不要让多个 Group 共享含义模糊的容器名。

Group 适合替代所有前缀字段吗？

不适合。只有字段确实属于一个对象或上下文时才分组。全局追踪标识、日志来源等横切字段保持平铺更方便检索。

为什么要限制嵌套层数？

嵌套层数越多，日志查询路径越长，跨团队约定也越难维护。让每一层都对应真实业务对象，通常比追求细粒度更重要。