Go / 系统课时
用 Context 传播取消与超时
用 Context 传播取消与超时
context.Context 用来把一次操作的取消、截止时间和少量请求级元数据沿调用链向下传递。本课用一条完整调用链说明父子 Context 如何传播信号,以及函数应怎样响应 Done,避免请求已结束而后台工作仍继续占用资源。
学习目标
- 使用
WithCancel、WithTimeout和 deadline 控制一条调用链的生命周期。 - 在阻塞操作中监听
ctx.Done(),并正确处理ctx.Err()。 - 区分取消信息与
Value的职责,避免把 Context 当作通用参数容器。
Context 沿调用链向下传播
通常由请求入口获得或创建根 Context,再把它作为第一个参数传给 service、repository 和其他下游函数。通过 context.WithCancel、context.WithTimeout 或 context.WithDeadline 派生出的子 Context 会继承父级约束。
父 Context 被取消时,所有后代都会收到取消信号;子 Context 自己取消不会反向取消父 Context。若父级 deadline 比子级设置的时间更早,子级也不可能突破父级的更早截止时间。

ctx.Done() 返回一个只读 Channel。取消发生或 deadline 到期时,这个 Channel 会被关闭,因此多个正在等待它的 goroutine 都能立即收到通知。ctx.Err() 则说明退出原因:主动取消通常为 context.Canceled,超过截止时间为 context.DeadlineExceeded。
在阻塞点响应取消
只有把 Context 传下去还不够,耗时操作必须真正观察取消信号。网络库、数据库驱动等支持 Context 的 API 应优先直接接收同一个 ctx;自己编写的等待逻辑则通常在 select 中同时等待业务结果与 ctx.Done()。
下面的程序给一次调用设置 80 毫秒超时,而 repository 模拟 300 毫秒工作。超时会从入口传播到最深层,并由 repository 主动结束等待。
package main
import (
"context"
"fmt"
"time"
)
func repository(ctx context.Context) error {
select {
case <-time.After(300 * time.Millisecond):
return nil
case <-ctx.Done():
// 把取消原因返回给上层,而不是继续占用资源。
return ctx.Err()
}
}
func service(ctx context.Context) error {
return repository(ctx)
}
func handleRequest(ctx context.Context) error {
ctx, cancel := context.WithTimeout(ctx, 80*time.Millisecond)
// 即使 timeout 已经发生,也应调用 cancel 及时释放关联资源。
defer cancel()
return service(ctx)
}
func main() {
err := handleRequest(context.Background())
fmt.Println("request failed:", err)
}预期输出
request failed: context deadline exceeded实际调度时间可能略有差异,但程序不需要等待完整的 300 毫秒工作周期;deadline 到期后,ctx.Done() 被关闭,repository 随即返回 context deadline exceeded。
正确创建和传递 Context
函数通常把 ctx context.Context 放在第一个参数位置,并显式向下传递。不要为了省参数把 Context 隐藏在全局变量中,也不要在普通长生命周期结构体里随意保存请求 Context,否则对象生命周期与请求生命周期容易混在一起。
通过 WithCancel、WithTimeout 或 WithDeadline 得到 cancel 后,应在拥有该派生 Context 的作用域内调用它,常见写法是立即 defer cancel()。这不仅表示主动取消,也让实现及时释放与计时器、子 Context 相关的资源。
context.Background() 适合程序根部、顶层任务或没有上游 Context 的入口;context.TODO() 表示当前代码尚未决定应该接收哪个 Context,适合迁移阶段,但不应长期用它掩盖调用链设计问题。
把 Value 限制在请求级元数据
context.WithValue 适合携带跨 API 边界传播的请求级信息,例如 request ID、trace 信息或认证后得到的最小身份数据。键应使用自定义类型,避免不同包使用相同字符串键而发生冲突。
不要把超时配置、分页大小、业务开关等普通函数参数塞进 Context。它们属于明确的业务输入,应该出现在函数参数或配置结构中。Context 的核心职责仍是控制一次操作的生命周期,而不是替代参数列表。
取消机制只有在下游愿意响应时才真正生效。设计调用链时,应让同一个 ctx 贯穿阻塞边界,并在自定义等待、循环和后台任务中提供退出路径,这样上游请求结束后,CPU、连接和 goroutine 才能及时回收。