4、请求上下文（context.Context）在中间件中的角色

在 Go 中间件链路中，context.Context 是贯穿整个请求生命周期的核心载体。它不仅携带请求级别的元数据，还负责超时控制与取消信号的传播。理解 Context 在中间件中的角色，是构建可观测、可控制、可取消的分布式链路的基础。

4.1 Context 的三大核心职责

4.2 元数据传递：WithValue 的链式传递

中间件通过 context.WithValue 将元数据注入 Context，后续中间件或业务处理函数通过 ctx.Value 安全读取。注意：Key 必须使用自定义类型，避免与标准库或其他包冲突。

// 定义包级私有 key 类型，防止 key 冲突
type contextKey string

const (
    TraceIDKey contextKey = "trace_id"
    UserIDKey  contextKey = "user_id"
)

// 中间件：注入 TraceID
func TraceMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        traceID := r.Header.Get("X-Trace-ID")
        if traceID == "" {
            traceID = uuid.New().String()
        }
        ctx := context.WithValue(r.Context(), TraceIDKey, traceID)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// 业务函数：读取 TraceID
func BusinessHandler(w http.ResponseWriter, r *http.Request) {
    traceID, ok := r.Context().Value(TraceIDKey).(string)
    if !ok {
        traceID = "unknown"
    }
    log.Printf("[%s] 处理请求", traceID)
}

4.3 超时控制：保护下游资源

中间件可以为整个请求链路设置超时时间。当超时发生时，Context 的 Done() 通道会关闭，所有监听该通道的 goroutine 应立即停止工作并释放资源。

// 超时中间件：设置 3 秒超时
func TimeoutMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
        defer cancel() // 确保资源释放

        // 将带超时的 Context 传递给后续处理
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

// 数据库查询：监听 ctx.Done()
func QueryDatabase(ctx context.Context) ([]Record, error) {
    done := make(chan []Record, 1)
    go func() {
        // 模拟耗时查询
        time.Sleep(5 * time.Second)
        done <- fetchRecords()
    }()

    select {
    case result := <-done:
        return result, nil
    case <-ctx.Done():
        return nil, ctx.Err() // 返回 context.DeadlineExceeded
    }
}

4.4 取消信号传播：优雅终止

当客户端断开连接（如浏览器关闭、网络中断）时，HTTP 请求的 Context 会自动取消。中间件应主动检查 ctx.Done()，避免在已断开的连接上继续执行无用操作。

// 取消感知中间件
func CancelAwareMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx := r.Context()

        // 启动一个 goroutine 监听取消信号
        go func() {
            select {
            case <-ctx.Done():
                log.Println("请求被取消，清理资源")
                // 清理数据库连接、文件句柄等
            case <-time.After(10 * time.Second):
                // 正常完成，不做额外处理
            }
        }()

        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

4.5 Context 在中间件链中的传播流程

下图展示了 Context 在三个中间件中的传递过程：TraceMiddleware 注入元数据，TimeoutMiddleware 设置超时，CancelAwareMiddleware 监听取消信号。每个中间件都基于前一个 Context 创建新的子 Context。

4.6 常见陷阱与避坑指南

• Key 类型冲突： 不要使用 string 或 int 作为 Context key，始终定义包级私有类型。
• 忘记调用 cancel： 使用 WithTimeout 或 WithCancel 时，务必 defer cancel()，否则会导致资源泄漏。
• 在 Context 中存储可变对象： Context 的值应当是不可变的。如果存储指针或 slice，多个 goroutine 并发读写会导致数据竞争。
• 忽略 ctx.Err()： 在 select 中收到 ctx.Done() 后，应返回 ctx.Err() 而非自定义错误，便于上层中间件识别取消原因。
• 超时时间设置过短或过长： 根据下游服务的 P99 延迟合理设置超时，避免频繁超时或长时间等待。

4.7 实战：构建一个完整的链路 Context 中间件

以下代码将元数据注入、超时控制、取消监听整合为一个中间件链，展示 Context 在真实工程中的使用方式。

// 链路 Context 中间件组合
func ChainMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 1. 注入元数据
        ctx := context.WithValue(r.Context(), TraceIDKey, generateTraceID())
        ctx = context.WithValue(ctx, UserIDKey, extractUserID(r))

        // 2. 设置超时
        ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
        defer cancel()

        // 3. 启动取消监听 goroutine
        go func() {
            select {
            case <-ctx.Done():
                log.Printf("[%s] 请求取消: %v", ctx.Value(TraceIDKey), ctx.Err())
                cleanupResources()
            case <-time.After(10 * time.Second):
                // 正常完成
            }
        }()

        next.ServeHTTP(w, r.WithContext(ctx))
    })
}