Go slog.Record.NumAttrs 与 Attrs 遍历结果有什么区别

我第一次在自定义 slog.Handler 里给日志属性预留切片时，直觉上会把 Record.NumAttrs() 和 Record.Attrs() 当成同一件事：前者告诉我有多少个字段，后者把字段逐个交给我。这个理解对“完整遍历普通属性”的场景基本成立，但它没有说清楚三个边界：计数只看顶层属性，空的 Group 可能根本不会进入记录，而回调返回 false 后观察到的遍历数量又可能小于计数。

这两个 API 的分工可以先记成一句话：NumAttrs 是规划信息，Attrs 是处理入口。需要分配容量、写统计摘要时看前者；需要读取键值、保持记录顺序或在找到目标后停止时用后者。

一句话结论：在回调始终返回 true、没有提前退出的前提下，NumAttrs() 通常等于 Attrs 回调次数；一旦提前停止，回调次数只是“实际处理了多少”，不是“记录原本有多少”。

先把两个 API 放回同一条处理链

slog.Record 保存的是一组顶层 Attr。NumAttrs 返回这组顶层属性的数量，适合告诉 Handler 预留多大的临时空间；Attrs 则按记录中的顺序调用回调。回调返回 false 时，遍历立即结束。

这里的“顶层”很重要。一个 slog.Group("request", slog.Int("id", 7)) 在 Record 中仍然是一个 Group 属性，不会因为里面有一个 id 就让 NumAttrs 变成两个。要不要递归展开，是 Handler 自己的输出策略。

为什么完整遍历时两个结果通常相等

如果回调不提前停止，Attrs 会把 Record 中的每个顶层属性交给 Handler。此时可以把 NumAttrs 看成遍历上限，也可以用它做一次容量提示。它不承诺把 Group 内部的叶子字段摊平，也不负责替 Handler 读取属性值。

package main

import (
	"fmt"
	"log/slog"
)

func listAttrs(record slog.Record) []slog.Attr {
	attrs := make([]slog.Attr, 0, record.NumAttrs()) // 计数只用于预留顶层容量。
	record.Attrs(func(attr slog.Attr) bool {
		attrs = append(attrs, attr) // Attrs 按 Record 中的顺序交付属性。
		return true                // 返回 true，才能继续处理剩余属性。
	})
	return attrs
}

func main() {
	record := slog.NewRecord(
		0,
		slog.LevelInfo,
		"request finished",
		0,
	)
	record.AddAttrs(
		slog.String("method", "GET"),
		slog.Group("request", slog.Int("id", 7)),
	)

	attrs := listAttrs(record)
	fmt.Println(record.NumAttrs(), len(attrs)) // 完整遍历时通常都是 2。
}

这里的 len(attrs) 是实际收集到的顶层属性数，record.NumAttrs() 是记录在遍历前报告的顶层属性数。Group 作为一个属性占一个位置；如果后续 Handler 要输出扁平键名，例如 request.id，应在自己的递归逻辑里再处理 Group，而不是把 NumAttrs 当作叶子字段总数。

提前停止时，回调次数为什么会变少

自定义 Handler 常常不需要消费全部属性。例如只想找一个租户编号，或者只扫描到某个安全边界就结束。此时 NumAttrs 仍然反映整个 Record 的顶层属性数量，但 Attrs 的回调次数取决于你什么时候返回 false。

func findTenant(record slog.Record) (string, bool) {
	var tenant string
	found := false
	record.Attrs(func(attr slog.Attr) bool {
		if attr.Key == "tenant" {
			tenant = attr.Value.String() // 找到目标后保存值。
			found = true
			return false // 停止遍历，不再扫描后面的属性。
		}
		return true // 目标尚未出现，继续按原顺序遍历。
	})
	return tenant, found
}

如果这个 Record 有五个顶层属性，而 tenant 排在第二个位置，那么 NumAttrs() 仍然是五，但回调只会执行两次。把“回调执行次数”记成“记录属性总数”会让指标、审计摘要或预分配逻辑产生误导。

空 Group 是计数差异的另一个来源

slog 会把没有有效内容的 Group 视为无意义结构，在加入 Record 时忽略它。常见来源包括条件拼接：开发者先构造一个 Group，后来发现里面的字段都被过滤掉，却仍然把它传给 AddAttrs。这时你看到的不是“一个计数为零的 Group”，而是这项没有进入 Record。

func addOptionalAttrs(record *slog.Record, includeDebug bool) {
	debug := slog.Group("debug") // 没有子属性时，不应把它当作一个字段。
	if includeDebug {
		debug = slog.Group("debug", slog.Bool("enabled", true))
	}
	record.AddAttrs(debug)

	// 需要确认结果时，观察 NumAttrs 或完整 Attrs 遍历，而不是猜 Group 是否占位。
}

非空 Group 则仍是一个顶层 Attr。也就是说，slog.Group("debug", slog.Bool("enabled", true)) 会让顶层计数增加一个；它里面的 enabled 是否在最终文本中展开，取决于 Handler 的处理方式。空 Group 被忽略和 Group 是否递归展开，是两个不同层次的问题。

自定义 Handler 应怎样使用这两个 API

我更愿意把 NumAttrs 放在“规划”层，把 Attrs 放在“执行”层：先按顶层数量给临时切片设置容量，再在回调里做键过滤、值转换或编码。这样即使后面增加提前停止条件，也不会把计数 API 误当成遍历结果。

func appendText(record slog.Record, dst []string) []string {
	if cap(dst)-len(dst) 

上面的重点不是某一种文本格式，而是职责边界：容量规划不应该决定输出内容，输出内容也不应该反推 Record 的原始属性总数。生产代码还需要按实际格式处理 Group、LogValuer 和敏感值；本文只聚焦 NumAttrs 与 Attrs 的计数和遍历关系。

迁移时记住四个检查点

• 要预估顶层属性数量，用 NumAttrs；不要把它当成递归展开后的叶子字段数。
• 要按顺序处理属性，用 Attrs；回调返回 false 就代表主动结束。
• 要比较“总数”和“实际消费数”，分别记录 NumAttrs() 与回调中的处理计数。
• 遇到条件 Group 时，确认空 Group 是否已被忽略，再判断非空 Group 的输出策略。

如果你的 Handler 总是完整遍历普通属性，那么两个数字相等是正常现象；如果 Handler 会短路、过滤或递归展开，两个数字的语义就必须分开写进代码注释和指标名称里。这样以后看到“属性少了”的日志时，才能判断是 Record 没有这些属性，还是处理逻辑主动没有继续遍历。

最后的最小检查

可以用一个包含普通 Attr、非空 Group 和空 Group 的 Record 做人工检查：先打印 NumAttrs，再让 Attrs 完整遍历并统计回调次数，最后让回调在第二项返回 false。你应该能看到完整遍历时计数一致，而提前停止时回调次数减少；这比只看一条格式化日志更容易定位 Handler 的边界。