Go 请求 ID 中间件实战：从 HTTP 入口传到 context 和结构化日志

线上接口出了500，业务日志却只有一句“处理失败”，没有请求编号，开发者只能靠时间和用户描述去猜是哪一次调用。给 Go 的 net/http 服务加一层请求 ID 中间件，就能把同一个编号带过 handler、context.Context、响应头和结构化日志；客户端传来不可信或过长的值时，再自动换成服务端生成的 ID。

先把请求 ID 的边界说清楚

请求 ID 不是用户身份，也不是权限凭证。它只负责把一次 HTTP 调用串起来，适合放在访问日志、错误日志和响应头中。不要把手机号、邮箱、订单内容等业务数据拼进 ID，也不要因为客户端带了一个值就无条件信任它。

这次实验约定：请求头名为 X-Request-ID，只保留 1 到 64 个 ASCII 字母、数字、短横线和下划线。规则不满足时直接生成新的随机 ID。这样既能兼容网关已有的追踪编号，也不会把换行符或超长字符串带进日志。

在 net/http 入口生成并传递 ID

先写一个只做一件事的中间件。ID 放入 context 时使用未导出的 key 类型，避免和其他包的字符串 key 冲突；handler 只通过一个小函数读取，不直接接触存储细节。

package requestid

import (
    "context"
    "crypto/rand"
    "encoding/hex"
    "net/http"
    "regexp"
)

type contextKey struct{}

var validID = regexp.MustCompile(`^[A-Za-z0-9_-]{1,64}$`)

func FromContext(ctx context.Context) string {
    value, _ := ctx.Value(contextKey{}).(string)
    return value
}

func Middleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        id := r.Header.Get("X-Request-ID")
        if !validID.MatchString(id) {
            id = newID()
        }

        ctx := context.WithValue(r.Context(), contextKey{}, id)
        w.Header().Set("X-Request-ID", id)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func newID() string {
    buf := make([]byte, 16)
    if _, err := rand.Read(buf); err != nil {
        return "request-id-unavailable"
    }
    return hex.EncodeToString(buf)
}

这里故意把响应头写在调用下游之前。handler 一旦开始写响应体，HTTP 头部就可能已经发出，再补写 X-Request-ID 会失效。随机源异常时的固定兜底值只用于保住日志链路，生产项目还应该把随机源错误作为启动或监控告警处理。

让业务日志和响应头使用同一个值

有了中间件，业务 handler 不需要再次解析请求头。把 ID 从 context 取出后作为结构化字段写入 log/slog，错误日志和成功日志就拥有相同的检索条件。

func orderHandler(logger *slog.Logger) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        requestID := requestid.FromContext(r.Context())
        logger.InfoContext(r.Context(), "order lookup",
            "request_id", requestID,
            "path", r.URL.Path,
        )
        w.WriteHeader(http.StatusNoContent)
    })
}

日志字段建议固定叫 request_id，不要一会儿写 requestId、一会儿写 trace。如果服务还接入了 OpenTelemetry，可以把请求 ID 作为检索字段保留，同时使用真正的 trace/span ID 处理跨服务拓扑，两者用途不同。

用 httptest 验收三处是否一致

只看浏览器响应头不够，最容易漏掉的是 context 没有传进去，或者测试请求携带非法 ID 时仍然原样回显。下面的测试覆盖“复用合法 ID”和“替换非法 ID”两条路径。

func TestMiddlewareKeepsOneID(t *testing.T) {
    next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if got := requestid.FromContext(r.Context()); got != "client-42" {
            t.Fatalf("context request id = %q", got)
        }
        w.WriteHeader(http.StatusNoContent)
    })

    req := httptest.NewRequest(http.MethodGet, "/orders/7", nil)
    req.Header.Set("X-Request-ID", "client-42")
    rec := httptest.NewRecorder()

    requestid.Middleware(next).ServeHTTP(rec, req)

    if got := rec.Header().Get("X-Request-ID"); got != "client-42" {
        t.Fatalf("response request id = %q", got)
    }
}

func TestMiddlewareReplacesBadID(t *testing.T) {
    next := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if requestid.FromContext(r.Context()) == "bad value" {
            t.Fatal("unsafe request id reached context")
        }
    })
    req := httptest.NewRequest(http.MethodGet, "/health", nil)
    req.Header.Set("X-Request-ID", "bad value")
    rec := httptest.NewRecorder()

    requestid.Middleware(next).ServeHTTP(rec, req)

    if got := rec.Header().Get("X-Request-ID"); got == "" || got == "bad value" {
        t.Fatalf("response request id = %q", got)
    }
}

运行 go test ./... 后，重点看两件事：下游读取到的 ID 与响应头完全一致；非法输入不会原样进入 context。若测试偶尔出现空响应头，先检查 handler 是否在中间件之前直接写了响应，或是否存在另一层中间件覆盖了同名 header。

几个容易被忽略的生产边界

不要把客户端 ID 当成安全凭证

客户端可以伪造请求 ID，所以它只能用于关联日志，不能参与授权、签名或敏感资源定位。涉及权限时仍然要依赖登录态、服务间认证和资源归属检查。

跨服务调用要明确谁负责透传

如果 Go 服务再调用下游 HTTP 服务，可以从当前 context 取出 ID 写入下游请求头；但要约定覆盖规则，避免每个服务都重新生成，导致一条调用链出现多个编号。

异常兜底要能被发现

request-id-unavailable 这样的兜底值不应长期静默存在。可以增加计数指标或告警，并在启动检查中确认系统随机源可用。日志字段里出现大量相同兜底值时，说明关联能力已经失真。

相关问题

请求 ID 应该放在 context 还是结构体里？

放在 request context 更适合贯穿一次请求的调用链，避免把横切字段塞进业务参数结构体。业务函数仍应通过明确的参数传递核心数据。

为什么不直接使用字符串作为 context key？

不同包可能使用同一个字符串，造成覆盖或误读。未导出的自定义类型能把 key 的命名空间留在当前包内。

请求 ID 和 trace ID 是一回事吗？

不是。请求 ID 偏向单次入口请求的人工检索，trace ID 用来描述跨服务调用拓扑。两者可以同时保留，并在日志中使用不同字段名。

总结

这层中间件的核心不是生成一个随机字符串，而是把“入口校验、context 传递、响应回写、日志字段、测试验收”连成同一条可检查的链路。先用 httptest 固定合法和非法输入的行为，再接入真实路由与日志采集，后续排查 500、慢请求或重试问题时，才不会只剩一串时间戳。