Go slog Handler WithGroup 后字段名为什么变了

Go 的 log/slog 使用 Handler.WithGroup 后，字段名看起来发生变化，通常不是 slog.Attr 被改写了，而是处理器开始用“分组名 + 字段名”表示新的命名空间。内置 TextHandler 会把它写成点号路径，例如 request.method；JSONHandler 则会把同一关系写成嵌套对象，例如 {"request":{"method":"GET"}}。

因此，排查时要先确认日志处理器的输出格式，再检查 WithGroup、With 和自定义 Handler 的调用顺序。下面只围绕分组字段、嵌套输出和处理器组合展开。

先区分 WithGroup 与普通 With

With 给后续日志添加固定属性，WithGroup 给后续属性建立命名空间。它们都会返回一个新的 Logger，原来的 Logger 不会被就地修改。

package main

import (
	"log/slog"
	"os"
)

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

	requestLogger := logger.With("service", "gateway").WithGroup("request")
	requestLogger.Info("收到请求",
		// 中文注释：method 会被 request 这个分组限定，原始键仍然是 method。
		slog.String("method", "GET"),
		slog.Int("status", 200),
	)
}

上例的逻辑是：service 通过 With 添加在根级，method 和 status 是当前 request 分组里的字段。若把 WithGroup 理解成给已有字符串加前缀，就容易误以为所有字段都被永久改名；实际上它表达的是处理器在当前日志记录中如何限定后续属性。

对照 TextHandler 和 JSONHandler

内置处理器的差异是“字段名为什么变了”的最常见答案。Go 官方文档规定，文本处理器用点号分隔组名和属性名，JSON 处理器把组名作为对象键。

package main

import (
	"bytes"
	"fmt"
	"log/slog"
)

func main() {
	var textBuffer, jsonBuffer bytes.Buffer
	textLogger := slog.New(slog.NewTextHandler(&textBuffer, nil)).WithGroup("request")
	jsonLogger := slog.New(slog.NewJSONHandler(&jsonBuffer, nil)).WithGroup("request")

	// 中文注释：两种 Logger 接收相同的 Attr，差别只在 Handler 的呈现方式。
	textLogger.Info("完成", slog.String("method", "GET"), slog.Int("status", 200))
	jsonLogger.Info("完成", slog.String("method", "GET"), slog.Int("status", 200))

	fmt.Println(textBuffer.String())
	fmt.Println(jsonBuffer.String())
}

文本结果的关键部分会类似 request.method=GET request.status=200；JSON 结果的关键部分会类似 "request":{"method":"GET","status":200}。两者都没有把 Attr 的原始 Key 从 method 改成了另一个键，只是输出协议不同。

如果日志采集端只允许扁平字段，应该在索引映射或查询层适配点号路径；如果下游期待对象结构，则应保留 JSON 的嵌套形式。不要为了让一种输出“看起来一致”而在业务代码里重复拼接 request.method，否则换处理器后很容易得到双重前缀。

检查嵌套分组和调用顺序

多个 WithGroup 会按调用顺序形成嵌套分组。下面把通用字段放到 request 下，再把查询字段放到 query 下：

package main

import (
	"log/slog"
	"os"
)

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

	// 中文注释：每次 WithGroup 都只影响其后的属性，组名顺序决定 JSON 的嵌套顺序。
	logger.WithGroup("request").
		With("trace_id", "t-42").
		WithGroup("query").
		Info("查询完成", slog.String("keyword", "go"))
}

此时 trace_id 位于 request 下，keyword 位于 request.query 下。属性是在分组前还是分组后添加，结果也不同：

• logger.With("id", 7).WithGroup("request")：id 在根级，后续字段在 request 下。
• logger.WithGroup("request").With("id", 7)：id 也属于 request 分组。
• WithGroup("")：按接口约定返回接收者，不新增空分组。

自定义 Handler 还必须保留这种顺序。Logger.With 会调用 Handler 的 WithAttrs，Logger.WithGroup 会调用 Handler 的 WithGroup。如果实现只保存“最后一个组名”，或者把所有属性提前合并成一个无序 map，就会出现字段被放错层级、重复覆盖或嵌套顺序丢失。

修正自定义 Handler 的实现

实现包装 Handler 时，WithGroup 的基本契约是返回带有新状态的 Handler，而不是修改原接收者。新分组要追加到已有分组序列，后续 With 或 Record 中的属性都要按这条序列限定。

type groupHandler struct {
	base   slog.Handler
	groups []string
}

func (h *groupHandler) WithGroup(name string) slog.Handler {
	if name == "" {
		// 中文注释：空组名不增加命名空间，直接复用当前 Handler。
		return h
	}

	groups := make([]string, len(h.groups), len(h.groups)+1)
	copy(groups, h.groups)
	groups = append(groups, name)
	return &groupHandler{base: h.base, groups: groups}
}

func (h *groupHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
	// 中文注释：包装器把属性继续交给底层 Handler，同时保留当前分组状态。
	return &groupHandler{base: h.base.WithAttrs(attrs), groups: h.groups}
}

这段代码只展示状态传递的关键部分；真正的 Handle 还需要将 h.groups 应用到每个属性，并正确处理嵌套 Group、空 Group 和 LogValuer。如果包装器只是调整日志级别，可以像官方示例那样把 WithGroup 和 WithAttrs 原样转发给内部 Handler，不要在外层重新拼接键名。

整理工程中的命名策略

建议把分组当作稳定的模块边界，而不是每条日志临时拼接的字符串。HTTP 服务可以使用 request，数据库访问可以使用 db，但同一层不要同时出现 request、req 两套别名。

一句话总结：WithGroup 改变的是后续属性的命名空间，字段在文本和 JSON 中的外观由 Handler 决定；遇到“字段名变了”，先看输出格式和调用顺序，再看自定义 Handler 是否遵守分组契约。

常见追问

WithGroup 和 slog.Group 应该怎么选？

WithGroup 适合给一个 Logger 的后续输出建立持续边界；slog.Group 适合只在一条日志中把几组 Attr 收进一个字段。两者可以产生相似的结构，但作用范围不同。

为什么文本日志能查到 request.method，JSON 却要查 request.method？

因为文本输出把路径扁平化为带点号的键，JSON 输出保留对象层级。查询语法由采集系统决定，不能只根据字段显示字符串猜测底层结构。

能不能在 Handler 里直接给 Attr.Key 加前缀？

不建议。这样容易破坏嵌套 Group、空键分组和包装 Handler 的组合语义。更稳妥的做法是保留分组序列，在最终编码阶段决定文本或 JSON 的呈现。

参考资料：https://pkg.go.dev/log/slog、https://go.dev/src/log/slog/handler.go、https://go.dev/blog/slog