
Hello,我是小兔大白糖。 线上偶发 context canceled,日志里的请求 ID 对不上这次调用;再一查,Service 字段里塞着一个「上次请求留下来的」context.Context。写成这篇,给写过 HTTP Handler、但对「ctx 该不该进 struct」还含糊的后端同学。
说明:示例均为教学脱敏 / 示意。读完带走的是可复述的硬规则与取舍,不是可粘贴的内部框架代码。
估计阅读时间:8 分钟
目录
为什么现在要关心
context.Context 管的是「这一次请求」的取消、超时和少量跨层值——不是 Service / Client 的长期配置。
常见现场:
| 你看到的现象 | 常见真相 |
|---|---|
偶发 context canceled,业务日志却像「新请求」 | 复用了上一单已取消 / 已超时的 ctx |
| 单测偶绿偶红,压测下取消「串味」 | 多个请求或 goroutine 共享了同一个存进 struct 的 ctx |
| 改超时只改了 Handler,下游仍按旧截止时间跑 | ctx 在构造时钉死,方法里再也换不了 |
| 「每个调用传独立 Context」写进规范后,同请求里超时对不上 | 把「首参传递」误读成「每层重新 Background()」 |
并发扇出怎么收成有界池,见 /blog/goroutine_explosion_worker_pool/。本文只钉一件事:ctx 跟请求走,不贴在长期存活的对象上。
心智模型:快递单跟包裹走
主比喻:快递单。
- 跟包裹走:运单号、签收截止、取消件——都贴在这一票货上,分拣、干线、派送逐手交接。对应:
ctx作函数第一个参数,Handler → Service → Repo 往下传。 - 贴在仓库墙上:仓库(Service 单例)墙上贴一张「当前运单」。下一票货进仓时,墙上还是上一票的截止时间——取消一件,整仓「串味」。对应:把
context.Context存进长期存活的 struct 字段。
类比局限一句说清:运单解释「作用域与传递」;解释不了 context.WithValue 该不该塞业务大对象——值传递是另一条窄门,本文不展开。
精确定义:请求作用域,不是实例状态
请求作用域(request-scoped):随一次入站请求(或一次明确发起的操作)创建、派生、结束;取消与截止时间属于这一次,不属于进程里活很久的那个 Service 实例。
官方包文档写得很硬(意译对齐原文口径):
- Do not store Contexts inside a struct type——不要把 Context 存进结构体类型。
- instead, pass a Context explicitly to each function that needs it——需要它的函数,显式传入。
- 惯例:
ctx作第一个参数(func F(ctx context.Context, …))。
再钉三条边界:
| 说法 | 对不对 | 人话 |
|---|---|---|
| Context ≈ 请求级取消 / 超时 / 少量值 | 对 | 跨 API 边界带着走 |
| Context ≈ Service 字段里的全局状态 | 错 | 生命周期跟实例绑死就坏了 |
「每个函数调用都 context.Background()」 | 错 | 同请求应共享派生后的同一条链 |
「并发子任务再各自 WithCancel / WithTimeout」 | 对 | 分叉处才拆,不是每层无脑新建 |
业务层只认标准库的 context.Context。不要把 HTTP 框架的 Request 对象(或框架专用 RequestContext)塞进 Service 字段当「万能袋子」——框架类型停在 Handler;往下只传 ctx + 领域入参。
对照表:存进去 vs 当参数传
一眼表比大段对错代码管用:存字段坏在「生命周期」和「共享」,不坏在「少写一个参数」。
| 维度 | ❌ 存进 struct 字段 | ✅ 方法首参传递 |
|---|---|---|
| 生命周期 | 跟 Service / Client 实例一样长 | 跟这一次调用一样长 |
| 多请求 | 易复用已取消 / 已超时的旧 ctx | 每次入站带本次派生的 ctx |
| 并发 | 多 goroutine 易「串」同一份取消信号 | 调用方决定传同一派生 ctx,或给子任务再拆 |
| 可测性 | 构造时钉死,单测难换超时 | 测试里随意注入 WithTimeout / 已取消的 ctx |
| 与官方口径 | 直接撞上「Do not store…」 | 对齐「explicitly to each function」 |
教学示意(合计约十几行,非生产实现;类型名用 OrderService):
// ❌ 别这样:ctx 钉在实例上
type OrderService struct {
ctx context.Context
}
// ✅ 这样:实例只持有依赖;ctx 每次传入
type OrderService struct {
repo OrderRepository
}
func (s *OrderService) List(ctx context.Context, q Query) ([]Order, error) {
return s.repo.Find(ctx, q)
}代价也说清:首参传递意味着签名变长、中间层都要接力;漏传时编译器帮得有限(接口未改全时尤甚)。换来的是取消与超时可预期——这是账单,不是口号。
传递链与「要不要拆 ctx」
同一次请求:一条派生链往下传;只有并发分叉或单独截止时间,才再 With*。
典型形状(教学):
| 层 | 做什么 | ctx 怎么处理 |
|---|---|---|
| Handler | 从入站请求取根 ctx;常 WithTimeout / WithCancel | defer cancel();把派生后的 ctx 交给 Service |
| Service | 编排业务;调用 Repo / 下游 | 同一请求路径继续传同一个(或再收紧超时后的)ctx |
| 并发子任务 | 扇出查询、并行写 | 各任务用 WithCancel / WithTimeout 从父 ctx 派生;父取消则子应感知 |
| Repo / Client | I/O | 把收到的 ctx 交给驱动 / SDK(它们懂取消) |
易混的一句纠正:
- 原稿式说法「每个方法调用都传递独立 Context」——若理解成每层
Background(),错。 - 可复述版:每个需要取消语义的函数,显式接收 ctx 参数;同一请求调用链共享派生后的 ctx;并发任务再各自派生。
和 /blog/goroutine_explosion_worker_pool/ 的衔接:工作池里每个任务仍应带上自己的(或从父派生的)ctx——池限制的是并发形态,ctx 管的是「这单要不要停」。
常见坑
-
构造函数
NewXxx(ctx)把 ctx 存进字段
实例复用后,字段里仍是创建那一刻的截止时间。Handler 里派生了新超时也传不进去。 -
把「首参传递」写成「每层新建 Background」
上游取消到不了下游;链路追踪 / 截止时间断裂。同请求要接力,不要重生。 -
Service 依赖框架 RequestContext
业务层被 HTTP 框架拖下水,单测和换传输协议都疼。框架停在边上,标准context.Context往下走。 -
父 ctx 已取消,仍对存着的字段「再试一次」
重试若需要新的截止时间,应基于仍有效的父 ctx(或明确的新根策略)再WithTimeout,而不是翻炒字段里的尸体。 -
无界扇出 + 共享一个存着的 ctx
取消一人、全员收工——或反过来无人取消。并发模型见工作池文;这里先把「别存字段」做对。 -
用 WithValue 塞大对象当隐式依赖注入
官方允许请求作用域的值,但不等于「匿传 DB 句柄」。传参能写清的,别藏进 ctx。
小结
- Context = 请求作用域的取消 / 超时 / 少量值,不是 Service 单例状态。
- 硬规则:不要把 Context 存进 struct;需要它的函数显式传入,惯例作首参。
- 同请求共享派生后的 ctx;只有并发分叉或单独截止,才再
WithCancel/WithTimeout。 - 业务层只认
context.Context;框架 Request 类型留在 Handler。 - 账单:签名与接力变烦,换可预期的取消与超时——漏传和存字段都会以更难查的线上偶发付钱。
下一步:搜一遍 struct { 附近的 context.Context 字段 → 改成方法首参 → 核对 Handler 是否 WithTimeout 且 defer cancel() → 并发扇出处对照 /blog/goroutine_explosion_worker_pool/。权威阅读:Go Blog: Context、pkg.go.dev/context。