Go slog Handler 怎样给每条日志添加请求关联字段

在 HTTP 服务里，日志通常需要带上 request_id 或 trace_id，这样才能把同一次请求的入口、下游调用和错误串起来。直接在每个 logger.Info 调用处手动补字段很快会变得重复，而且漏写一次就会让排查链路断掉。

更稳定的做法是包装 slog.Handler：让包装层在 Handle 中从 context.Context 读取白名单字段，再交给底层 TextHandler 或 JSONHandler 输出。官方接口约定了 Enabled、Handle、WithAttrs 和 WithGroup 的职责，包装时四个方法都要考虑。

官方资料：https://pkg.go.dev/log/slog

请求字段属于请求范围数据，适合在 Handler 的 Handle 阶段补齐；固定服务名等进程级字段继续用 Logger.With，二者不要混成一套。

先看现象：同一请求的日志为什么对不上

假设中间件已经生成了请求编号，但业务代码只这样写：

// 业务日志只写消息，暂时看不到请求编号。
logger.InfoContext(r.Context(), "开始读取订单")

这条日志可以正常输出，却没有 request_id。把 logger := logger.With("request_id", id) 放进每个处理函数能解决局部问题，但会带来两个隐患：入口漏掉后整条链路没有编号，跨层传递 Logger 时还容易把请求字段误当成全局字段。

这里要区分两类数据：

• 服务名、版本、节点名是进程级或实例级数据，适合用 Logger.With 预先绑定。
• request_id、trace_id、租户标识是请求级数据，应该从当前请求的 context.Context 读取。

定义上下文字段：只保存可安全记录的值

不要把整个请求对象、Header 映射或认证 token 放进上下文再让 Handler 随意遍历。先定义私有 key 和明确类型，只允许日志层读取经过筛选的字符串。

package requestlog

import "context"

// 私有 key 避免和业务包的字符串 key 冲突。
type contextKey uint8

const (
	requestIDKey contextKey = iota
	traceIDKey
)

// WithIDs 只把可用于关联日志的公开标识放进请求上下文。
func WithIDs(ctx context.Context, requestID, traceID string) context.Context {
	ctx = context.WithValue(ctx, requestIDKey, requestID)
	return context.WithValue(ctx, traceIDKey, traceID)
}

// valueString 只返回字符串，避免把任意对象格式化到日志里。
func valueString(ctx context.Context, key contextKey) (string, bool) {
	value, ok := ctx.Value(key).(string)
	return value, ok && value != ""
}

上下文只负责携带请求范围的元数据，不负责保存大对象，也不应该成为修改业务状态的通道。request_id 是否来自可信入口、长度是否受限，可以在生成或接收请求时处理；Handler 只做最后一层白名单读取。

包装 Handler：在 Handle 中合并请求字段

包装器的核心是把当前记录复制一份，再追加从上下文取得的字段。不能修改传入的原始记录，也不要只实现 Handle 而忽略底层 Handler 的其他方法。

package requestlog

import (
	"context"
	"log/slog"
)

// ContextHandler 给已有 Handler 增加请求级字段，不改变底层输出格式。
type ContextHandler struct {
	next slog.Handler
}

// Enabled 继续委托给底层 Handler，保留级别过滤和采样策略。
func (h ContextHandler) Enabled(ctx context.Context, level slog.Level) bool {
	return h.next.Enabled(ctx, level)
}

// Handle 只从上下文读取白名单字段，然后把它们追加到当前记录。
func (h ContextHandler) Handle(ctx context.Context, record slog.Record) error {
	if requestID, ok := valueString(ctx, requestIDKey); ok {
		record.AddAttrs(slog.String("request_id", requestID))
	}
	if traceID, ok := valueString(ctx, traceIDKey); ok {
		record.AddAttrs(slog.String("trace_id", traceID))
	}
	return h.next.Handle(ctx, record)
}

// WithAttrs 返回新的包装器，不能让 logger.With 影响原来的 Handler。
func (h ContextHandler) WithAttrs(attrs []slog.Attr) slog.Handler {
	return ContextHandler{next: h.next.WithAttrs(attrs)}
}

// WithGroup 继续转发分组语义，避免结构化字段层级丢失。
func (h ContextHandler) WithGroup(name string) slog.Handler {
	return ContextHandler{next: h.next.WithGroup(name)}
}

这里的关键不是“拦截日志”，而是保持 Handler 的契约。Enabled 必须先由底层判断；否则低级别日志可能绕过原来的过滤。WithAttrs 与 WithGroup 都返回新的包装器，才能保留 Logger.With 和 Logger.WithGroup 的不可变使用习惯。

接入 HTTP 请求：让每条日志自动获得编号

应用启动时只包装一次底层 Handler。每个请求进入时生成或读取编号，随后把它写入请求上下文；业务函数只需要使用带 Context 的日志方法。

// NewContextHandler 用构造函数隐藏内部字段，避免跨包初始化错误。
func NewContextHandler(next slog.Handler) slog.Handler {
	return ContextHandler{next: next}
}

func main() {
	// JSONHandler 负责格式化，ContextHandler 只负责补请求字段。
	base := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: slog.LevelInfo})
	logger := slog.New(NewContextHandler(base)).With("service", "orders")

	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		requestID := r.Header.Get("X-Request-ID")
		if requestID == "" {
			requestID = "generated-id"
		}
		ctx := WithIDs(r.Context(), requestID, "trace-from-gateway")
		logger.InfoContext(ctx, "开始读取订单")
		w.WriteHeader(http.StatusNoContent)
	})

	// 示例省略服务关闭处理，真实服务应保留返回错误。
	_ = http.ListenAndServe(":8080", handler)
}

上面的示例强调接入关系：Handler 只创建一次，请求字段随 r.Context() 进入日志。生产代码应替换示例中的编号生成逻辑，并对外部传入的 X-Request-ID 做长度和字符集限制；不要把原始认证 Header 直接放入上下文或日志。

出现重复字段时，先判断字段来源

如果日志同时出现两个 request_id，通常是 Logger.With 和 Handler.Handle 都补了同名字段。它未必会导致程序失败，但会让检索结果不稳定，读者也很难判断哪个值可信。

如果业务确实需要覆盖一个关联字段，应先制定优先级，而不是依赖不同 Handler 对重复 key 的偶然处理。最简单的规则是：请求关联字段由入口统一生成，业务只能新增领域字段。

并发与空值边界：这几个细节不要省略

slog.Handler 的方法可能并发调用。包装器本身保持不可变，只读取上下文并操作当前 Record 副本，就不需要为每条日志增加共享锁。不要在 Handler 里复用可变的全局 []slog.Attr，也不要把当前请求字段写回 Handler 实例。

空值也应该有明确策略：缺少 request_id 时可以不输出该字段，或者在入口先生成；不要用一个固定的 unknown 掩盖所有缺失来源，否则检索时会把真实缺失和同一个请求混在一起。敏感信息则应在字段进入上下文之前拦截，Handler 只允许读取已经定义好的 key。

只有通过 InfoContext、WarnContext、LogAttrs(ctx, ...) 等带上下文的方法调用，Handler 才能拿到当前请求的上下文。脱离请求的后台任务如果调用普通 logger.Info，本来就没有请求关联字段，这是正常边界。

落地清单：把请求关联字段做成基础设施

1. 在入口生成或校验 request_id，限定长度、字符集和信任来源。
2. 只把白名单字符串写入 context，不把 Header、token 或业务对象整体塞进去。
3. 用包装 Handler 在 Handle 阶段追加 request_id、trace_id，并委托 Enabled、WithAttrs、WithGroup。
4. 服务名和版本等固定字段使用 Logger.With，避免和请求字段重复。
5. 业务日志统一使用带 Context 的方法；后台任务明确不拥有请求编号。
6. 通过日志检索检查同一请求的多个事件是否能用同一个编号串起来。

这样做的结果是：业务代码保持简洁，结构化日志仍由标准 Handler 输出，请求级字段集中在一个可替换的边界里；以后接入 trace、租户或灰度批次时，也只需扩展白名单读取和入口注入逻辑。

相关问题

为什么不直接给每个 Logger 调用加 request_id？

少量代码可以这样做，但大型服务容易漏写，并且请求字段会散落在业务层。Handler 包装更适合统一基础设施；业务仍可以显式追加订单号等领域字段。

WithAttrs 和 Handle 都能加字段，应该选哪个？

固定字段用 WithAttrs，请求上下文中的动态字段用 Handle。这样既能复用底层 Handler 对固定属性的处理，也不会把一个请求的值泄漏到另一个请求。

Handler 能不能在请求取消后停止写日志？

不要把取消上下文直接当成丢弃日志的信号。错误日志往往正是排查取消原因所需要的证据；是否过滤应由日志级别和业务策略决定。