Go context.WithCancelCause 怎么传递取消原因：错误链与测试验收

服务端收到客户端断开、超时或主动终止任务时，单纯调用 cancel() 只能让下游知道“该停了”，却说不清“为什么停”。Go 的 context.WithCancelCause 正好补上这段信息：调用方保留一个可识别的错误原因，下游通过 context.Cause(ctx) 读取它，同时仍可用 ctx.Err() 判断是否已经取消。

什么时候值得把取消原因带下去

如果下游只是停止循环，普通的 context.WithCancel 已经够用；但在批处理、并发聚合和后台刷新任务里，取消原因往往决定日志级别、重试策略和最终返回值。比如库存同步因为请求超时被终止，和因为业务发现版本冲突而终止，后续动作并不一样。

这个 API 适合传递本次取消的根因，不适合把一整份响应对象直接塞进 context。作为取消原因的错误值应该是稳定、可比较的类型，其余细节内容放在日志字段或业务返回结构里单独处理就好。

三种写法的差别：能停下来，还要能说清原因

只用 WithCancel：有状态，没有根因

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

// 下游只能得到 context.Canceled 或 context.DeadlineExceeded

这种方式最简单，兼容所有常见的取消流程。问题在于，调用方把“用户主动停止”“版本冲突”“上游任务失败”都压成了同一个 context.Canceled。

用 WithCancelCause：取消函数可以携带 error

var ErrVersionConflict = errors.New("version conflict")

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

go func() {
    if err := syncOne(ctx); err != nil {
        cancel(fmt.Errorf("sync stopped: %w", err))
    }
}()

这里用 %w 保留错误链，下游不需要知道上游包裹了几层。ctx.Err() 仍然返回取消状态；真正的业务原因由 context.Cause(ctx) 提供。

一个可落地的并发任务边界

常见的使用场景比如批处理器同时同步多个数据分片，父任务负责汇总最终结果，任意分片发现不可恢复的版本冲突时，直接终止其余正在执行的分片任务，同时把冲突的具体来源透传到最外层调用逻辑。

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

    results := make(chan error, len(shards))
    for _, shard := range shards {
        shard := shard
        go func() {
            results 

实际项目里写完逻辑还要等待已启动的 goroutine 正常收尾，不要函数提前返回后还残留着写入通道、占用资源的后台任务。上面的演示片段重点标注的是边界约定：取消动作和取消原因必须由同一个逻辑拥有者管理。

父上下文先结束时，Cause 可能不是子任务的错误

这部分是测试环节最容易误判的细节。如果父上下文已经因为超时提前结束，子上下文还没来得及调用自身绑定的取消函数，那么子上下文拿到的 cause 会直接继承父上下文的原因，不能看到子上下文实例就默认 cause 一定来自子任务本身。

func TestCauseFromParent(t *testing.T) {
    parent, stop := context.WithCancelCause(context.Background())
    child, cancel := context.WithCancelCause(parent)

    parentErr := errors.New("parent stopped")
    stop(parentErr)
    

如果子任务先调用 cancel(childErr)，再由父上下文取消，则子上下文保留先写入的原因。测试要显式控制顺序，避免用无同步的睡眠“碰运气”。

错误判断和资源收尾的几个边界

• 业务分类用哨兵错误或自定义类型，使用 errors.Is、errors.As，不要依赖 err.Error() 的完整文本。
• 取消函数应由创建子上下文的函数负责调用，常规成功路径用 defer cancel(nil) 释放关联资源。
• 收到 ctx.Done() 后仍要检查子任务是否已退出，尤其是子任务持有连接、文件或临时锁时。
• 不要把密码、令牌或整段原始用户输入作为 cause 传入，这类错误值最终会流入日志、测试失败信息和监控标签，容易引发敏感信息泄露问题。

相关问题：项目里怎么选 API

只有超时，没有业务原因，需要 WithCancelCause 吗？

不一定。若调用方只关心是否超时，WithTimeout 更直接；当下游需要区分超时来源或把根因交给统一错误处理时，再增加 cause。

context.Cause(ctx) 和 ctx.Err() 应该返回哪个？

状态判断优先看 ctx.Err()，业务分类看 context.Cause(ctx)。两者承担的职责不同，不建议相互替代。

取消原因需要跨网络传输吗？

context 只做进程内的任务生命周期传播。跨服务调用的场景下，应该把经过筛选的错误码或状态值放到协议的明确字段里传输，服务内部再用 context 统一管理本地 goroutine 的运行生命周期。

收束：把“停止”与“为何停止”分开

WithCancelCause 的价值不在于多一个 API，而在于让并发代码同时保留状态和原因。创建者负责取消，下游用 ctx.Err() 判断状态、用 context.Cause(ctx) 做错误分类，再用确定性的测试覆盖父子取消顺序，这套边界就能稳定工作。