Go context.WithCancelCause 传递根因的错误链

在 Go 的任务链里，ctx.Err() 通常只能告诉上层“已经取消”，却不一定能解释取消是依赖超时、客户端断开，还是业务主动终止。context.WithCancelCause 把这两件事分开：取消状态仍可用 Err 做通用判断，具体根因则用 context.Cause 继续向下游和上层传递。

先区分 ctx.Err 与 context.Cause

最小用法是从父 context 派生一个可携带根因的 context。业务层把真正导致任务停止的错误传给 cancel，读取时不要只看 Err：

package main

import (
    "context"
    "errors"
    "fmt"
)

func main() {
    ctx, cancel := context.WithCancelCause(context.Background())
    defer cancel(nil) // 兜底释放派生 context；真正失败时由业务传入根因

    rootErr := errors.New("依赖服务超时")
    cancel(rootErr) // 记录第一次取消的具体原因

    fmt.Println(ctx.Err() == context.Canceled) // true：通用取消状态
    fmt.Println(context.Cause(ctx) == rootErr) // true：业务根因
}

这里的两个返回值用途不同。ctx.Err() 适合让统一的重试、退出或 HTTP 映射逻辑识别 context.Canceled；context.Cause(ctx) 适合日志、指标和错误分类。传入 nil 时，根因会落为 context.Canceled，所以主动取消也能保持一致语义。

让根因沿任务链向下传播

把 context 作为函数的第一个参数，worker 只负责响应取消并把根因交给调用方。不要把根因塞进 context.WithValue，那会让错误生命周期和取消生命周期脱节。

func runWorker(ctx context.Context) error {
    for {
        select {
        case 

更常见的调用链是：上层创建 ctx，下层返回依赖错误，上层调用 cancel(err)，其他 goroutine 从 Done 醒来后再读取同一个根因。这样日志里既有统一的取消类别，也有可定位的错误链。

处理父子 context 的首次取消边界

Cause 不是可反复改写的共享变量。官方语义是第一次取消某个 context 或其父级的动作决定该 context 的原因：

如果上层要判断某类故障，优先用 errors.Is(context.Cause(ctx), target)，不要依赖错误字符串。需要注意，父 context 的 Cause 和已经先行取消的子 context 的 Cause 可能不同；记录日志时应明确记录当前函数收到的是哪一个 context。

清理责任与排查清单

创建了派生 context 就要在当前函数结束时调用 cancel，即使你确信父级稍后也会取消。这样可以及时解除父对子 context 的引用并停止相关定时器。排查一条“根因没有传上来”的链路时，可按下面顺序检查：

1. 是否真的使用了 WithCancelCause，而不是普通的 WithCancel。
2. 发生依赖错误的那一层是否调用了 cancel(err)，并且传入的 error 不是 nil。
3. 读取点是否在 之后调用 context.Cause(ctx)。
4. 是否存在更早的父级取消，导致当前错误无法成为首次原因。

相关问题

只判断 ctx.Err 是否够用

只做统一退出判断时够用；需要区分超时、依赖失败和主动终止时，应同时读取 Cause。

cancel(nil) 会不会丢失取消信号

不会。Done 仍会关闭，Err 仍会返回取消状态，只是 Cause 会使用 context.Canceled。

Cause 能否替代 error wrapping

不能。Cause 说明 context 为什么结束；函数自身返回的 error 仍应使用 %w 或其他标准方式保留调用链。