用户在网页上点击了 “取消查询”,或者某个接口请求超过 3 秒还没有响应时,主程序就应该及时通知后台正在运行的子协程停下来,避免白白消耗系统资源。
sync.WaitGroup 主要用于被动等待子协程干完活,而想要像握着 “总遥控器” 一样从外部主动控制子协程何时退出,我们就需要使用标准库提供的 context(上下文)包。它专门用于在多个协程或函数调用链之间传递取消信号、超时时间以及请求数据。
使用 WithCancel() 取消协程
在 Go 语言中,上下文变量名通常简写为 ctx。要使用上下文控制,我们需要先调用 context.Background() 创建一个空的 “根上下文”,作为后续派生的起点。
拿到根上下文之后,我们就可以调用 context.WithCancel() 创建一个可取消的上下文。主协程手里握着取消函数 cancel(),一旦调用 cancel(),所有持有同一个 ctx 的子协程都会通过 <-ctx.Done() 收到停止信号,如下图所示。

语法:
// 创建可取消的上下文
ctx, cancel := context.WithCancel(context.Background())
// 子协程监听停止信号
<-ctx.Done()
// 主协程发出停止信号
cancel()说明:
context.WithCancel() 接收一个父级上下文作为参数,并返回两个结果:
- ctx:上下文对象,用于传递给子协程或子函数。子协程可以在循环中配合 select 语句监听
case <-ctx.Done():分支,判断外部是否发出了取消信号。 - cancel:取消函数。当外部需要让子协程停止工作时,我们直接调用
cancel()即可。调用后,ctx.Done()只读通道会被自动关闭,所有监听该通道的子协程都会在同一时刻收到退出信号。
示例 1:同时取消多个子协程
package main
import (
"context"
"fmt"
"sync"
"time"
)
func monitor(ctx context.Context, id int, wg *sync.WaitGroup) {
defer wg.Done()
ticker := time.NewTicker(80 * time.Millisecond)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
fmt.Printf("监控任务 %d:收到停止信号,退出运行\n", id)
return
case <-ticker.C:
fmt.Printf("监控任务 %d:正在巡检系统状态...\n", id)
}
}
}
func main() {
ctx, cancel := context.WithCancel(context.Background())
var wg sync.WaitGroup
wg.Add(2)
go monitor(ctx, 1, &wg)
go monitor(ctx, 2, &wg)
// 运行 200 毫秒后发出取消信号
time.Sleep(200 * time.Millisecond)
fmt.Println("主协程:发出取消信号")
cancel()
wg.Wait()
}运行结果如下。
监控任务 1:正在巡检系统状态...
监控任务 2:正在巡检系统状态...
监控任务 1:正在巡检系统状态...
监控任务 2:正在巡检系统状态...
主协程:发出取消信号
监控任务 2:收到停止信号,退出运行
监控任务 1:收到停止信号,退出运行分析:
在这个例子中,我们把同一个 ctx 同时传给了监控任务 1 和监控任务 2,并配合周期性定时器 time.NewTicker() 每隔 80 毫秒执行一次巡检。在主协程调用 cancel() 之前,ctx.Done() 通道里没有信号,因此两个子协程会按定时器节奏稳定运行。
等到 200 毫秒后,主协程调用了一次 cancel(),内部就会自动关闭 ctx.Done() 通道。前面学习关闭通道时我们讲过,从已关闭的通道读取数据不会阻塞,因此两个子协程的 case <-ctx.Done(): 分支会在同一时刻立刻触发并退出。
相比普通通道每发一次数据只能被一个协程取走,context 这种 “一次取消、同时通知所有子协程” 的广播方式方便不少。最后我们在主协程末尾调用 wg.Wait(),等待两个子协程彻底清理完毕再结束程序。
提示:
- ctx 放在第 1 个参数位置:在 Go 语言的编码规范中,如果函数需要接收
context.Context参数,我们通常将它放在第 1 个参数的位置,且变量名统一命名为ctx。 - 不要把 ctx 存进结构体字段:上下文应该沿着函数调用链显式传递,不要把它保存为某个结构体的长期字段;如果暂时没有上下文可传,也不要传入
nil,而应传入context.Background()或context.TODO()。
使用 WithTimeout() 控制超时
除了手动调用 cancel() 取消任务之外,在实际项目中我们更常做的是给某个耗时操作设定一个 “最长时间限制”,比如限制某次数据库查询最多不超过 150 毫秒。一旦超过这个时间还没干完,就自动发出取消信号。
想要实现自动超时控制,我们可以使用 context.WithTimeout() 函数。它相当于在 WithCancel() 内部自动绑定了一个倒计时定时器,时间一到就会自动关闭 ctx.Done() 通道。
语法:
ctx, cancel := context.WithTimeout(父级上下文, 超时时长)
defer cancel()说明:
context.WithTimeout() 的第 1 个参数是父级上下文,第 2 个参数是允许的最大耗时。拿到返回的 cancel 函数后,我们应该配合 defer 语句及时释放资源。当上下文被取消或超时后,还可以调用 ctx.Err() 方法查看具体的停止原因。
示例 2:超时自动终止慢任务
package main
import (
"context"
"fmt"
"sync"
"time"
)
func slowQuery(ctx context.Context, wg *sync.WaitGroup) {
defer wg.Done()
fmt.Println("子协程:开始执行查询任务...")
select {
case <-time.After(500 * time.Millisecond):
fmt.Println("子协程:查询任务顺利完成")
case <-ctx.Done():
fmt.Printf("子协程:查询超时终止,原因:%v\n", ctx.Err())
}
}
func main() {
// 创建限时 150 毫秒的上下文
root := context.Background()
timeout := 150 * time.Millisecond
ctx, cancel := context.WithTimeout(root, timeout)
defer cancel() // 退出前释放上下文资源
var wg sync.WaitGroup
wg.Add(1)
go slowQuery(ctx, &wg)
wg.Wait()
}运行结果如下。
子协程:开始执行查询任务...
子协程:查询超时终止,原因:context deadline exceeded分析:
上面代码中,我们先通过 context.WithTimeout() 创建了一个限时 150 毫秒的上下文 ctx,再将它传给 slowQuery() 子协程。由于模拟的慢查询需要 500 毫秒,因此在满 150 毫秒时,ctx.Done() 通道会自动关闭,触发第 2 个分支提前退出。
此时调用 ctx.Err() 会返回 context deadline exceeded,意思是已超出上下文的截止时间。如果是像示例 1 那样主动调用 cancel() 取消的,ctx.Err() 返回的则是 context canceled,表示上下文已被手动取消。
这里小伙伴们要搞清楚一点:WithTimeout() 并不会强行终止正在运行的子协程,它只是按时发出取消信号。子协程内部必须主动监听 <-ctx.Done()(或者把 ctx 继续传给支持超时的数据库、网络接口),才能真正响应超时并退出。
上下文还有一个非常实用的特点:支持像树枝一样层层向下派生。如果我们在父上下文 parentCtx 的基础上,再派生出子上下文 childCtx 交给下级任务,会发生什么呢?下面我们通过一个例子来看看。
示例 3:父子上下文的级联取消
package main
import (
"context"
"fmt"
"sync"
"time"
)
func subTask(ctx context.Context, name string, wg *sync.WaitGroup) {
defer wg.Done()
<-ctx.Done() // 等待取消信号
fmt.Printf("%s:收到信号,退出(原因:%v)\n", name, ctx.Err())
}
func main() {
// 父上下文限时 150 毫秒
root := context.Background()
limit := 150 * time.Millisecond
parentCtx, parentCancel := context.WithTimeout(root, limit)
defer parentCancel()
// 基于父上下文派生子上下文
childCtx, childCancel := context.WithCancel(parentCtx)
defer childCancel()
var wg sync.WaitGroup
wg.Add(2)
go subTask(parentCtx, "父级任务", &wg)
go subTask(childCtx, "子级任务", &wg)
wg.Wait()
}运行结果如下。
父级任务:收到信号,退出(原因:context deadline exceeded)
子级任务:收到信号,退出(原因:context deadline exceeded)分析:
从运行结果可以看出,虽然我们并没有手动调用 childCancel(),但当 150 毫秒一到、parentCtx 触发超时时,子级任务也跟着退出了。这是因为 childCtx 是以 parentCtx 为父级派生出来的,取消信号会自动沿着这棵上下文树向下传递,把 childCtx 一并取消掉。
反过来,取消信号只会 “自上而下” 传递:如果我们提前调用了 childCancel(),只会停止监听 childCtx 的子级任务,并不会反向影响到父级任务。
此外,context 包还提供了一个 context.WithDeadline() 函数,用来按具体的时间点控制超时。在日常开发中,我们优先掌握按时长计时的 WithTimeout() 就可以了。
注意: 调用 WithTimeout() 或 WithCancel() 拿到返回的 cancel 函数后,哪怕子任务在超时前就已经提前完成了,小伙伴们也应该在下一行紧接着写上 defer cancel()。这样可以确保函数退出时及时释放内部定时器和上下文资源,避免资源泄漏。
使用 WithValue() 传递数据
除了控制协程取消与超时,context 包还提供了 context.WithValue() 函数,用来在函数调用链中顺带传递少量与当前请求绑定的键值对数据,比如请求的追踪编号或当前登录的用户 ID。这一部分在日常业务代码中用得相对较少,小伙伴们简单了解一下即可。
语法:
// 将键值对存入新上下文中
ctx := context.WithValue(父级上下文, 键, 值)
// 从上下文中按键取值
val := ctx.Value(键)说明:
context.WithValue() 会基于父级上下文生成一个新的上下文对象,并在里面存入一组键值对。后续在子函数中调用 ctx.Value(键) 时,会返回 any 类型的值;如果指定的键不存在,则返回 nil。
示例 4:跨函数传递请求编号
package main
import (
"context"
"fmt"
)
type traceKey string
const traceIDKey traceKey = "trace_id" // 定义专属类型的常量键
func handleRequest(ctx context.Context) {
val := ctx.Value(traceIDKey)
if traceID, ok := val.(string); ok {
fmt.Printf("当前请求追踪编号:%s\n", traceID)
}
}
func main() {
root := context.Background()
ctx := context.WithValue(root, traceIDKey, "REQ-1001")
handleRequest(ctx)
}运行结果如下。
当前请求追踪编号:REQ-1001分析:
context.WithValue() 基于根上下文生成了一个携带键值对的新 ctx。将 ctx 传给 handleRequest() 函数后,我们先通过 ctx.Value(traceIDKey) 取出对应的值,再使用双返回值类型断言安全还原为 string 字符串打印出来。
可能有些小伙伴会问:“为什么开头要专门定义 traceKey 这个新类型,而不直接用普通的 string 类型当键呢?”
这是因为在大型项目中,同一个 ctx 通常会流经多个不同的包。如果两个包都直接拿普通的 string 类型 "trace_id" 往 ctx 里存数据,后面的值就会把前面的值覆盖掉。定义包内专属的自定义类型常量作为键,就能避免不同包之间的键名冲突。
另外小伙伴们要注意,WithValue() 只适合传递请求追踪号、权限令牌这类跨层级的辅助信息,千万不要为了图省事把普通函数的业务参数全都塞进 ctx 里传递,否则会让代码变得难以阅读和维护。
常见问题
1. 创建根上下文时,context.Background() 和 context.TODO() 有什么区别?
在底层实现上,这两个函数返回的都是一个空的、永不取消的根上下文,功能上没有任何区别。
它们主要是使用场景上的区分:context.Background() 是最常用的标准起点,一般用在 main() 函数或请求处理的顶层入口。
而 context.TODO() 相当于一个临时的 “待定占位符”,仅在改造旧代码、暂时还不确定应该传入哪个上下文时过渡使用。平时编写新代码时,我们直接使用 context.Background() 就可以了。
