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 中的 Context 使用边界要清晰
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.WithCancel 创建的 ctx，cancel 函数只能由创建者调用；而 http.Request.Context() 的 cancel 是由 server 内部在请求结束时自动触发的——这两类 cancel 行为混用，几乎必然导致 goroutine 泄漏或过早终止。
