当前位置：首页 > 文章列表 > Golang > Go问答 > Go slog Handler WithGroup 后字段名为什么变了

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

来源：17golang原创 2026-11-14 01:34:54 0浏览收藏

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 理解成给已有字符串加前缀，就容易误以为所有字段都被永久改名；实际上它表达的是处理器在当前日志记录中如何限定后续属性。

slog WithGroup 将字段送入文本点号路径和 JSON 嵌套对象的结构说明图 — 图1：同一组 slog 属性在 TextHandler 与 JSONHandler 中的字段表示，这是静态说明图，不是运行截图。

对照 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，就会出现字段被放错层级、重复覆盖或嵌套顺序丢失。

slog Logger 与 Handler 按调用顺序维护分组栈和属性层级的结构图 — 图2：嵌套 WithGroup 与 WithAttrs 组合时，Handler 需要保留分组序列和属性调用顺序，这是静态结构图。

修正自定义 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 两套别名。

现象	优先检查	处理方式
TextHandler 出现 `a.b`	是否调用了 WithGroup("a")	按点号路径查询，不要再次手工加前缀
JSONHandler 出现多层对象	WithGroup 的调用顺序	把共享属性放在正确的分组之前或之后
自定义 Handler 字段串层级	WithAttrs/WithGroup 是否返回新状态	保存完整分组序列，并复制切片避免别名修改
字段名没有变化	组名是否为空、Handler 是否真的使用分组	检查空组与包装 Handler 的转发逻辑