Golang如何在函数间传递Context_Context使用规范说明

context.Context不应硬编码为函数首参，仅在需控制生命周期、传递取消信号或请求数据时显式传入；纯计算函数无需它，I/O操作才需接收并向下传递，且派生上下文应由创建者负责cancel。

Context 不能作为函数第一个参数硬编码

Go 官方明确反对把 context.Context 当作“固定第一位参数”来设计 API。它只应在**真正需要控制生命周期、传递取消信号或携带请求范围数据**时才显式传入。盲目加 ctx context.Context 到每个函数签名，会让接口变重、测试变难、调用方负担加重。

常见错误是工具生成代码或初学者模仿 http.HandlerFunc 风格，给所有函数都塞一个 ctx 参数，哪怕该函数根本不涉及 I/O 或超时控制。

• 纯计算函数（如字符串处理、数值转换）不需要 context.Context
• 底层工具函数（如 bytes.Equal、sort.Ints）不接受 context.Context
• 若函数内部调用了 net/http、database/sql、time.Sleep 等可能阻塞或需响应取消的操作，才考虑接收 ctx

Context 应随调用链向下传递，不可跨 goroutine 复用

context.Context 是不可变的，但它的派生（如 context.WithTimeout、context.WithValue）会创建新实例。关键原则是：谁创建，谁 cancel；谁使用，谁传递。

典型误用是在 goroutine 中直接复用上层传入的 ctx 并调用 cancel() —— 这会提前终止整个请求链，而非仅当前分支。

• 不要在 goroutine 内部调用 cancel()，除非你明确拥有该 context 的所有权（即你调用了 WithCancel）
• 需要并发执行多个子任务？用 context.WithCancel(ctx) 派生新上下文，并在 goroutine 内部管理其生命周期
• 若只是读取 ctx.Done() 或 ctx.Value()，可安全传递原 ctx，无需复制

func handleRequest(ctx context.Context) {
    // ✅ 正确：为子任务派生独立上下文
    childCtx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()

    go func() {
        select {
        case <-childCtx.Done():
            log.Println("subtask canceled:", childCtx.Err())
        }
    }()
}

不要用 Context.Value 传业务参数，只传请求元数据

context.WithValue 是 Context 唯一的“写入”方式，但它不是通用传参通道。Go 团队多次强调：它只适合传递**跨多层调用、与请求强相关、且无法通过函数参数自然传递的元数据**，比如用户身份、请求 ID、追踪 traceID。

把它当函数参数替代品（例如传 userID、config、logger），会导致类型不安全、难以测试、IDE 无法跳转、重构困难。

• 业务逻辑所需参数，请明确定义为函数参数（支持类型检查和文档化）
• 日志器、配置对象等依赖项，应通过结构体字段或选项模式注入，而非藏在 ctx.Value 里
• 若必须用 ctx.Value，请定义全局唯一 key 类型（如 type ctxKey string），避免字符串 key 冲突

type userKey struct{}
func WithUser(ctx context.Context, u *User) context.Context {
    return context.WithValue(ctx, userKey{}, u)
}
func UserFromCtx(ctx context.Context) (*User, bool) {
    u, ok := ctx.Value(userKey{}).(*User)
    return u, ok
}

HTTP handler 中的 C

ontext 使用边界要清晰

HTTP server（如 net/http）自动将请求上下文注入 http.Request.Context()，这是天然的请求生命周期载体。但注意：这个 ctx 仅属于当前 HTTP 请求，不应泄露到非请求相关的后台任务中。

常见混淆点是把 handler 的 r.Context() 直接传给定时任务、消息队列消费者或数据库连接池初始化——这些场景需要独立的生命周期控制，和 HTTP 请求无关。

• HTTP handler 内发起的异步操作（如发通知、写日志到远端），应派生带超时的子 ctx，并确保不会因请求结束而意外中断
• 全局初始化（如 DB 连接、gRPC client）、长周期后台协程，应使用 context.Background() 或自定义长期存活的 ctx，而非复用 request ctx
• 中间件中增强 ctx（如加 traceID、user），应返回新 *http.Request，而非修改原 ctx 后丢弃

实际项目中最容易被忽略的是 Context 的所有权归属和取消时机。一个 context.WithCancel 创建的 ctx，cancel 函数只能由创建者调用；而 http.Request.Context() 的 cancel 是由 server 内部在请求结束时自动触发的——这两类 cancel 行为混用，几乎必然导致 goroutine 泄漏或过早终止。