Go context.WithCancelCause 怎么保留根因：取消传播、Cause 读取与错误包装边界

服务把上游取消当成普通的 context.Canceled 记下来，排查时常常只剩一句“请求被取消了”，却不知道是客户端断开、库存校验失败，还是下游主动终止。Go 1.20 引入的 context.WithCancelCause 解决的正是这层信息丢失：ctx.Err() 继续提供稳定的取消类别，context.Cause(ctx) 额外保留触发取消的根因。

先复现一次“只知道取消、不知道为什么”的请求链

假设一个订单接口同时检查库存和配送范围。库存协程发现业务条件不满足后调用取消函数，HTTP 层只监听 Done()，最后把 ctx.Err() 返回给日志系统。请求确实停下来了，但日志无法回答“哪个检查先失败”。

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

// 某个下游失败后：
cancel(errOutOfStock)

fmt.Println(ctx.Err()) // context canceled
// 原始的 errOutOfStock 已经没有位置可读

这不是把错误字符串换个写法就能解决的问题。普通 CancelFunc 的签名没有接收 error；如果要保留根因，创建上下文时就要选择带 cause 的 API。

WithCancelCause 的最小改动：分类和根因各看各的

WithCancelCause 返回的是 CancelCauseFunc。调用方传入一个非空错误后，ctx.Err() 仍是稳定的 context.Canceled，而 context.Cause(ctx) 返回传入的业务错误。

var errOutOfStock = errors.New("inventory: item unavailable")

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

cancel(errOutOfStock)

fmt.Println(ctx.Err() == context.Canceled)       // true
fmt.Println(context.Cause(ctx) == errOutOfStock) // true

这里的 defer cancel(nil) 仍然值得保留，它负责在函数提前返回时释放上下文关联资源。若前面已经用业务错误取消，后面的 nil 不会把已记录的 cause 改掉。

把根因沿着子上下文传下去

取消通常发生在调用链中间，而读取往往在更下游。由带 cause 的上下文派生出的子上下文，能看到同一个取消结果，因此工作函数不必额外增加一条“失败原因”通道。

func loadOrder(ctx context.Context) error {
    

下游可以用 errors.Is 或 errors.As 做机器判断，日志再通过 %v 或结构化字段展示上下文。不要只把 context.Cause(ctx).Error() 拼成一段文本后丢掉原始 error。

父子上下文谁先取消，决定谁的 cause 生效

这条规则最容易在超时和业务取消同时发生时被误读。每个上下文的第一次取消决定自己的 cause；但如果父上下文已经先取消，子上下文会从父上下文继承取消状态和 cause。

因此，子任务想表达自己的局部失败时，应由子上下文先取消；如果它已经观察到父取消，再去调用自己的取消函数，并不能把父 cause 改成新的值。

错误包装边界：保留 cause，不要把取消类别改没

一个常见的迁移错误是直接返回 context.Cause(ctx)，这样业务根因虽然保留了，但上层可能失去对 context.Canceled 的统一判断。更稳妥的做法是把 cause 包在一个带上下文的 error 中，并确认调用方真正需要的是哪一层。

func waitWorker(ctx context.Context) error {
    

要注意，业务错误和 context.Canceled 不一定天然同时存在于一条 unwrap 链上。若监控必须同时统计取消类别与业务根因，建议把两者分别写入结构化日志字段，例如 cancel_kind、cancel_cause，不要强行用一个字符串承载两个维度。

迁移前后的回归检查

把普通 WithCancel 替换成 WithCancelCause 后，至少覆盖下面四个检查点。重点不是“能不能编译”，而是第一次取消、父子竞速和错误判断是否符合原来的接口约定。

1. 用非空业务错误调用 cancel(err)，断言 ctx.Err() == context.Canceled 且 context.Cause(ctx) 可被 errors.Is 找到。
2. 用 cancel(nil) 覆盖主动取消路径，确认 cause 是 context.Canceled，不是一个模糊的 nil。
3. 分别测试父先取消、子先取消，记录两个上下文的 Err 和 Cause。
4. 对包装后的返回值执行 errors.Is，确保日志格式化不会成为唯一的判断依据。

go test ./...
go vet ./...

常见问题

context.Cause(ctx) 和 ctx.Err() 能互相替代吗？

不能。Err 用于稳定判断取消或超时类别，Cause 用于读取更具体的取消原因；两者承担的接口职责不同。

重复调用 CancelCauseFunc 会覆盖旧错误吗？

不会。上下文第一次被取消后，后续调用不会替换已经确定的 cause，所以真正重要的失败路径要先完成取消。

WithTimeout 能不能直接传业务 cause？

如果要为超时本身指定原因，可以看 WithTimeoutCause；普通 WithTimeout 只能提供标准的超时错误。业务主动终止则应使用合适的 CancelCauseFunc。

把取消原因当成接口的一部分

WithCancelCause 的价值不在于让错误信息变长，而在于把“请求为什么停止”和“停止属于哪一类”拆成两个可验证的字段。迁移时先保持 ctx.Err() 的稳定语义，再用 context.Cause(ctx) 补齐根因，最后用父子取消顺序和 errors.Is 测试把边界固定下来，后续排障才不会依赖猜测。