用 slog 建立请求级字段并统一 JSON 日志输出

如果日志里只有“处理失败”和一串散落的字符串，排查一次请求往往要靠时间和猜测。用 Go 的 log/slog 可以把日志变成统一的 JSON 记录：入口建立 request_id、HTTP 方法和路径，业务层沿用派生出来的 Logger，最终每条记录都能被日志系统按字段检索。

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

这套方案的关键不是把所有参数塞进 context.Context，而是让“请求级字段”绑定在 Logger 上，让 context 只承担取消、超时和跨层信号。

先把日志出口固定成 JSON

slog 的 Handler 决定输出格式。服务启动时明确创建 JSONHandler，并用 HandlerOptions 设置最低级别；调用 slog.SetDefault 后，包级的 slog.Info、slog.Error 也会走这个出口。

package main

import (
	"log/slog"
	"os"
)

func newLogger() *slog.Logger {
	// 让日志平台按行接收 JSON，Info 以下的调试记录默认不输出。
	opts := &slog.HandlerOptions{Level: slog.LevelInfo}
	logger := slog.New(slog.NewJSONHandler(os.Stdout, opts))
	// 设置默认 logger，兼容仍使用 slog.Info 的旧调用点。
	slog.SetDefault(logger)
	return logger
}

func main() {
	logger := newLogger()
	// 使用结构化属性，避免把字段拼进不可检索的 message。
	logger.Info("service started", slog.String("service", "orders"))
}

输出会是逐行 JSON，例如 {"level":"INFO","msg":"service started","service":"orders"}。生产环境通常把输出交给标准输出采集器；不要在业务代码里再次把 JSON 编码成字符串，否则会得到嵌套转义。

把请求字段绑定到派生 Logger

公共字段应该在请求入口一次绑定，而不是由每个业务函数手工重复传入。Logger.With 会返回使用同一 Handler 的新 Logger，之后每条记录都会带上这些属性。

func requestLogger(base *slog.Logger, r *http.Request) *slog.Logger {
	// 真实服务可优先读取网关传入的 request_id，再为缺失请求生成新的值。
	requestID := r.Header.Get("X-Request-ID")
	if requestID == "" {
		requestID = newRequestID()
	}
	// 请求公共字段绑定在 Logger 上，不把业务参数混进 context。
	return base.With(
		slog.String("request_id", requestID),
		slog.String("method", r.Method),
		slog.String("path", r.URL.Path),
	)
}

这里的 newRequestID 只代表项目已有的 ID 生成器，示例不假定某个第三方库。字段名一旦进入日志查询和告警规则，就应当保持稳定；例如不要一会儿叫 request_id，一会儿叫 traceId。

让业务函数接收带上下文的日志器

入口拿到派生 Logger 后，直接把它作为显式依赖传入业务函数。请求的取消信号仍然通过 context.Context 传递，日志公共字段则由 Logger 负责。

func handleOrder(ctx context.Context, logger *slog.Logger, orderID string) error {
	// Context 用于取消和超时；Logger 用于请求级字段与事件属性。
	logger.InfoContext(ctx, "load order", slog.String("order_id", orderID))
	order, err := loadOrder(ctx, orderID)
	if err != nil {
		// 错误对象作为结构化字段保留，消息只描述当前事件。
		logger.ErrorContext(ctx, "load order failed", slog.Any("error", err))
		return err
	}
	logger.InfoContext(ctx, "order loaded", slog.String("state", order.State))
	return nil
}

在 Handler 中可以这样组织边界：logger := requestLogger(slog.Default(), r)，然后调用 handleOrder(r.Context(), logger, orderID)。如果需要写入完成状态，再由入口记录 status、duration_ms 等 HTTP 层字段，避免业务层猜测响应状态。

统一分组、级别和敏感字段

字段越来越多时，可以用 WithGroup 给子系统建立命名空间。例如 logger.WithGroup("db") 后，数据库层的 duration_ms 不会和 HTTP 层同名混淆。对接口错误使用 Error，对正常状态使用 Info，需要临时打开的细节使用 Debug，并通过 LevelVar 动态调节级别。

密码、Cookie、访问令牌和完整 Authorization 头不应直接记录。自定义类型可以实现 slog.LogValuer，只返回脱敏后的值；Handler 的 ReplaceAttr 也适合统一删除时间、源文件或敏感键。脱敏要在日志出口完成一次，避免每个调用点各写一套规则。

性能与落地检查清单

slog 的调用参数会先求值，即使该级别最终被丢弃。因此不要在 Debug 日志参数中提前执行昂贵的序列化或数据库统计。可直接传递结构化值，或让类型实现 LogValuer，在记录真正启用时再计算。对热点路径优先使用 LogAttrs，减少交替键值参数带来的分配。

相关问题

slog 的请求字段应该放进 context 吗？通常不必。请求 ID 等日志字段放到派生 Logger 更直观；只有需要被多个独立组件读取的请求元数据，才考虑通过 context 传递。

为什么 JSON 日志里出现重复字段？常见原因是入口已经 With 绑定了字段，业务层又用相同键重复写入。应约定公共字段只在入口绑定，业务层只追加本业务事件字段。

什么时候用 InfoContext 而不是 Info？调用点已有请求 context 时优先使用 InfoContext，这样自定义 Handler 能读取 trace 等上下文信息；没有 context 的进程级启动日志再使用 Info。