Go Context:别塞进 struct,顺着请求往下传

Go Context:别塞进 struct,顺着请求往下传

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 从 Handler 经 Service、Repo 传递,并发再派生
Context 从 Handler 经 Service、Repo 传递,并发再派生 · 点击查看 SVG 原图

类比局限一句说清:运单解释「作用域与传递」;解释不了 context.WithValue 该不该塞业务大对象——值传递是另一条窄门,本文不展开。


精确定义:请求作用域,不是实例状态

请求作用域(request-scoped):随一次入站请求(或一次明确发起的操作)创建、派生、结束;取消与截止时间属于这一次,不属于进程里活很久的那个 Service 实例。

官方包文档写得很硬(意译对齐原文口径):

  1. Do not store Contexts inside a struct type——不要把 Context 存进结构体类型。
  2. instead, pass a Context explicitly to each function that needs it——需要它的函数,显式传入。
  3. 惯例: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 / WithCanceldefer cancel();把派生后的 ctx 交给 Service
Service编排业务;调用 Repo / 下游同一请求路径继续传同一个(或再收紧超时后的)ctx
并发子任务扇出查询、并行写各任务用 WithCancel / WithTimeout 从父 ctx 派生;父取消则子应感知
Repo / ClientI/O把收到的 ctx 交给驱动 / SDK(它们懂取消)

易混的一句纠正:

  • 原稿式说法「每个方法调用都传递独立 Context」——若理解成每层 Background(),错。
  • 可复述版:每个需要取消语义的函数,显式接收 ctx 参数;同一请求调用链共享派生后的 ctx;并发任务再各自派生。

和 /blog/goroutine_explosion_worker_pool/ 的衔接:工作池里每个任务仍应带上自己的(或从父派生的)ctx——池限制的是并发形态,ctx 管的是「这单要不要停」。


常见坑

  1. 构造函数 NewXxx(ctx) 把 ctx 存进字段
    实例复用后,字段里仍是创建那一刻的截止时间。Handler 里派生了新超时也传不进去。

  2. 把「首参传递」写成「每层新建 Background」
    上游取消到不了下游;链路追踪 / 截止时间断裂。同请求要接力,不要重生。

  3. Service 依赖框架 RequestContext
    业务层被 HTTP 框架拖下水,单测和换传输协议都疼。框架停在边上,标准 context.Context 往下走。

  4. 父 ctx 已取消,仍对存着的字段「再试一次」
    重试若需要新的截止时间,应基于仍有效的父 ctx(或明确的新根策略)再 WithTimeout,而不是翻炒字段里的尸体。

  5. 无界扇出 + 共享一个存着的 ctx
    取消一人、全员收工——或反过来无人取消。并发模型见工作池文;这里先把「别存字段」做对。

  6. 用 WithValue 塞大对象当隐式依赖注入
    官方允许请求作用域的值,但不等于「匿传 DB 句柄」。传参能写清的,别藏进 ctx。


小结

  1. Context = 请求作用域的取消 / 超时 / 少量值,不是 Service 单例状态。
  2. 硬规则:不要把 Context 存进 struct;需要它的函数显式传入,惯例作首参。
  3. 同请求共享派生后的 ctx;只有并发分叉或单独截止,才再 WithCancel / WithTimeout。
  4. 业务层只认 context.Context;框架 Request 类型留在 Handler。
  5. 账单:签名与接力变烦,换可预期的取消与超时——漏传和存字段都会以更难查的线上偶发付钱。

下一步:搜一遍 struct { 附近的 context.Context 字段 → 改成方法首参 → 核对 Handler 是否 WithTimeout 且 defer cancel() → 并发扇出处对照 /blog/goroutine_explosion_worker_pool/。权威阅读:Go Blog: Context、pkg.go.dev/context。