Go log/slog Handler怎样给结构化日志增加自定义字段怎样在批处理代码中减少额外分配

我在批处理任务里第一次把 log/slog 接到 JSON 输出时，最容易混在一起的是两个问题：公共字段应该放在哪里，以及每一轮日志怎样少做无意义的值转换。结论是，像 batch_id 这类整批不变的字段，应通过 Logger.With 或 Handler 的属性链复用；只属于当前记录的索引、状态和错误，使用 LogAttrs 直接传入。只有确实需要动态注入字段时，才在自定义 Handler 的 Handle 中克隆 Record 后修改。

官方文档：https://pkg.go.dev/log/slog

我先遇到的症状：字段有了，批处理还在抖

slog 的每条记录都由消息、级别和键值属性组成，Logger 再把 Record 交给 Handler。最初我把批次号、任务名和本轮索引全部写在每个日志调用里，字段虽然齐全，但批处理循环每次都要重新准备同一组键值。

排查时先把字段分成两类：公共字段是一个批次内不变的 batch_id、job；单条字段是本轮 record_index、状态或错误。前者绑定到 Logger，后者留在当前日志调用，Handler 只负责真正需要的动态补充。

用自定义 Handler 注入批次字段

如果字段来自 Handler 自己持有的上下文，例如批处理器创建时已经拿到批次号，可以包一层 Handler。关键点不是把字符串拼到消息里，而是把它作为结构化 Attr 加回 Record；修改 Record 前先 Clone，避免对共享状态产生意外影响。

package main

import (
	"context"
	"io"
	"log/slog"
)

// batchHandler 给每条记录增加同一批次的结构化字段。
type batchHandler struct {
	next    slog.Handler
	batchID string
}

func (h batchHandler) Enabled(ctx context.Context, level slog.Level) bool {
	// 先交给下游判断级别，避免无效记录继续处理。
	return h.next.Enabled(ctx, level)
}

func (h batchHandler) Handle(ctx context.Context, r slog.Record) error {
	if h.batchID != "" {
		// Record 可能共享内部属性状态，修改前先创建独立副本。
		r = r.Clone()
		r.AddAttrs(slog.String("batch_id", h.batchID))
	}
	return h.next.Handle(ctx, r)
}

func (h batchHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
	// 保留下游 Handler 的属性优化，不把 Attr 重新拼成文本。
	return batchHandler{next: h.next.WithAttrs(attrs), batchID: h.batchID}
}

func (h batchHandler) WithGroup(name string) slog.Handler {
	// 继续转发分组，避免自定义 Handler 破坏 JSON 的层级。
	return batchHandler{next: h.next.WithGroup(name), batchID: h.batchID}
}

func newBatchLogger(w io.Writer, batchID string) *slog.Logger {
	base := slog.NewJSONHandler(w, nil)
	return slog.New(batchHandler{next: base, batchID: batchID})
}

这个包装器适合字段确实属于 Handler 上下文的场景。WithAttrs 和 WithGroup 必须继续转发，否则调用方在 Logger 上绑定公共字段或分组后，可能出现字段丢失、层级不一致等问题。

在批处理循环中使用 LogAttrs

更常见的情况其实不需要自定义 Handler。先用 With 绑定公共字段，再用 LogAttrs 传递每条记录独有的属性。官方文档明确指出，Handler 可以把通过 With 绑定的公共属性只格式化一次，而 LogAttrs 只接受 Attr，适合高效输出结构化日志。

func writeBatch(ctx context.Context, logger *slog.Logger, items []string) {
	// 整批不变的字段只绑定一次，避免每轮重复准备。
	batchLogger := logger.With(
		slog.String("job", "import"),
		slog.String("batch_id", "b-20261108-01"),
	)

	for i, item := range items {
		// 当前索引和结果只属于这一条记录，使用 LogAttrs 保持键值结构。
		batchLogger.LogAttrs(ctx, slog.LevelInfo, "处理记录",
			slog.Int("record_index", i),
			slog.String("item", item),
		)
	}
}

如果公共字段还要按子系统区分，可以继续使用 WithGroup("batch")，让 JSONHandler 把这些字段放进 batch 对象；这比在消息文本里手工拼接 batch_id=... 更容易被下游解析。

为什么我不会直接在 Handler 里反复计算字段

日志级别被过滤时，调用参数仍然会先求值。像 URL 格式化、堆栈摘要或大对象摘要这样的昂贵计算，不应无条件写在 Debug 参数里。可以先用 Enabled 判断，也可以把延迟计算封装成实现 slog.LogValuer 的类型，让 Handler 真正需要输出时再解析。

func logDebug(ctx context.Context, logger *slog.Logger, payload []byte) {
	// 只有 Debug 级别启用时，才构造昂贵的摘要字符串。
	if !logger.Enabled(ctx, slog.LevelDebug) {
		return
	}

	summary := summarizePayload(payload)
	logger.LogAttrs(ctx, slog.LevelDebug, "payload summary",
		slog.String("summary", summary),
	)
}

func summarizePayload(payload []byte) string {
	// 示例只表达延迟计算边界，不代表固定的摘要算法。
	if len(payload) > 64 {
		return string(payload[:64]) + "..."
	}
	return string(payload)
}

另一个容易漏掉的边界是自定义 Handler 修改 Record。官方文档提醒，Record 的简单副本仍可能间接引用属性状态；因此要添加或删除属性，先 Clone，再交给下游 Handler。

最后按三个信号复查

我通常只看三个信号来确认设计没有走偏：

1. 字段信号：JSON 输出中 batch_id、job 和 record_index 仍是独立字段，而不是塞进 msg 文本。
2. 边界信号：关闭 Info 或 Debug 后，昂贵摘要不会继续计算；Handler 的 Enabled 没有被绕开。
3. 扩展信号：增加 WithGroup 或新的公共 Attr 时，包装器仍能把调用转发到下游，不破坏分组层级。

如果只是给每条日志附加固定批次信息，优先选 logger.With；如果字段来自 Handler 持有的动态上下文，再使用上面的包装器。这个分界比“所有字段都塞进 Handler”更容易维护，也更接近 slog 的结构化设计。

常见问题

With 和 WithAttrs 应该怎么选？

业务代码通常使用 Logger.With，它会返回带公共属性的新 Logger；实现自定义 Handler 时才需要正确实现并转发 WithAttrs。两者都表达“这些属性会复用于后续日志”，但所在抽象层不同。

为什么不用 fmt.Sprintf 先拼好一行日志？

拼成字符串会丢掉键值字段的结构，后续检索、过滤和 JSON 消费都要再次解析。只要下游需要按字段查询，就应保留 Attr，并用 LogAttrs 传入当前记录的数据。