context 不是拿来传值的,是拿来传取消的

难度 ★★★★☆ · 前置:Mutex、RWMutex、atomic 到底该用哪个 | 一句话结论:取消顺着树往下走,父节点一按,挂在下面的子孙当场拿到同一个错误值,而传值只是搭在这棵树上顺带的那一半。

我 2023 年 6 月才入行,写 Go 的时间不算长,头半年对 context 的理解就一句话,函数参数里带一个 ctx。真正开始写业务之后,我把它当成了一只可以随便塞东西的背包,配置、可选参数、日志对象都往里放,理由很实在,塞进去就不用改签名,调用方也不必知道底下到底读了什么。单文件里这么写确实舒服,等到调用链上挂了四五个函数,谁读了哪个键、谁根本没传、默认值是从哪儿冒出来的,只能一段段读下去才看得出来。第一次因为这个去查告警,是列表接口的分页全回到了第一页,我从 handler 一路往回翻,翻到最后才确认那个 pageSize 根本没进过 ctx,断言失败走了零值分支,于是所有人都安静地拿到了第一页,谁也没报错。(那天在工位上我想,这跟把钥匙丢进一只没有底的抽屉差不多,真要用的时候才发现根本没放进去。)这篇讲的是我后来才想明白的一件事,context 的重心在取消那一半,传值那一半的边界很窄,越过去之后代码会变得难查,也很难改,我自己踩的坑基本都出在这条线上,所以这篇先讲取消,再讲值到底能落到哪儿。实验的结构不复杂,Background 下面挂一个 WithCancel 得到 reqCtx,reqCtx 下面再挂 WithTimeout 和 WithValue,三段父子,连着根一共五个 ctx。

值挂在一边,期限挂在另一边,取消的权力只在中间那个 reqCtx 手里。

一棵树,五个 ctx,先看输出

骨架大致是这样,值和期限各挂一支,中间的 reqCtx 握着取消的权力,两条支路都从它身上长出去。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
root := context.Background()
reqCtx, cancel := context.WithCancel(root)
defer cancel()

valCtx := context.WithValue(reqCtx, traceKey{}, "trace-abc")
timeoutCtx, timeoutCancel := context.WithTimeout(reqCtx, 50*time.Millisecond)
defer timeoutCancel()

_, ok := timeoutCtx.Deadline()
fmt.Println("timeout deadline set:", ok)
fmt.Println("values:", valCtx.Value(traceKey{}))
fmt.Println("timeout ctx err:", timeoutCtx.Err())
fmt.Println("reqCtx err before cancel:", reqCtx.Err())
cancel()
fmt.Println("reqCtx err after cancel:", reqCtx.Err())
fmt.Println("valCtx err after cancel:", valCtx.Err())

结构就是一棵树。这句话写在纸上是这样,真跑起来打印的时候更明显。

跑一次,我什么统计都没做,就是把几个 ctx 的状态依次打出来。cmd 里 go run main.go,输出原样贴在下面,一行没删。环境写在这里,go1.27.2,windows/amd64,GOMAXPROCS 是 32。

1
2
3
4
5
6
7
8
9
10
values: trace-abc
timeout deadline set: true
timeout ctx err: context deadline exceeded
reqCtx err before cancel: <nil>
reqCtx err after cancel: context canceled
valCtx err after cancel: context canceled
timeoutCtx err: context deadline exceeded
child1 err: context canceled
parent err: context canceled
child of dead parent err: context canceled

这十行里信息量最大的是 reqCtx 前后那两行,cancel 之前 Err 打出来是 nil,cancel 之后立刻变成 context canceled,中间没有第三个状态,也没有一段从 nil 慢慢过渡到错误的窗口,取消是一次到位的。

这五个 ctx 各自能干什么,其实一眼就能列完:

ctx 怎么生的 有自己的期限吗 能被父节点取消吗
root Background() 没有 它是根,没有父节点
reqCtx WithCancel(root) 没有 是根的儿子
valCtx WithValue(reqCtx, …) 没有 能,跟父节点分毫不差
timeoutCtx WithTimeout(reqCtx, 50ms) 有,五十毫秒 能,自己到点也会死

valCtx 是 WithValue 生的,它自己没有期限,也没有取消的能力,可父节点一按,它的 Err 也是 context canceled,跟父节点拿到的那一个分毫不差,说明值节点在取消这件事上也是跟着父节点走的。

timeoutCtx 就不同了,它报的是 context deadline exceeded,说明它是被自己那个五十毫秒的定时器按下去的。我一开始以为这种 ctx 到期会把父节点也一起按下去,毕竟名字里都带着 cancel,后来才明白它只是自己那一支到点,父节点该跑还跑,不是被父节点带走的。最后三行把同一个结论又验了一遍,子节点、父节点,还有那个拿死掉的父节点建出来的子节点,报的全是 context canceled,一个都没漏。

取消只沿着父到子的方向走

树的用处全在取消上。父节点一按,挂在下头的所有节点全被按下去,中间隔了几层都一样,那个节点是 WithCancel 生的还是 WithTimeout 生的也都一样。

context 的取消沿树往下传

取消只往下传,不会往回传。

子 ctx 取消,父 ctx 收不到。

这个方向不是巧合,是建的时候定死的。子节点在被创建出来的那一刻,就把自己登记到了离它最近的那个可取消的祖先前头,父节点 cancel 的时候顺着这份名单挨个关掉,被关掉的子节点再往下关自己那一层,一层一层传到底。

所以父节点取消,所有子孙都跟着取消,反过来子节点取消,只关自己那一支,父节点和兄弟节点一点都不受影响,这个不对称是树这个结构本身就带着的,不是谁额外加了一个判断。

我做的第二个实验就是专门验这一条,用 WithCancel 建一棵子树,父节点 cancel 之后,不管子节点是 WithCancel 生的还是 WithTimeout 生的,全都在下一个瞬间变成 context canceled,没有一个还留着 nil。

单向这件事在写代码的时候会咬人。你给一个请求建了 ctx,下游几个 goroutine 各自再建子 ctx,某个子 ctx 到期了,断掉的只是它自己那一支,父请求还在跑,别的兄弟也还在跑。这是设计意图,不是 bug,可第一次看到的时候我确实以为哪里漏了,还去翻了标准库才放心。

后来评审别人的代码又碰上一次反过来的情形,子 ctx 被取消,父 ctx 明明还在跑,那段代码把这一次取消当成了整个请求的信号,一路把父 ctx 也 defer cancel 掉,等于自己把整棵树从上往下按了一遍。

Done 是 channel,Err 是取消的原因

取消信号本身只有一个载体,就是 channel。Done 把那个 channel 交出来,取消发生的时候它被关掉,close 这个动作本身就是信号,没有第二个地方去查状态。这一点和我最早在别的语言里见到的写法不太一样,那边通常给你一个句柄让你去问它好了没有,Go 这边是它主动告诉你,你只要在读就行。所以我看到有人在循环里一遍遍问 ctx.Err() 判断要不要退出,就知道他大概还没把 Done 当一回事。

用 channel 而不是回调表,好处是它天然能挂进 select。一个 goroutine 在等网络、等锁、等另一个 goroutine 的结果,只要把读 Done 的那个 case 摆在 select 里,取消发生的那一刻它就能醒,不用谁去遍历一张注册表,也不用额外开一个 goroutine 去转一道手。

close 过的 channel 还有个脾气,读它永远不会阻塞,读出来是零值,所以这个 case 一旦变成就绪就会一直就绪,你不会被卡在第二次等待上。我最早写 select 的时候,总爱在 case 里再判一次这个 channel 到底关没关,后来才明白那一层判断是多余的。

Err 走的是另一条路,它不看 channel,直接返回一个早就存好的错误值,取消之前是 nil,取消之后是 context.Canceled 或者 context.DeadlineExceeded,两个值对应两种原因,一个是有人主动按,一个是时间到了,两个都是标准库里现成的变量,拿去比较不用绕弯。

错误一旦定了就不再改。这句话是字面意思,第一次 cancel 之后那个错误值就固定下来了,后面调多少次 Err 都是同一个,再调一次 cancel 也不会把它换成别的,更不会变回 nil。所以拿 Err 做分支判断是安全的,它不会在你判断到一半的时候被换掉,写重试逻辑的时候这一点挺关键。

WithTimeout 就是 WithDeadline 加个定时器

这两个函数在标准库里的关系,比名字看上去要近。WithTimeout 拿到一个时长之后,先算出当前时刻加上这个时长得到的一个绝对时刻,然后转手交给 WithDeadline,真正干活的是后者。WithDeadline 会先看这个时刻是不是已经过去了,如果已经过去,它连定时器都不建,建出来的 ctx 当场就是取消状态,Err 是 deadline exceeded。没过去才起一个定时器,到点由运行时把 cancel 叫起来,错误照样用 DeadlineExceeded。所以 WithTimeout 本身没有自己的逻辑,它做的只是把相对时间换算成绝对时间,剩下的全交给 WithDeadline,这也是为什么嵌套调用的时候,最终生效的是最早到点的那个,外面套一层更长的期限没有用,里面那个短的先响。时间到了它自己动手,这个区别在排查的时候很有用。Err 报 canceled,说明是有人主动按的,可能是父节点,也可能是别的代码路径。报 deadline exceeded,说明是时间到了,定时器按的。两个错误值分开,等于把两种原因也分开了。我第一年排查的时候不信这个,看到 deadline exceeded 就去翻下游的超时配置,翻遍了也没找到哪一项设成了那个数,最后才发现是自己这层 WithTimeout 从上游继承过来的剩余时间,那个数从来没人显式写过,它是算出来的。

日志里看到哪一个,基本就知道该往哪儿找。

我后来养成了一个顺序,看到 deadline exceeded 先去看这个请求有没有设超时,看到 canceled 先去找是谁在 defer 里按的 cancel,这两条路通常比对着调用链干猜要快。

拿死掉的父节点建子节点,子节点当场就死

第三个实验只做了一件事,拿一个已经取消的父 ctx 去建子 ctx,然后立刻读子 ctx 的 Err,结果是 context canceled,一行都不等,也没有任何延迟。这个行为在建的时候就已经决定了,子节点一出生就会先看父节点是不是已经取消了,是的话它自己直接进取消状态,不会先登记再等通知,所以这种 ctx 从建出来到能用之间没有窗口。

我猜标准库这么写,是为了避开一种很难查的情况,父节点早就死了,子节点还以为自己活着,接着往下干活,错误从很远的地方才冒出来,那时候栈上已经没有谁还记得是哪一次取消带出来的,只能一层层往回倒,倒到最后也未必找得到源头。

图上就看明白了。

这条路上我摔过两次。第一次是把 ctx 存进了结构体,隔了很久才拿出来用,那会儿请求早就结束了,一路全是 context canceled,我第一反应是 ctx 本身坏了。

第二次是在一个循环里反复用同一个父 ctx 建子 ctx,父节点中途被取消,后面每次建出来的子节点都是死的,我盯着错误日志看了半天,一直以为是下游的问题,最后把父子关系画在纸上才反应过来。(那张纸现在还夹在笔记本里,画得很丑,但比日志有用。)那之后我给每个函数的 ctx 参数都加了一行注释,写清它继承自谁,谁有权取消它。

WithValue 的键不能是 string

WithValue 的签名里,键的类型是 any,看起来什么都能放,可底下用的是 map,键必须可比较,切片、map、函数这些放进去当场就 panic(这一点还算好的),至少崩在眼前。就算可比较,也不该用 string,原因不是性能,是撞键。两个不相干的包都用 user 这个字符串当键,它们在同一个 ctx 上读到的就是对方写进去的东西,编译器不会拦,运行时也不会报错,只会给你一个类型断言失败,或者一个莫名其妙的值,等到发现的时候已经绕了很远。

键要自己定义一个类型。标准库给的解法是定义一个空结构体类型,类型本身就成了命名空间,空结构体不占内存,代价接近于零,换来的是任何别的包都不可能撞上你这个键。读取的时候末尾那个类型断言得留着,别用强制转换,我图省事直接转过一次,值不存在时拿到的是空字符串,那个空串又刚好合法,错误一路飘到监控图上,看着像某个页面真的没有数据。我还见过把键定义成 type userKey = string 这种别名,写法看着像新类型,其实是同一类,撞起来一样不留情。

1
2
3
4
type traceKey struct{}

ctx = context.WithValue(ctx, traceKey{}, "trace-abc")
id, ok := ctx.Value(traceKey{}).(string)

值是请求范围的数据,不是可选参数

值的边界我觉得是这篇文章里最难讲清的一段。ctx 该带的是请求范围的数据,trace id、认证主体、租户号这一类,特点是它们跟着一个请求从入口走到出口,中间好几层都可能要用,但没有一个函数会把它当成自己的业务参数。不该带的是可选参数。你今天把 pageSize 塞进去,明天就会想顺手把 sortField 也塞进去,后天发现有个函数需要它而签名里又没有,于是又去翻 ctx。这条路一直走下去的结果,是依赖关系从签名里消失了,你读一个函数的参数表,根本看不出它到底依赖什么,注释里也不会写,新人接手的时候只能顺着调用链一路往上猜,猜错了就是一次线上问题,很难在本地复现,也很难怪到具体某个人身上。签名里没了依赖,也藏了依赖。我现在判断一个值该不该进 ctx,就问一句,如果这个值不传,函数还能不能正确工作。能,那它是可选的,该走参数或者配置。不能,而且它描述的是这次请求本身,那它才适合放进 ctx。这条线不严谨,但比凭手感强,至少能把一眼就不该进来的东西挑出去。有一次我在一个导出接口上把租户号做成了可选参数,漏传的地方就拿不到租户,数据全落到默认租户名下,线上看图表一切正常,只是那段数据对谁都不显示,隔了一周才有人问起。

(真要说的话,多数时候难受的不是判断不出来,是明知道不该塞又懒得改签名。)

ctx 不杀 goroutine,它只是把门关上

最后说一件很容易误会的事。取消不会杀掉任何 goroutine,ctx 没有这个能力,它能做的只是把那个 channel 关掉。一个 goroutine 如果在跑一段纯计算,中间不看 Done,那它照样跑完,取消对它没有任何作用。所谓协作式就是这个意思,取消是一个通知,接不接在你自己手里。最容易出事的情况,是某个 goroutine 卡在一个很久才回来的调用上,父 ctx 早就取消了,它还在那儿老老实实地等,等回来之后把结果写进一个已经没人要的地方,谁也不报错,只是白白占了资源,等到连接数涨起来才发现是它在拖,那会儿已经离最初的取消过去很久了。取消不是杀进程。所以我现在写带 ctx 的循环或者长任务,第一件事就是在该退出的地方摆一个 select,把 Done 和正在等的东西放在一起,两边谁先来都行。Background 和那个留着以后再说的根都不带取消,它们只是树根,真要能取消,就得在某个地方挂上 WithCancel,这一层省不掉。我一开始还以为 ctx 取消之后运行时会顺手把那个 goroutine 停掉,查了文档才明白根本没有这回事,取消就是关 channel,剩下的全靠你自己看一眼。我在这件事上犯的错比较低级,循环里每轮都 select 一次,退出却写成了 break,而 break 只跳出 select,循环照转。

(这条后来被我写进了自己的检查清单第一行,因为实在没什么好辩解的。)