4. Context上下文：context.Context接口、WithValue传递请求级数据、WithTimeout超时控制、WithCancel取消传播

在分布式系统与中间件链路中，每个请求的生命周期管理是核心挑战。Go 的 context.Context 接口提供了一种标准化的方式，在 goroutine 之间传递截止时间、取消信号和请求级数据。本章深入剖析 Context 的四大核心能力：接口契约、值传递、超时控制与取消传播。

4.1 context.Context 接口契约

context.Context 是一个接口，定义了四个方法，所有派生 context 都必须实现：

// 创建根 context
ctx := context.Background()

// 检查 context 是否已取消
select {
case <-ctx.Done():
    // 已取消，处理清理
    log.Println("context canceled:", ctx.Err())
default:
    // 继续执行
}

4.2 WithValue：请求级数据传递

context.WithValue 用于在请求链路中传递元数据，如 trace ID、用户身份、认证令牌。数据以键值对形式存储，键必须为可比较类型（通常自定义类型避免冲突）。

// 定义自定义 key 类型
type contextKey string

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

// 注入数据
ctx := context.WithValue(context.Background(), TraceIDKey, "abc-123")
ctx = context.WithValue(ctx, UserIDKey, "user-456")

// 提取数据
if traceID, ok := ctx.Value(TraceIDKey).(string); ok {
    log.Printf("trace_id: %s", traceID)
}

4.3 WithTimeout：超时控制

context.WithTimeout 为操作设置最大执行时间，超时后自动取消。这是防止 goroutine 泄漏和请求堆积的关键手段。

// 设置 2 秒超时
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel() // 重要：释放资源

// 模拟耗时操作
select {
case <-time.After(3 * time.Second):
    fmt.Println("操作完成")
case <-ctx.Done():
    fmt.Println("操作超时:", ctx.Err()) // 输出: context deadline exceeded
}

4.4 WithCancel：取消传播

context.WithCancel 返回一个可手动取消的 context。当父 context 取消时，所有子 context 级联取消，形成取消传播树。

// 创建可取消的父 context
parentCtx, parentCancel := context.WithCancel(context.Background())

// 派生两个子 context
childCtx1, _ := context.WithCancel(parentCtx)
childCtx2, _ := context.WithCancel(parentCtx)

// 启动 goroutine 监听取消
go func() {
    <-childCtx1.Done()
    log.Println("child 1 canceled:", childCtx1.Err())
}()

go func() {
    <-childCtx2.Done()
    log.Println("child 2 canceled:", childCtx2.Err())
}()

// 取消父 context，所有子 context 级联取消
parentCancel()
time.Sleep(100 * time.Millisecond)
// 输出:
// child 1 canceled: context canceled
// child 2 canceled: context canceled

4.5 四种派生函数对比

4.6 中间件链路中的 Context 最佳实践

1. 始终使用 context.Background() 作为根：在 main 函数、初始化代码和测试中创建根 context。
2. 在中间件入口派生新 context：每个中间件通过 WithValue 注入元数据，通过 WithTimeout 设置超时。
3. defer cancel() 确保释放：所有 WithCancel、WithTimeout、WithDeadline 返回的 cancel 函数必须调用。
4. 优先使用 Done() channel 监听取消：避免轮询 Err()，使用 select 监听 <-ctx.Done()。
5. 不存储 context 到结构体：context 应作为函数第一个参数传递，而非存储在 struct 中。

// 中间件链路示例
func AuthMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 从请求头提取 token
        token := r.Header.Get("Authorization")
        ctx := context.WithValue(r.Context(), "token", token)
        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

func TimeoutMiddleware(timeout time.Duration) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            ctx, cancel := context.WithTimeout(r.Context(), timeout)
            defer cancel()
            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

4.7 错误聚合与 Context 取消的协同

在错误聚合模式中，Context 取消与 channel 通信协同工作：

• 当某个 goroutine 发生致命错误时，调用 cancel() 通知其他 goroutine 停止工作。
• 其他 goroutine 通过 <-ctx.Done() 感知取消，立即返回，避免资源浪费。
• 错误聚合器收集所有 goroutine 的返回错误，结合 ctx.Err() 判断是超时、取消还是业务错误。

// 错误聚合 + Context 取消示例
func aggregateWithContext(ctx context.Context, urls []string) []error {
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    errCh := make(chan error, len(urls))
    for _, url := range urls {
        go func(u string) {
            select {
            case <-ctx.Done():
                errCh <- ctx.Err()
                return
            default:
                // 模拟请求
                if u == "bad" {
                    cancel() // 触发级联取消
                    errCh <- fmt.Errorf("failed: %s", u)
                    return
                }
                errCh <- nil
            }
        }(url)
    }

    var errs []error
    for i := 0; i < len(urls); i++ {
        errs = append(errs, <-errCh)
    }
    return errs
}