Go slog.ReplaceAttr 处理分组属性时 groups 参数怎么用

如果你在 log/slog 的 HandlerOptions.ReplaceAttr 里看到 groups []string，它不是“所有分组名称的配置表”，而是当前属性所在的打开分组路径。根属性通常收到空路径，分组里的叶子属性才会收到对应的组名；ReplaceAttr 本身不会为 Group 容器单独回调。

实用结论是：先用 len(groups) 判断层级，再按名称和顺序匹配路径，最后返回原属性、改写后的属性或零值属性。这样可以只处理 request.password，而不会因为字段同名把根级 password 也一起删掉。

官方地址：https://pkg.go.dev/log/slog#HandlerOptions

ReplaceAttr 处理的是叶子属性

一个日志记录可以包含普通属性和分组属性，例如 a、分组 g 里的 b、以及普通属性 c。Handler 展开这棵属性树后，才把每个非分组属性交给 ReplaceAttr。所以回调关注的是“当前叶子是什么、它位于哪些打开的组中”，不是去判断当前 Attr 是否为 Group。

package main

import (
	"log/slog"
	"os"
)

func main() {
	logger := slog.New(slog.NewTextHandler(os.Stdout, &slog.HandlerOptions{
		ReplaceAttr: func(groups []string, a slog.Attr) slog.Attr {
			// 先记录路径和键的职责：groups 描述位置，a.Key 描述当前叶子。
			if len(groups) == 0 {
				return a // 根级属性没有打开的分组。
			}
			return a // 分组容器不会单独进入这里，处理其内部叶子即可。
		},
	}))

	// Group 只负责组织字段，回调会分别看到 a、b、c。
	logger.Info("demo",
		"a", 1,
		slog.Group("g", slog.Int("b", 2)),
		"c", 3,
	)
}

官方契约给出的调用顺序可以概括为：groups=nil, a；groups=["g"], b；groups=nil, c。这里的 nil 和长度为零的非 nil 切片在判断层级时应视为同一类情况，不要用切片是否为 nil 来表达业务规则。

用 groups 区分根属性和分组属性

最常见的排查错误是只写 a.Key == "password"。如果日志里同时有根级密码和请求对象里的密码，这个判断会把两者混在一起。正确做法是把字段名和路径放在同一个条件里。

package main

import "log/slog"

func replaceRootTimeAndNestedPassword(groups []string, a slog.Attr) slog.Attr {
	// 只删除根级时间；分组里若有同名键，不受这个条件影响。
	if a.Key == slog.TimeKey && len(groups) == 0 {
		return slog.Attr{}
	}

	// 只处理 request 组里的 password，避免误伤根级或其他组的同名字段。
	if a.Key == "password" && len(groups) == 1 && groups[0] == "request" {
		return slog.String("password", "***")
	}

	return a // 没有命中目标路径时保留原属性。
}

这里有两个可复用的判断习惯：

• 处理 Handler 的内置属性时，根级时间、级别、消息等属性也可能经过回调；如果只想处理用户业务字段，先把内置键和层级条件写清楚。
• 删除属性要返回零值 slog.Attr{}；仅仅把键改成空字符串并不等价于“丢弃”。改写值时则返回新的 slog.Attr，保持输出键的含义稳定。

嵌套分组要按顺序匹配

当属性位于嵌套分组中，groups 是从外到内的路径。例如 request 下再有 auth，其中的 token 可以按 ["request", "auth"] 识别。路径是回调当次使用的输入，官方明确要求不要保留或修改它。

package main

import (
	"io"
	"log/slog"
)

func redactToken(groups []string, a slog.Attr) slog.Attr {
	// 先判断长度，再按外层到内层的顺序比较，避免越界和错层匹配。
	if a.Key == "token" && len(groups) == 2 &&
		groups[0] == "request" && groups[1] == "auth" {
		return slog.String("token", "[redacted]")
	}
	return a
}

func buildLogger() *slog.Logger {
	// 将回调交给 Handler，Logger 只负责产生日志属性树。
	return slog.New(slog.NewJSONHandler(io.Discard, &slog.HandlerOptions{
		ReplaceAttr: redactToken,
	}))
}

示例用 io.Discard 表达 Handler 配置关系，真实程序可以换成已准备好的文件或标准输出。这里更重要的是路径匹配：groups[0] 是外层组，groups[1] 是内层组，顺序颠倒就不应视为同一位置。

TextHandler 和 JSONHandler 只是展示不同

同一棵分组属性树，在 TextHandler 中通常表现为带点号的键，在 JSONHandler 中则表现为嵌套对象。这个差异不改变 ReplaceAttr 的 groups 语义：回调仍然在叶子属性层面接收当前打开的路径。

一张清单排除 groups 误用

1. 先问当前属性是不是叶子。不要为 Group 容器写回调分支，把判断集中在 a.Key 和 a.Value 上。
2. 用长度表达层级。根级用 len(groups) == 0，一层分组用长度 1，嵌套分组按完整顺序比较。
3. 不要保存或修改 groups。回调返回前读取即可；如果需要记录路径，复制出自己的字符串或结构。
4. 返回值要有明确语义。返回原 Attr 表示保留，返回新 Attr 表示改写，返回零值 Attr 表示删除。
5. 同时考虑内置属性。时间、级别、源位置和消息也可能进入回调，必要时用根级判断把它们与业务字段分开。

总之，groups 解决的是“这个叶子字段位于哪条分组路径上”，不是“日志已经经过了多少层处理”。把路径判断和键判断组合起来，ReplaceAttr 就能稳定完成分层脱敏、字段改名和选择性删除，同时保持原有 Handler 结构不变。

相关问题

ReplaceAttr 会为 slog.Group 本身调用吗？

不会。它针对非分组属性调用，分组容器只是组织路径，组内叶子属性才会进入回调。

groups 为 nil 和空切片有什么区别？

在表达“没有打开的分组”时应按长度判断，len(groups) == 0 比判断是否为 nil 更稳妥。

可以直接修改 groups 里的字符串吗？

不可以。官方要求不要保留或修改这份路径；需要异步使用时，应复制出自己的数据。