一个典型的线上故障，往往就是理解Go Context最好的教材。我之前维护过一个 Go 写的 HTTP 服务，某天凌晨收到告警：goroutine 数量从几千一路涨到几十万，内存眼看着就要爆。拉 goroutine 栈出来一看，大量协程整整齐齐地阻塞在一个第三方 SDK 的网络调用上，而它们拿到的Context全部来自context.Background()。请求早就在 handler 返回时结束了，可后台协程还在傻等响应，没人告诉它们“该停了”。那次事故逼着我彻底把context的传播与取消机制搞透：它不只是一个函数参数，而是你整个程序的退出信号高速公路。这篇文章不讲概念堆砌，只讲我读完源码、翻完 pprof 之后总结出来的核心认知，以及后来在好几个项目里反复验证过的用法和坑。
先说清楚边界：你在搜索引擎里敲context，会看到一堆 LLM 的 context window、Docker 构建上下文、甚至某些模型工具报 “context length exceeded”，那都不是本文要聊的东西。本文只聊 Go 标准库里的context包，以及它如何完成“控制信号在调用链中的传播与取消”。文章适合已经能写 Go 并发代码、但总觉得context是个玄学的人，也适合正在为 goroutine 泄漏和超时失控苦恼的人。
1. 一次线上 goroutine 泄漏，逼我重新认识 context
1.1 泄漏现场还原
那个接口做的事情不复杂：接收到请求后，把请求数据丢到一个任务队列里异步处理，然后立刻返回成功。因为异步任务里调用了外部用户画像服务，响应时间不太可控，所以代码里直接go func()开协程，在协程里用 HTTP client 去调外部服务。
func handler(r *http.Request) { task := parseTask(r) go func() { result, err := fetchFromProfileService(task) if err != nil { log.Errorf("fetch profile failed: %v", err) return } saveResult(task.ID, result) }() writeAccepted(w) }这段代码初看没啥问题：接口不阻塞，异步逻辑独立运行。但它没有做任何生命周期管理。客户端在发起请求后 300ms 就断开了，handler 已经返回，可后台协程并不知情。外部用户画像服务那会儿恰好大量超时，TCP 连接迟迟得不到响应，协程就全部挂在http.Client.Do上。
我们用 pprof 抓到 goroutine dump 时，看到的栈几乎都是：
net/http.(*persistConn).roundTrip net/http.(*Client).Do github.com/xxx/profile.SDK.Fetch main.asyncProcessProfile每一行都没有context.Done相关的 select，说明这里没有任何取消信号能穿透进去。这不是一个偶发错误，而是设计上就没有给异步链路安排“退出遥控器”。
1.2 为什么传统做法救不了场
你可能想，不就是一个“让 goroutine 退出的通知机制”吗？用 channel 不也能实现？确实，理论上可以自己维护一个stopCh chan struct{}，然后每个 goroutine 都 select 它。但问题在于：一旦调用链变深，这个stopCh要作为参数层层传递，每个函数的签名都得带上它，所有调用的分支都要判断它。更关键的是，它不能同时携带超时时间、截止时间、呼叫来源等元数据，你很难让“客户端断连导致取消”和“上游超时取消”这两类事件统一成同一种语义。
context包的价值恰恰是把这些信号统一成一个标准对象，让标准库、第三方库、你的业务代码共用同一套“取消语言”。http.Request自带Context()，database/sql支持QueryContext，grpc 天然依赖 context，可以说 Go 生态早就把生命周期的传递约定成了“第一个参数必须是Context”。如果你绕过它自己发明一套 channel，等于把整个生态的协作能力挡在门外。
那次事故之后，我给团队定的第一条铁律就是：只要有 goroutine 启动，就必须先问一句：这个协程的生命周期归谁管，退出信号顺着哪条链路传过去。大部分 goroutine 泄漏，都是因为说不出这两句话。
2. Context 的四件套：接口设计背后的工程意图
2.1 Context 接口：只有四个方法，却卡住了整个生命周期
type Context interface { Deadline() (deadline time.Time, ok bool) Done() <-chan struct{} Err() error Value(key any) any }这个接口小得不像一个重量级抽象，但四个方法刚好覆盖了控制信号传播所需要的全部能力：
Deadline()返回这个 context 被设置的截止时间，ok为 false 表示未设截止时间。它主要用于某些 io 库去计算剩余时间，决定是自己设置 socket deadline 还是直接放弃。
Done()是取消信号的核心。它返回一个空结构体 channel，注意方向是<-chan struct{}，只有读权限。这个设计很关键：下游只能感知“有没有关闭”，不能主动“关闭”，关闭动作只能由创建这个 context 的cancel函数触发。一旦 Done 被关闭，所有 select 到这个 channel 的 goroutine 都会立即唤醒，实现广播式通知。
Err()返回取消原因。如果 context 还没结束，返回 nil；如果被取消，返回context.Canceled；如果超时或到了截止时间，返回context.DeadlineExceeded。这个返回值最重要的用途是让调用方区分“我主动取消”和“对方超时”，从而决定错误日志的级别或是否需要重试。
Value(key any) any负责跨 API 边界携带进程内请求元数据，比如 traceID、requestID。注意它的 key 和 value 都用空接口，后面我会专门讲它的滥用问题。
为什么 Context 接口本身不提供Cancel()方法？因为取消是创建方的权力，传递给下游的是只读视图。如果下游也能取消，那整个链路的取消点就不可控，谁都能提取消信号，排查问题会变成灾难。正是这种“上游管下游，不许下游管上游”的单向约束，让退出信号能沿着固定的方向传播。
2.2 标准实现与派生函数：cancelCtx、timerCtx、valueCtx 的分工
我们平时不会直接实现 Context 接口，而是用标准库提供的四个实现：
emptyCtx：本质是一个永不取消、永不超时的空 context，对应context.Background()和context.TODO()。cancelCtx：支持手动取消的核心体，所有WithCancel返回的 context 都是它。timerCtx：在cancelCtx基础上包了一层定时器，到时间自动取消，对应WithTimeout和WithDeadline。valueCtx：只负责存键值对，不参与取消，但它的 Done 和 Deadline 会委托给 parent。
日常开发里，你接触更多的是几个派生函数：
ctx, cancel := context.WithCancel(parent) ctx, cancel := context.WithTimeout(parent, 3 * time.Second) ctx, cancel := context.WithDeadline(parent, deadline) ctx := context.WithValue(parent, key, value)除了WithValue不返回 cancel 函数，其他三个派生函数都要求你必须调用返回的cancel，否则会留下资源隐患。
理解这些实现的分工，有个很实用的价值：看到WithTimeout时，你应该意识到它内部生成了一个timerCtx，这个timerCtx会在到期时自动调用底层cancelCtx.cancel()，并把err标记为DeadlineExceeded。但如果你提前调用了 cancel，它就不再等定时器，立刻取消并标记为Canceled。
3. 取消信号是怎么在父子和兄弟之间传开的
3.1 Done channel 的关闭：广播而非逐一通知
Go 里最经典的广播机制，就是关闭一个 channel：关闭动作会让所有正在等待读这个 channel 的 goroutine 立刻收到零值。Done()返回的<-chan struct{}就利用了这一点。
你可以在 N 个 goroutine 里都 select<-ctx.Done()，当 cancel 被调用时，它们不是排队挨个接收，而是同时被唤醒。这是 channel 关闭的特性和普通发送数据的本质区别。普通发送只能被一个接收者取走，而“关闭”能被所有接收者感知。控制信号的传播，需要的正是这种一对多的广播能力。
这也解释了为什么 context 适合做退出信号而不是做数据传输：它只关心“这次生命周期是否还在继续”，不需要传递具体数据。具体数据的传递应该走参数、返回值、业务 channel，而不是塞进 context。
3.2 父节点取消时，整个子树都在干什么
每次调用WithCancel(parent)时，标准库都会创建一个cancelCtx，并把新节点挂到 parent 的 children map 上。这样所有派生 context 会形成一棵树。
当父节点的 cancel 被调用时，内部的cancel方法会做三件事：
- 把自身的 err 字段设为
Canceled或DeadlineExceeded。 - 关闭自己的 done channel，唤醒所有等待者。
- 遍历自己的 children，挨个调用它们的 cancel 方法。
也就是说，取消是深度递归向下传播的：父节点取消，所有子孙节点跟着取消。这也意味着，如果你在请求入口派生了一个根 context，那么由它派生的所有超时 context、值 context、数据层用的 context，都会在请求结束时被一并取消。
有一个细节值得注意：WithValue产生的valueCtx并没有自己的 children 和 cancel 方法，它只是封装在原来的 cancelCtx 外一层，通过读取 parent 的 Done 来感知取消。所以即使你只调用了WithValue(parent, k, v)而没有返回 cancel 函数，取消信号依然能沿着 parent 穿透到 valueCtx。而在树形结构里，兄弟节点之间互不影响：一个子 context 被取消，不会取消父节点，也不会影响其他兄弟节点。这也是为什么我们可以放心地在同一个父 context 下派生多个工作协程，取消其中一个最坏只会影响它自己，除非你明确把父节点一起 cancel。
3.3 cancel 函数调用时机与幂等性：为什么 defer cancel 是标配
很多初学 Go 的人不理解，为什么每次WithCancel都要立刻defer cancel()，明明可能根本用不到取消。其实cancel不只是发送取消信号，它还承担资源清理职责：
- 把当前 cancelCtx 从父节点的 children map 中摘除，让父节点不再持有引用。
- 如果是 timerCtx，会停止内部定时器，避免定时器在 context 已经结束后仍然存活到到期时间。
- 关闭 done channel，唤醒所有等待者。
如果你创建了WithTimeout却从不调用 cancel，定时器会一直等到超时时间才触发，而不是在调用结束后立刻销毁。设想一个每秒钟创建几百个 10 秒超时 context 的高频接口，如果都漏 cancel，这些 timer 会堆积近一整个超时窗口，内存和 goroutine 压力都不小。
cancel函数是幂等的，内部用sync.Once保证多次调用只执行一次清理。所以放心的做法是：创建完 ctx 之后，立刻defer cancel()，这样哪怕后续逻辑分叉再多，函数退出时都会自动清理。唯一要留意的是，如果你把 ctx 返回给调用方、或者要在一个更外层的生命周期里取消，那就不要让内部 defer cancel，因为那样会过早终止整个链路。这种场景更合理的做法是让调用方去管理 cancel。
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) defer cancel() result, err := doSomething(ctx) // 无论 doSomething 是否执行到自然结束，defer 都会兜底4. 生产环境的几个典型用法，我建议直接背下来
4.1 HTTP 服务场景：请求生命周期贯穿中间件、控制器、数据层
Go 的net/http在http.Request里直接挂了一个 context，r.Context()的取消时机由底层连接管理决定：客户端断开连接、HTTP/2 请求被取消、或服务端主动超时，都会让这个 context 失效。你写 handler 时应该下意识地把它传给下游所有函数。
func handler(w http.ResponseWriter, r *http.Request) { ctx := r.Context() // 不要用 context.Background() 来替代 orders, err := orderService.GetList(ctx, userID) if err != nil { writeError(w, err) return } writeJSON(w, orders) }在 service 和 repository 层，所有方法签名都必须把 ctx 作为第一个参数。这样做的最大收益是：一旦客户端断开，整个数据库查询、外部 HTTP 调用、或者消息队列操作都能收到取消信号。很多框架内置的连接池也会感知 ctx.Done，从而及时放弃慢请求，把连接归还给池子。
我刚入行时有个误解：以为 handler 结束就结束了，底层 goroutine 自然会随着请求结束而被回收。实际上只有当你把 ctx 一路传下去，并让每个阻塞点都 select Done，回收才可能发生。
4.2 超时管控：withTimeout 与 withDeadline 的取舍
WithTimeout和WithDeadline的区别，一个是相对时长，一个是绝对时刻。实践中我遵循一个判断标准：
- 如果你要限制“整个函数链路最多跑多久”，用
WithTimeout，因为它好读、好写，心智负担小。 - 如果你要保证“在某个时间点前必须完成”，比如一批任务必须在 10:00 前结束，或者你从外部系统拿到一个绝对截止时间，用
WithDeadline。
光设置 context 超时不一定够。很多底层 IO 库会利用 context 的Deadline()去设置对应的 socket 读写超时，但这依赖具体实现。如果你自己写 HTTP client 调用，建议同时给http.Client设置Timeout，并且给每次请求设置 context，二者互为兜底。context 负责链路内所有分支的统一截止，client.Timeout 负责最外层的兜底，防止某个环节忘记监听 context。
ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second) defer cancel() req, _ := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) resp, err := client.Do(req) if errors.Is(err, context.DeadlineExceeded) { // 记录超时，不要笼统不区分错误 }超时时长设置是门学问。太短会导致正常慢请求被误杀，太长体会不到熔断的价值。我的习惯是先看外部服务的 P99 响应时间，再设置成比 P99 稍大一些的值，留出网络抖动余地；再在告警里对大量 DeadlineExceeded 保持敏感，因为那往往意味着下游服务已经劣化，而不仅仅是随机抖动。
4.3 跨 goroutine 编排：select + Done 的正确姿势
在需要同时管理多个 goroutine 时，最标准的方式是为每个子任务派生自己的子 context，再用一个 select 统一等待。
func runWorker(ctx context.Context, tasks <-chan Task) { for { select { case <-ctx.Done(): log.Info("worker exiting: %v", ctx.Err()) return case task, ok := <-tasks: if !ok { return } if err := process(task); err != nil { log.Error("process task failed: %v", err) } } } }这里有个细节：select 要优先监听ctx.Done()，并且把任务 channel 的接收放在后面。如果 ctx 已经取消，哪怕任务 channel 里还有数据，<-ctx.Done()也会立刻返回，从而让 worker 退出。阻塞在发送操作上也是同样的道理，下面是一个给某个并发 goroutine 发任务时的安全写法：
select { case <-ctx.Done(): return ctx.Err() case resultCh <- result: }为什么强调“显式传参”而不是在闭包里捕获 ctx？因为闭包捕获会让 ctx 的可见范围变得模糊，尤其是你在多个 goroutine 里复用同一个闭包时，稍不注意就从共享变量里拿到过期的 ctx。显式传参能保证每个 goroutine 拿到的是创建时的快照，同时也更容易通过静态检查发现问题。
4.4 传值的边界：WithValue 只放请求无关的元数据
WithValue是最容易被滥用的功能。它的官方定位非常明确：携带进程内的请求元数据，比如 trace ID、用户 ID、客户端 IP、本次请求的语言偏好。它不应该用来传递可选参数，更不应该用来传递数据库连接、配置对象、日志器这类全局依赖。
原因至少有两点：
- 隐式依赖很危险。如果下游函数从 ctx 里掏出一个“我正在使用的 service”，阅读代码的人根本猜不到这个函数还有这么重的隐藏依赖，测试时也很难构造。
- 值是只读的，context 设计上不可变，你想塞一个可变对象进去，等于在并发环境里埋雷。
如果要用WithValue，key 必须用自定义类型，不能直接用内置 string 或 int，否则不同包之间 key 容易撞车。惯例是定义一个私有类型，并在暴露给外部的包内做 getter/setter：
type userIDKey struct{} func WithUserID(ctx context.Context, uid int64) context.Context { return context.WithValue(ctx, userIDKey{}, uid) } func UserIDFrom(ctx context.Context) (int64, bool) { uid, ok := ctx.Value(userIDKey{}).(int64) return uid, ok }这样做之后，跨包读取 userID 只能通过UserIDFrom，key 永远不暴露给外部，碰撞概率降到零。
5. 我踩过的坑：Context 滥用现场与根因
5.1 坑一：context.Background() 当万能油
context.Background()是一个永远不会取消的根上下文，它的正确使用场景很有限：程序入口处，例如main、init、命令行初始化；以及一些确确实实不依赖请求生命周期的长驻后台任务。但在实际代码里，它经常被当成“省事默认值”随手用。
我见过最典型的反例，是一个 API 网关内部要调用下游服务，代码为了省去“把上游 ctx 传进来”的麻烦，直接在数据层函数里写context.Background()。结果就是，网关前端已经断连了，下游调用还在继续打；网关开启了限流，但因为每个请求都用同一个 background，限流器内部想用 ctx 区分请求都做不了。
正确做法是：所有函数签名从入口开始就把 ctx 作为第一个参数一路透传。如果函数可能被多种入口调用，允许传 nil 也要避免偷偷用 Background 替代，宁可让调用方显式传context.TODO()，等待后续补链路。
5.2 坑二：WithCancel 派生了却没有 cancel
这里有个容易忽略的代码结构问题：
func fetch(ctx context.Context) ([]Item, error) { ctx, cancel := context.WithTimeout(ctx, time.Second) // 忘了 defer cancel() if someCondition { return nil, nil } return doFetch(ctx) }如果someCondition满足，函数直接提前 return，cancel没有被调用。这个timerCtx会一直等待超时时间到期才能释放自己，如果这种分支调用频率高，就造成了累积的资源浪费。更糟糕的是，如果这个 ctx 被传递到了子 goroutine，子 goroutine 永远不会收到提前取消。
解决方案很简单：在任何WithCancel/WithTimeout/WithDeadline创建之后，立刻写defer cancel()，不要等到确定需要的时候再写。在 code review 里，我一般看到没有紧跟 defer cancel 的派生 ctx，就会直接打回。
好在 Go 的工具链能帮我们做一部分检查：go vet里有 lostcancel 检查器，会提示那些创建了 context 但从未使用 cancel 函数的调用点。不过它只检查“cancel 完全没用到”的情况，如果 cancel 在某个分支里用过但另一个分支漏掉，它查不出来，所以关键还是养成习惯。
5.3 坑三：把 context 塞进结构体
有人为了方便，在定义 service 结构体时塞了一个 ctx 字段，然后所有方法都从字段里取。比如：
type UserService struct { ctx context.Context db *sql.DB } func (s *UserService) GetUser(id int) (*User, error) { // 所有查询都用 s.ctx }这个设计基本等于给并发埋雷。一个 service 实例可能被多个请求共用，但每个请求的 ctx 生命周期都不同。一旦一个请求超时取消，它把 ctx 存进结构体，另一个请求也会读到已取消的 ctx，导致误杀。官方文档原话就是：不要将 Context 存储在结构体类型中，应该显式作为参数传递。
如果你面对的是一个长期运行、不区分请求的后台 job，那也不应该用结构体字段，而是应该把 ctx 显式传入 main loop，再传给每个任务处理函数。清晰的 ctx 作用域，比少写一个参数重要得多。
5.4 坑四：手动判断 err == context.Canceled 还不够
很多库在返回错误时，会用fmt.Errorf("xxx: %w", ctx.Err())包装一下。如果你用err == context.Canceled去判断，永远匹配不上。
正确写法是：
if errors.Is(err, context.Canceled) { // 主动取消 } if errors.Is(err, context.DeadlineExceeded) { // 超时 }errors.Is会顺着错误包装链一层层找目标错误，这已经是 Go 1.13 之后的标准姿势。光记住这一步，就能省掉你排查“为什么 err 值明明看起来是 cancel，判断却走不进”的半小时。
5.5 排查链路：pprof 定位 goroutine 堆积，source 锁定未能退出的 select
最后把我的排查套路分享出来。线上出现 goroutine 泄漏时，常规步骤是：
- 如果服务已经暴露了
net/http/pprof，直接访问/debug/pprof/goroutine?debug=1，能看到当前所有 goroutine 栈和数量统计。注意，这里会瞬间产生一个快照，可能比较大，在高峰期要谨慎。 - 用
go tool pprof http://host:port/debug/pprof/goroutine拉一个 profile 下来，然后top、list查看哪些函数栈堆积最严重。 - 如果栈上出现
chan receive阻塞，或者net.(*conn).Read阻塞，再看这个栈是从哪个 handler 入口进入的。重点看它是否经过了任何select { case <-ctx.Done(): ... }。如果完全没有相关分支，大概率就是 ctx 没有穿透到阻塞点。 - 在代码里搜索这个阻塞函数，顺着调用链往上翻，看最初的 ctx 是来自
r.Context()还是context.Background()。大多数情况下，你会看到某个中间层偷偷用了Background()替代原始 ctx，或者某个WithTimeout少写了一个defer cancel()。
我在实际处理过一次复杂泄漏后，还习惯于在提交前跑一遍go vet ./...，并且把staticcheck的SA4006、SA1015等检查也纳入 CI。虽然它们不能发现所有并发问题，但能拦截掉很多低级误用。
顺带说一句，Docker 构建时报context canceled也是高频问题，但那是 Docker CLI 的构建上下文发送过程被中断，和 Go 的 context 包是两回事。不要把两种排查路径混在一起，否则会越查越乱。
6. 我在实际项目中沉淀下来的三条约定
聊了这么多，最后分享三条我自己写代码时严格执行的约定，它们帮团队减少了大量并发事故。
约定一：谁创建谁取消，defer cancel 必须紧随其后。只要是WithCancel、WithTimeout、WithDeadline创建 ctx，下一行必须写defer cancel()，除非你敢明确说出“这个 cancel 的调用责任在哪个外部代码”。说不清楚就不要说，一律 defer。
约定二：函数签名第一个参数永远放 ctx。不用把 ctx 放进结构体，也不用包一层自定义 Context struct，直接裸传标准库的context.Context。这样任何调用方都能一眼看出这个函数受不受外部生命周期控制。
约定三：用 WithValue 只放跨 API 边界的请求元数据，所有 key 用私有类型封装 getter。一旦发现有人从 ctx 里取 “db” 或 “config”，review 时直接打回重写。让 context 回归它的本来职责：传递控制信号，而不是充当依赖注入容器。
Context 看起来简单，但只有真正把它放到并发链路的每个阻塞点，才能体会它带来的确定性：超时、取消、请求断连，最终都能变成一套统一的退出机制，让该停的协程停得干净利索。希望这些踩坑经验能帮你少走一段弯路。
