Go 中 context 必须显式作为首参数传递，不可依赖全局变量或闭包；WithCancel/Timeout/Deadline 的区别在于取消触发主体不同；WithValue 仅限传请求级只读元数据，key 应用未导出类型。
Context 传递必须用函数参数显式传入
Go 的 context.Context 不是全局变量，也不能靠闭包或包级变量“偷偷”携带。一旦你从 http.Request.Context() 或 context.WithTimeout() 拿到一个 Context，它就必须作为第一个参数（惯例）一路手动传给所有可能需要它的下游函数——包括数据库调用、HTTP 客户端请求、子 goroutine 启动点。
常见错误是：在某个中间函数里直接调用 context.Background() 或复用一个包级 var ctx = context.Background()，结果超时/取消信号根本传不到深层逻辑。
- 所有涉及 I/O 或可能阻塞的函数签名，应以
func(ctx context.Context, ...)开头 - 启动新 goroutine 时，必须把当前 ctx 传进去，不能在 goroutine 内部重新创建
- 如果调用第三方库（如
database/sql、net/http），确认其方法是否接收context.Context；老版本驱动可能不支持，需升级
WithCancel / WithTimeout / WithDeadline 的选择依据
三种派生 Context 的核心区别不在“能不能取消”，而在于谁负责触发取消：
-
context.WithCancel(parent)：由你主动调用返回的cancel()函数来终止，适合手动控制生命周期（如用户点击取消按钮） -
context.WithTimeout(parent, 5*time.Second)：底层自动调用time.AfterFunc，5 秒后自动触发 cancel；等价于WithDeadline(parent, time.Now().Add(5*time.Second)) -
context.WithDeadline(parent, t)：按绝对时间截止，适合与外部系统约定 deadline（如上游服务声明“请在 2024-06-15T14:30:00Z 前返回”）
注意：WithTimeout 返回的 cancel 函数必须被调用（哪怕没超时），否则会泄漏 timer。惯用写法是 defer cancel()，但要确保 defer 发生在 goroutine 内部而非外层函数——否则可能提前释放。
立即学习“go语言免费学习笔记（深入）”；
Value 方法只能传请求范围的只读元数据
context.WithValue(parent, key, val) 是 Context 唯一的“存值”方式，但它不是通用状态容器。它的设计目标很窄：仅用于传递跨 API 边界的、与请求强相关且只读的元数据，比如用户 ID、请求 trace ID、认证 scope。
- key 必须是可比较类型，推荐用未导出的 struct{} 类型变量，避免字符串 key 冲突：
type ctxKeyUser struct{}+ctx.Value(ctxKeyUser{}) - 绝不要用
WithValue传配置、连接池、logger 实例——这些该通过函数参数或依赖注入传入 - Value 查找是链式遍历，深度过大会有微小开销；更重要的是，它破坏了函数纯度，让调用关系变得隐式难测
HTTP Server 中 Context 生命周期容易被忽略的点
HTTP handler 接收的 *http.Request 自带 Context，但它在 handler 返回后即被 cancel。如果你在 handler 内启了一个异步 goroutine 并直接用了 r.Context()，该 goroutine 可能刚运行就收到取消信号。
- 需要后台执行的任务，应基于
r.Context()创建新的context.WithCancel(r.Context())，并在任务结束时调用 cancel - 若任务必须脱离请求生命周期（比如发消息到队列后立即返回），应改用
context.Background()，但要确保该操作本身不依赖请求上下文（如不再读取r.Header） - 中间件中修改 Context（如加 Value）必须用
req = req.WithContext(newCtx)赋值回去，原req不可变
Context 的本质是信号+元数据的轻量载体，它的力量全靠严格的手动传递和明确的生命周期管理。漏掉一次传参、多调一次 cancel、错用一次 Value，都可能让超时失效、goroutine 泄漏或日志链路断裂。
