Go 中如何为每个 HTTP 请求正确创建和使用 Context_技术教程

在 go web 开发中，context 是管理请求生命周期、传递元数据（如请求 id、用户身份、超时控制）及实现优雅取消的核心机制；它替代了其他语言中的“线程局部存储”，通过显式传参保障可读性与可控性。

Go 的 context 包（现为标准库 context，已不再使用 golang.org/x/net/context）是构建健壮、可观测、可中断服务的关键基础设施。其核心价值并非“仅仅多传一个参数”，而在于统一契约：所有下游组件（数据库、HTTP 客户端、日志、中间件等）都接受 context.Context 作为首个参数，并遵循同一套取消/超时语义。

✅ 正确初始化请求级 C
ontext 的实践方式

应在 HTTP 处理函数入口处创建 Context，并注入关键请求上下文信息。推荐做法如下：

func handler(w http.ResponseWriter, r *http.Request) {
    // 1. 基于 request 创建带超时的 context（例如总处理时间 ≤ 5s）
    ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second)
    defer cancel() // 确保及时释放资源

    // 2. 可选：注入结构化元数据（避免 string key，提升类型安全）
    ctx = context.WithValue(ctx, keyRequestID, generateRequestID())
    ctx = context.WithValue(ctx, keyUserID, getUserIDFromToken(r))

    // 3. 将 context 显式传递给业务逻辑层
    result, err := userService.FetchProfile(ctx, "user-123")
    if err != nil {
        if errors.Is(err, context.DeadlineExceeded) {
            http.Error(w, "request timeout", http.StatusGatewayTimeout)
            return
        }
        http.Error(w, "internal error", http.StatusInternalServerError)
        return
    }

    json.NewEncoder(w).Encode(result)
}

? 注意：r.Context() 本身已是 Go net/http 框架自动创建的请求级 Context（继承自 context.Background() 并内置了 Done() 和 Err() 通道），应优先基于它派生，而非直接调用 context.Background()。

?️ 安全传递元数据的最佳实践

避免使用 context.WithValue(ctx, "user_id", id) 这类裸字符串 key —— 易冲突、无类型检查、难以维护。应定义私有未导出类型作为 key：

type ctxKey string
const (
    keyRequestID ctxKey = "request_id"
    keyUserID    ctxKey = "user_id"
)

// 使用时：
ctx = context.WithValue(ctx, keyRequestID, "req_abc123")
// 取值时强制类型断言：
if reqID, ok := ctx.Value(keyRequestID).(string); ok {
    log.Printf("Handling request: %s", reqID)
}

⏱️ 超时与取消：为什么必须由调用方统一控制？

假设你的服务需并行调用用户服务、订单服务和通知服务。若每个子服务各自硬编码 3 秒超时，整体响应可能长达 9 秒；而通过顶层 Context 统一设 WithTimeout(2*time.Second)，所有子调用会同时收到取消信号，实现真正的端到端超时控制：

func fetchAllData(ctx context.Context) (User, Order, Notification, error) {
    // 启动三个 goroutine，均接收同一 ctx
    userCh := make(chan User, 1)
    go func() { userCh <- fetchUser(ctx) }()

    orderCh := make(chan Order, 1)
    go func() { orderCh <- fetchOrder(ctx) }()

    notifCh := make(chan Notification, 1)
    go func() { notifCh <- sendNotification(ctx) }()

    // 任一失败或超时即返回
    select {
    case u := <-userCh:
        select {
        case o := <-orderCh:
            select {
            case n := <-notifCh:
                return u, o, n, nil
            case <-ctx.Done():
                return u, o, Notification{}, ctx.Err()
            }
        case <-ctx.Done():
            return u, Order{}, Notification{}, ctx.Err()
        }
    case <-ctx.Done():
        return User{}, Order{}, Notification{}, ctx.Err()
    }
}

✅ 总结：Context 不是“可选项”，而是 Go 服务的骨架约定

✅ 必传：所有可能阻塞或依赖请求生命周期的函数，首参应为 context.Context；
✅ 早建晚传：在 HTTP 入口（或 gRPC handler）初始化，沿调用链向下透传，绝不中途丢弃；
✅ 勿滥用 WithValue：仅用于传递跨层、低频、非业务主参数（如 traceID、authInfo）；业务参数请走显式函数参数；
✅ 务必监听 Done：任何阻塞操作（http.Do, db.Query, time.Sleep, channel receive）前，应 select 监听 ctx.Done()；
✅ 清理资源：使用 defer cancel() 配合 WithCancel/WithTimeout，防止 goroutine 泄漏。