Go context.WithCancelCause 怎么传递真实失败原因：Cause、Err 与错误链的边界

批量处理订单时，日志里经常只剩一句 context canceled：任务确实停了，却看不出是上游主动取消、超时，还是某个子任务先报错。Go 的 context.WithCancelCause 解决的正是这段信息丢失问题：用 cancel(err) 写入取消原因，再用 context.Cause(ctx) 读取；ctx.Err() 仍然只负责表达上下文的通用状态。

记住这条边界：Err 适合判断“取消还是超时”，Cause 适合回答“为什么取消”；两者不是互相替代的错误接口。

WithCancelCause 解决了哪一段信息丢失

普通的 context.WithCancel 只能调用无参的 cancel()。下游收到 后，最多通过 ctx.Err() 判断 context.Canceled 或 context.DeadlineExceeded，但无法知道取消动作由哪个业务条件触发。

例如订单同步由三个 goroutine 共同完成：库存接口返回不可重试错误时，协调者希望立刻停止另外两个任务，并在最终日志里留下原始错误。此时可以把“停止信号”和“停止原因”分开处理。

最小示例：先写 Cause，再看 Err 和 Cause

package main

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

var ErrStockUnavailable = errors.New("stock unavailable")

func main() {
    ctx, cancel := context.WithCancelCause(context.Background())
    cancel(fmt.Errorf("reserve SKU-42: %w", ErrStockUnavailable))

    fmt.Println(ctx.Err() == context.Canceled)       // true
    fmt.Println(context.Cause(ctx))                   // reserve SKU-42: stock unavailable
    fmt.Println(errors.Is(context.Cause(ctx), ErrStockUnavailable)) // true
}

这个结果说明三件事：ctx.Err() 没有被业务错误替换，Cause 保留了包装后的完整原因，而 errors.Is 仍能沿着 %w 找到哨兵错误。

在并发任务里怎么传递首个失败原因

协调者通常只创建一次带 cause 的上下文。某个子任务失败时调用 cancel(err)，其他任务监听 Done 退出；最后由协调者读取 Cause 做统一返回。不要让每个子任务各自创建一套无关的上下文，否则原因会散落在多个局部变量里。

func runBatch(parent context.Context) error {
    ctx, cancel := context.WithCancelCause(parent)
    defer cancel(nil)

    result := make(chan error, 2)
    go func() {
        if err := syncStock(ctx); err != nil {
            cancel(fmt.Errorf("sync stock: %w", err))
        }
        result 

生产代码还要让每个 goroutine 都有可退出的发送路径，并按项目需要使用 errgroup 或明确的结果收集。这里的关键不是复制示例，而是把“谁决定取消”和“谁读取最终原因”固定下来。

几个容易混淆的边界

取消原因遵循父子上下文的传播规则。已经被父上下文取消的子上下文，不应再假设能用自己的业务错误覆盖父级原因；如果业务上必须区分，就在调用点先记录子任务错误，再把它作为统一结果返回。

常见问题：Cause 什么时候读、错误怎么验收

调用 cancel(nil) 后 Cause 一定是 nil 吗？

不是把它当成业务错误使用即可。取消完成后，先用 ctx.Err() 判断上下文状态，再按需要读取 context.Cause(ctx)；正常取消时不要强行构造一个假的失败原因。

为什么重复调用 cancel(err) 不会更新原因？

上下文只接受首次生效的取消结果。这样并发任务不会因为后来的次要错误覆盖最早的根因，日志应围绕首次取消点组织。

能不能直接比较 context.Cause(ctx).Error()？

不建议。用 errors.Is 判断哨兵错误，用 errors.As 提取结构化错误；字符串只适合展示，不适合流程分支。

普通 WithCancel 代码要立刻改成 WithCancelCause 吗？

不必。只有当取消原因需要跨 goroutine、跨函数或跨层级传递时才值得升级；单纯的资源清理和生命周期控制，普通 WithCancel 已经足够。

验收清单

• 所有阻塞操作都监听了 ctx.Done()，不会因等待结果而泄漏 goroutine。
• 日志同时记录 ctx.Err() 与 context.Cause(ctx)，并区分超时和业务失败。
• 包装错误使用 %w，测试用 errors.Is/As 验证，而不是匹配文本。
• 取消函数放在创建它的函数里 defer，子任务失败时显式传入真实原因。

把 Err 看成通用控制状态，把 Cause 看成取消链上的业务证据，Go 并发代码的错误日志就不会只剩一句“已取消”。

参考资料

可结合 Go 官方 context 包文档 和 Go Blog：context 复查 API 语义与取消传播规则。