Go context.WithCancelCause 怎么用：把取消原因带回请求链路

线上排查 Go 服务的取消链路时，最头疼的就是日志里只有一句 context canceled。请求到底是用户主动取消、权限校验没通过、上游接口调用失败，还是本地超时触发的？如果这些关键信息只存在发起取消逻辑的那一层代码里，下游所有协程拿到的就只是一个泛泛的取消状态，排查问题的时候要绕很多弯路。context.WithCancelCause 解决的正是这个痛点：取消动作可以附带自定义原因，后续任意链路位置的代码都能通过 context.Cause 把这个原因读出来。

取消原因随请求链路传播

一个常见场景是：HTTP 请求进来后启动几个子任务，任何一个关键步骤发现不该继续，就取消整个链路。以前大家常写 cancel()，子任务拿到的只有 context canceled。现在可以把原因带进去。

ctx, cancel := context.WithCancelCause(parent)
defer cancel(nil)

go func() {
    if !allowed(userID) {
        cancel(errors.New("permission denied"))
        return
    }
}()

select {
case 

这里 ctx.Err() 仍然会告诉你 context 已取消，但 context.Cause(ctx) 能把“权限不足”这样的具体原因带出来。对排查来说，这比只有 canceled 有价值得多。

只看 ctx.Err 会丢掉业务原因

很多旧代码在退出分支里只记录 ctx.Err()：

select {
case 

这段代码没有错，但信息太粗。它能区分 context.Canceled 和 context.DeadlineExceeded，却不知道为什么取消。对于“用户取消”和“核心依赖失败”这两类问题，后续处理策略完全不同。

如果使用带原因的取消，可以把返回值写得更明确：

select {
case 

这不是要替代 ctx.Err()，而是把两个信息分层使用：ctx.Err() 判断状态，Cause 解释状态背后的原因。

适合用在哪些架构压力点

WithCancelCause 最适合那些“一个点失败，整条链路都要停”的地方。比如权限校验失败后不再查库存，支付风控拒绝后不再创建订单，批处理任务发现输入文件不合法后通知所有 worker 退出。这类场景里，取消不是普通结束，而是带着明确语义的中止。

反例：别把普通错误都塞进 cancel

如果某个函数只是返回一次普通业务错误，不一定要取消整个 context。比如校验某个可选字段失败、某个非关键缓存读取失败，这些错误直接返回或降级就好。把所有错误都塞进 cancel(err)，反而会让链路过早停止，后面的人也很难判断哪些原因真的应该传播。

一个简单判断是：这个错误是否应该让同一请求下的其他 goroutine 也停止？如果答案是肯定的，就适合做取消原因；如果只是当前函数自己的失败，就用普通 error 返回。

和超时、deadline 怎么配合

超时仍然可以继续用 context.WithTimeout 或 context.WithDeadline。如果父 context 已经因为超时结束，Cause 通常会反映 deadline 相关原因；如果你在超时之前主动调用带原因的取消函数，后续读取到的就是你传入的业务原因。

实践里不要为了“所有原因都统一”而手动包装每个超时。系统级超时、用户取消、业务拒绝是三类不同信号，日志里能区分它们，比把它们都改成同一个业务错误更有用。

落地前的判断清单

• 取消原因是否会被多个子任务读取，而不是只给当前函数自己看。
• 调用 cancel(err) 的地方是否足够少，能一眼看出谁触发了整条链路停止。
• 日志里是否同时保留 ctx.Err() 和 context.Cause(ctx)，方便区分状态和原因。
• 是否避免把 token、手机号、完整请求体这类敏感信息写进原因字符串。
• 是否给普通 error 返回和链路取消保留清晰边界。

常见问题

WithCancelCause 会替代 WithCancel 吗？

不会。普通取消只需要通知停止时，WithCancel 仍然够用。只有需要把停止原因传给下游时，才更适合用 WithCancelCause。

context.Cause 返回 nil 正常吗？

正常。如果 context 还没结束，或者取消时没有传入具体原因，就可能拿到 nil。代码里要按这个情况做兜底。

取消原因能放业务错误码吗？

可以，但要控制边界。适合放能解释链路停止的错误码或错误摘要，不适合放完整请求体、隐私字段或一大段调试信息。

子 context 能读到父 context 的原因吗？

可以。父 context 带原因取消后，派生出来的子 context 也能通过 context.Cause 读到对应原因，这正是它适合请求链路传播的原因。

小结

context.WithCancelCause 不是为了让所有错误都变得更复杂，而是给“整条链路为什么停下来”补上一块缺失的信息。保留 ctx.Err() 做状态判断，用 context.Cause 解释业务原因，再控制好哪些错误值得传播，Go 服务的取消日志会清楚很多，排查时也少走弯路。