做 Go 服务端开发的人，迟早会跟 context 打交道。很多人会用context.WithTimeout给接口套个超时，会用c.Request.Context()给下游调用传上下文，可一旦被问起"取消信号到底是怎么从父 context 一路传到子 context 的"，能讲清楚的人其实不多。这篇就把 Context 取消信号传播机制从头到尾拆开，讲明白源码层面的传播链路、业务里的正确用法、以及我实际踩过的几个坑。无论你是刚接触 Go 还是写了两三年，这文章都能帮你把 context 这块短板补上。
Context 在 Go 里的地位，基本等同于"请求级生命周期的标准载体"。从 HTTP 入口到数据库查询、RPC 调用、消息队列消费，几乎每一层都能看到它的身影。搞懂了它的取消传播机制，很多线上问题——比如 goroutine 泄漏、接口超时却不生效、并发任务收不了尾——都能一眼定位到根因。
1. Context 到底在解决什么问题
1.1 没有取消信号时，goroutine 是怎么悄悄泄漏的
想象一个典型场景：HTTP 接口收到请求后起了三个 goroutine，分别去查用户信息、查订单列表、查库存，每个 goroutine 里又发起 RPC 调用。如果客户端等不及断开连接了，或者服务端设置了 2 秒超时，这三个 goroutine 会怎样？没有取消机制的话，它们会继续把整个调用链跑完——哪怕结果已经没人要了。接口流量一大，这种"结果没人收但还在拼命跑"的 goroutine 越积越多，内存疯涨，连接池被占满，最后整个服务被拖垮。
我见过最典型的线上事故，就是一个批量任务接口起了大量 goroutine 处理数据，处理过程中要调一个第三方接口。第三方接口偶尔卡住不返回，goroutine 全堵在等待响应上。因为没人告诉它们"你已经没必要继续等了"，这些 goroutine 就永远挂在那里。从监控看，goroutine 数量持续爬升，最终 OOM。这就是没有取消机制的代价。
Go 语言里 goroutine 一旦创建，就没法从外部强制杀死。只能靠协作式取消——也就是说，你通知它"该停了"，它自己决定在合适的时机退出。Context 就是这套协作机制的标准化载体。说白了，Context 解决的第一个问题就是：让每一个 goroutine 都知道自己什么时候该收工。
1.2 四个方法的接口设计：够用且克制
context 包的核心是一个只有四个方法的接口，简洁得有点不像官方库：
type Context interface { Deadline() (deadline time.Time, ok bool) Done() <-chan struct{} Err() error Value(key any) any }四个方法各管一摊：
Deadline告诉调用方这个 context 有没有设置终止时间、什么时候终止。没有设置的话ok返回 false。Done返回一个只读 channel。这个 channel 被关闭，就代表取消信号到了。Err在Done关闭后返回取消原因，通常是context.Canceled（主动取消）或context.DeadlineExceeded（超时）。Value用来取键值对，属于附带能力，跟取消传播没有直接关系。
注意Done的返回值是<-chan struct{}，一个只收不发的只读 channel。设计成只读，外部代码就只能"等待"它关闭，没法往里写数据，从类型层面就杜绝了误操作。struct{}是空结构体，不占内存，纯粹当一个信号灯用。channel 关闭本身就是一个广播事件，所有监听这个 channel 的 goroutine 都会立刻收到通知。
这四个方法的设计非常克制，没有提供"取消指定子任务"这种精细 API。原因在于取消传播在 context 模型里是单向的、从上到下的广播：父 context 取消，所有子 context 全部跟着取消；反过来，一个子 context 取消，不影响它的兄弟节点。这种简单粗暴的全量广播，反而让心智负担降到最低——你不需要关心谁是谁的下游，只要保证 context 沿着调用链传递，取消信号就能覆盖整棵任务树。
2. 取消信号传播的源码级拆解
2.1 cancelCtx 的核心结构与 cancel 动作
以 Go 1.21 版本的实现为例（不同版本细节略有差异，但核心逻辑非常稳定），WithCancel内部创建的是cancelCtx，结构大致如下：
type cancelCtx struct { Context mu sync.Mutex done atomic.Value children map[canceler]struct{} err error }Context：内嵌的父 context。当子节点没被取消时，取 deadline、取值等操作都委托给父节点。mu：保护children和err的互斥锁。done：用atomic.Value缓存已关闭的 channel。为什么用 atomic？因为Done()可能被多个 goroutine 并发调用，而 channel 的创建和关闭存在竞态，atomic 能保证可见性。children：当前节点的所有子canceler，是一个 map。err：取消原因。
cancel方法是整个传播机制的心脏。简化后的核心流程是：
- 加锁，检查
c.err是否已非 nil，如果是就直接返回——保证幂等； - 设置
c.err = err； - 关闭
done里存的 channel； - 遍历
children，逐个调用子节点的cancel； - 清空
children，释放内存； - 解锁，然后从父节点的 children map 里把自己摘掉。
这里有一个顺序细节值得品：先写 err，再关 channel。这保证了接口契约——任何观察到Done()被关闭的代码，随即调用Err()一定能拿到非 nil 的原因。如果顺序反过来，就会出现"信号到了但查不到原因"的诡异窗口期。
donechannel 的关闭还有一个特殊处理：如果 channel 还没被创建过（因为done是懒加载的，首次调用Done()时才创建），就直接把包级别的closedchan（一个已经关闭的空 channel）存进 atomic.Value。这样省去了"先建 channel 再关闭"的竞态，而且广播效果完全一样。
cancel函数被设计成幂等且并发安全，这一条很重要。意味着你在defer里调cancel，同时又在某个条件分支里提前调了cancel，完全不会 panic，也不会出问题。日常写代码时，即使已经手动取消过，依然建议保留defer cancel()，纯粹为了兜底。
2.2 propagateCancel：父子关系是怎么建立的
每次调用WithCancel(parent)、WithTimeout(parent, d)这类函数时，都会执行propagateCancel(parent, child)。这一步就是父子关系建立的起点，逻辑分三条路径：
第一条，父节点的Done()返回 nil。说明父节点本身就是一个永远不会被取消的 context（比如自定义实现），那就不用建立任何关系，子节点独立存活。
第二条，父节点已经取消了（select快速检查<-parent.Done()命中）。那子节点也别折腾了，直接就地取消。
第三条，正常情况。尝试从父节点往上找到最近的cancelCtx（parentCancelCtx会循环向上查找，中间隔了多少层valueCtx都能穿透），找到后把子节点注册进父节点的childrenmap：
if p, ok := parentCancelCtx(parent); ok { p.mu.Lock() if p.err != nil { child.cancel(false, p.err) } else { if p.children == nil { p.children = make(map[canceler]struct{}) } p.children[child] = struct{}{} } p.mu.Unlock() }如果向上找不到cancelCtx（父节点是第三方库的自定义 Context 实现），就只能退化成启动一个 goroutine，同时监听父节点的Done和子节点的Done，谁先触发谁结束监听：
go func() { select { case <-parent.Done(): child.cancel(false, parent.Err()) case <-child.Done(): } }()你注意第三条路径里那个parentCancelCtx查找——它保证了注册点一定是最靠近自己的那个cancelCtx。所以哪怕你在中间包了七八层WithValue，取消信号依然能通过最近的cancelCtx正确下传。
传播方向是单向的：父取消，子跟着取消；子取消，父无感。这也意味着，如果有好几个子任务共用一个父 context，任何一个子任务想通过取消自己来连累兄弟任务，是做不到的。想实现"一个失败全部取消"，得靠errgroup或者手动包一层统一管理，后面会讲。
2.3 timerCtx：超时取消的底层实现
WithTimeout(ctx, d)本质上就是WithDeadline(ctx, time.Now().Add(d))。WithDeadline创建的是timerCtx，它内嵌了cancelCtx，额外多了一个deadline字段和一个定时器timer。
创建时有几个关键判断：
- 先看父节点有没有更早的
deadline。如果父节点的截止时间比当前设置的时间还早，说明子节点根本活不到自己设的截止时间，那就没必要再开一个定时器，跟着父节点走就行。 - 如果自己的
deadline更早，就启动一个time.AfterFunc，到点后触发内部的cancel(true, DeadlineExceeded)。
timerCtx的Deadline()方法返回自己的deadline。这样上层就能根据整条链路上最早的截止时间做决策，比如设置 HTTP 客户端的超时时间。
timerCtx的取消有一个常被忽略的细节：当 context 被提前取消（不是超时触发，而是手动 cancel）时，内部会调用timer.Stop()把定时器停掉。这个设计本来是好的，但前提是你确实调用了 cancel。如果只WithTimeout不调cancel，定时器会一直挂到 deadline 才触发。在 deadline 很长的场景（比如 24 小时、7 天），每一个泄漏的 context 都对应一个长期挂着的定时器，压力比普通cancelCtx的泄漏大得多。这点放到第 4 节展开。
3. 业务代码里怎么用才顺手
3.1 标准的取消姿势：defer cancel 与 select 多路监听
最基础也最标准的用法，是WithCancel加defer cancel()：
ctx, cancel := context.WithCancel(context.Background()) defer cancel() go func() { select { case <-ctx.Done(): // 收到取消信号，清理资源退出 return case result := <-someCh: // 正常处理结果 handle(result) } }()你记着一点：创建 context 的函数，必须负责调用 cancel。这个原则在任何场景都成立。defer cancel()写在创建紧跟着的下一行，是防御性编程的肌肉记忆——哪怕后续逻辑全乱了，context 的清理也能走到。
select多路监听是配合取消机制最常用的模式。凡是可能阻塞的操作，基本都可以套一层select加上ctx.Done()分支，这样阻塞操作就拥有了"可中断"能力。比如自己封装 RPC 调用、查 channel、等文件事件，都可以这么搞。
3.2 跨层透传：gin、gorm、grpc 里的实际衔接
Context 取消机制最大的价值，体现在跨层透传。拿一个标准的 gin + gorm 项目举例，链路是这样串起来的：
gin 的 handler 里，c.Request.Context()拿到的是请求上下文。客户端断开连接时，这个 ctx 会被自动取消。如果你的下游调用都沿着这个 ctx 传下去，整条链路上的工作就能被及时打断。
func GetUser(c *gin.Context) { ctx := c.Request.Context() var user User // 把请求 ctx 传给 gorm，查询会监听取消信号 if err := db.WithContext(ctx).Where("id = ?", c.Param("id")).First(&user).Error; err != nil { if errors.Is(ctx.Err(), context.Canceled) { // 客户端已断开，不要继续处理 return } c.JSON(500, gin.H{"error": err.Error()}) return } c.JSON(200, user) }db.WithContext(ctx)返回一个绑定了 ctx 的*gorm.DB会话，后续查询都监听这个 ctx。底层数据库驱动在 ctx 被取消时，会尝试终止正在执行的查询，比如 MySQL 驱动会主动中断查询或关闭连接。这就是为什么合理设置 ctx 超时对防止慢查询堆积有立竿见影的效果。
gRPC 那边同理。客户端调用时传入的 ctx 控制整个 RPC 的生命周期：
ctx, cancel := context.WithTimeout(rpcCtx, 2*time.Second) defer cancel() resp, err := client.GetUser(ctx, &pb.UserRequest{Id: id}) if errors.Is(err, status.DeadlineExceeded) { // 处理超时 }这里有个容易忽略的坑：gin 的c（*gin.Context）本身也实现了context.Context接口，但它跟c.Request.Context()不是一回事。c.Request.Context()的生命周期跟随客户端连接，断开即取消；而c的生命周期是整个过程，handler 退出前它都"活着"。标准做法是传给下游用c.Request.Context()。
3.3 errgroup：并发子任务一个失败全部取消
golang.org/x/sync/errgroup是官方扩展里处理并发取消的利器，实现原理就是一个WithCancel。
g, ctx := errgroup.WithContext(ctx) // 三个子任务共享同一个 ctx g.Go(func() error { return fetchUser(ctx, id) }) g.Go(func() error { return fetchOrders(ctx, id) }) g.Go(func() error { return fetchStock(ctx, id) }) if err := g.Wait(); err != nil { // 任何一个任务返回错误，其他任务都会被取消 return err }errgroup.WithContext返回的 ctx，会在任意一个g.Go任务返回非 nil error 时被取消。这样"一个失败，其余兄弟任务全部收工"的语义，一句话就实现了。不用自己手写 cancel 的协调逻辑，也不用担心 channel 关闭的竞态。
我项目里凡是遇到"并发拉取多个数据源，有一个失败就整体失败"的场景，无脑用 errgroup。它还有一个隐藏福利：g.Wait()会等所有 goroutine 结束，配合 ctx 取消信号，能保证没有 goroutine 在 errgroup 返回后还偷偷跑着。
4. 取消传播最常见的坑与排查实录
4.1 只 WithTimeout 不调 cancel，定时器全在裸奔
这是我在实际项目里遇到最多的问题，没有之一。很多刚写 Go 的同事写出来的代码长这样：
ctx, _ := context.WithTimeout(parent, 30*time.Second) resp, err := doSomething(ctx)第二个返回值cancel直接丢了。表面看没啥问题：反正 30 秒后自动超时，不调 cancel 也能触发。但结合前面的源码分析你就知道，cancel 不调用，timer.Stop()就不会执行。WithTimeout创建的定时器在 context 生命周期结束前，会一直挂在 timer 堆里。
什么场景会出事？高并发的接口，每个请求都WithTimeout但都丢了 cancel。请求结束（提前返回、panic、异常分支）后，定时器依然挂着，要等完整超时时间才触发。如果超时时间是 30 秒，那么在高峰期，系统里可能同时挂着几万个"僵尸定时器"，内存和 CPU 都在被白白消耗。
排查过一次很隐蔽的线上问题：服务内存曲线每隔一段时间就出现一次阶梯式上升，pprof 查 heap 发现大量time.Timer对象。最后定位到就是某个中间件里丢了 cancel。修复方式极其简单——把_改成defer cancel()：
ctx, cancel := context.WithTimeout(parent, 30*time.Second) defer cancel() resp, err := doSomething(ctx)就这么一行，内存曲线直接平了。从那以后，我见到context.WithTimeout都会下意识看有没有defer cancel()，这已经是条件反射了。
4.2 取消链路断裂：谁吞掉了 context
另一个高频坑是取消信号在某个分叉口断了。典型表现是：上游明明已经超时返回了，下游数据库/Redis 的请求还在继续跑。
我排查过的一个案例：一个导出接口，handler 里把请求 ctx 传给了 service 层，service 层起了三个 goroutine 分别查数据、生成文件、上传 OSS。问题出在查数据那个 goroutine——它内部调了一个同事写的公共函数，公共函数签名里没有 ctx 参数，于是在函数内部自己搞了个context.Background()去查库。
func queryUserData(userID int64) ([]Order, error) { // 这里用了 Background，请求 ctx 的取消信号根本传不进来 ctx := context.Background() return db.WithContext(ctx).Where(...).Find(...) }这就是典型的链路断裂。请求超时后，上层 goroutine 都退了，但查库操作还闷头跑着。大量慢查询堆积在数据库上，拖垮了 DB，又引起雪崩。
怎么规避？两条经验：
- 函数签名里必须带 ctx。凡是可能阻塞、可能发起 IO 的函数，第一个参数都应该是
ctx context.Context。如果看到一个函数的参数里没有 ctx，它就大概率是取消链路上的断点。 - 禁止在库函数里偷偷用 context.Background() 或 context.TODO()。这两个是给入口用的，比如
main函数、初始化逻辑。业务链路上应该用传入的 ctx，不要自己另起炉灶。
另外，新起的 goroutine 不会自动继承父 goroutine 的 context，必须手动传。很多人写go func() { doSomething(ctx) }()里忘了把外层的 ctx 捕获进去，或者干脆在 goroutine 里又造了一个Background()，取消信号到这里就断头了。这也是检查代码时要重点盯的地方。
4.3 用 pprof 定位 goroutine 堆积
当你不确定 goroutine 是不是泄漏了，别猜，直接看证据。标准的排查姿势是加 pprof 端点，或者线上直接暴露 debug 端口：
import _ "net/http/pprof" go func() { http.ListenAndServe(":6060", nil) }()然后抓 goroutine profile：
go tool pprof http://localhost:6060/debug/pprof/goroutine进入 pprof 交互界面后，输入top看 goroutine 最多的地方，输入web可以图形化查看调用栈。排查重点：看 goroutine 卡在哪个等待点上。如果大量 goroutine 都阻塞在chan receive上，且调用栈里能看出一条等一条的链，那基本就是取消信号没传到某个环节。
压测时可以用go test配合runtime.NumGoroutine()做断言，简单粗暴：
func TestNoGoroutineLeak(t *testing.T) { before := runtime.NumGoroutine() for i := 0; i < 100; i++ { handleRequest(context.Background()) } time.Sleep(100 * time.Millisecond) after := runtime.NumGoroutine() if after > before+10 { t.Fatalf("goroutine leaked: before=%d after=%d", before, after) } }这个测试不能证明没有泄漏，但能快速暴露明显的问题。真到了复杂场景，还得靠 pprof 对比压测前后两次 goroutine profile 的差异。
关于 WithValue 还有一个提醒：文档明确说 context 里放的值应该是请求级数据，比如 trace id、用户 id、鉴权 token，不要放不相关的对象。WithValue的查找是向上递归的，虽然一般不会成为性能瓶颈，但每层WithValue都是一次 O(depth) 的查找，滥用会让代码变得难维护。另外 key 类型要自定义，不要用 string 裸奔，不然不同包之间容易撞 key。至于"把 context 存在 struct 字段里"这种操作，官方态度很明确——不要存 context，要传 context，因为它代表的是调用链上的瞬时状态，不是对象的属性。
5. 几个容易被忽略的小知识点
关于取消传播，还有几个边角料值得记一下：
第一，context.Canceled和context.DeadlineExceeded是两个不同的哨兵错误。判断是否超时不要用err == context.DeadlineExceeded硬比，最好用errors.Is(err, context.DeadlineExceeded)，因为很多库会给错误套一层包装。
第二，父 context 的Err()在取消后返回什么，子 context 的Err()就返回什么。所以如果你在一个子 context 上看到DeadlineExceeded，不一定代表是它自己超时，也可能是父节点超时把它带着一起取消了。排查时要顺着链路往上看。
第三，context.Background()和context.TODO()都是不可取消的，区别只是语义：Background 表示"这里就是根"，TODO 表示"我还没想好传什么，先占个位"。很多人以为 TODO 会自动继承什么，其实不会，它就是一个不会被取消的空壳。
第四，Done()返回 nil 的 context（比如 Background、TODO），在select里会永久阻塞。所以如果你是写库的，想给调用方提供"支持取消的阻塞等待"，记得先把ctx.Done()是否为 nil 判断一下，否则调用方传个 Background 进来你的 select 就卡死了。
第五，想在 context 取消时自动关闭一些资源，可以用context.AfterFunc(ctx, f)——这是 Go 1.21 加的新函数，会在 ctx 取消时异步执行 f。注意它是"并发"触发的，多个 AfterFunc 的执行顺序不保证，别在里面写有依赖关系的逻辑。
第六，context的实现在标准库里还有valueCtx，它只负责 Value 的查找，不参与取消。WithValue每次都是包一层valueCtx，链越长，取一次值要走的节点越多。所以别往 context 里塞一堆东西，宁可多写几个参数。
收个尾：我的一点个人习惯
写了几年 Go，我对 context 的态度可以浓缩成一句话：每个 goroutine 的出生，都要配一个明确的死法。创建 goroutine 之前先问自己三个问题：它怎么退出？退出条件是什么？如果等不到结果，谁能通知它？
我的习惯是，函数签名里能带 ctx 就带 ctx，新起 goroutine 时先把 ctx 传进去，defer cancel()紧跟创建语句。这套规矩看起来繁琐，但真的能避免一大半线上问题。还有一个实用小技巧：在关键链路的日志里打上 ctx 的 deadline 和耗时，排查超时相关问题时，一眼就能看出是哪一段吞掉了时间。
最后再分享一个小经验：别迷信框架帮你传 ctx。gin、gorm、grpc 这些框架只是把 ctx 的传递路径修好了，真正决定取消信号能不能覆盖整条链路的，还是你自己在业务代码里有没有一路把 ctx 传到底。context 这玩意学起来不难，难的是把它当成一种习惯，融到每次写并发代码的肌肉记忆里。希望这篇拆解能帮你把这块短板补上。
