Go context.WithCancelCause 实战：并发任务链如何传递真正的失败原因

多并发任务协作处理订单的场景里，最怕碰到某条子任务失败后，上层调用方只拿到一句干巴巴的“context canceled”，最后根本分不清到底是库存校验没通过、下游服务超时，还是运营手动触发的人工终止。Go 1.20 正式引入的 context.WithCancelCause 可以把取消信号和真实的失败根因一起传回调用方。

先做一个会提前收敛的并发任务链

下面的示例模拟常见的订单处理流程：库存预留和优惠券锁定两个任务并行执行，任意一条任务失败就立刻终止另一条支路，避免不必要的资源占用。为了方便结果复现，库存任务里用了一段短等待模拟下游服务的响应延迟，之后主动返回对应的业务错误。

package main

import (
    "context"
    "errors"
    "fmt"
    "sync"
    "time"
)

var ErrStockInsufficient = errors.New("stock insufficient")

func reserveStock(ctx context.Context) error {
    select {
    case 

这里有两个很关键的实现细节：结果通道的容量设为2，能确保两个goroutine都可以顺利把结果回写不会阻塞；stop(err) 可以让另一条正常运行的支路尽可能快的感知到取消信号退出执行。就算后续主动调用defer stop(nil) 也只是释放上下文关联的占用资源，不会覆盖已经提前记录好的非空失败原因。

为什么不能只看 ctx.Err()

触发上下文取消之后，ctx.Err() 正常只会返回 context canceled 或者 context deadline exceeded 这两个值。这两个返回值足够用来判断控制流状态，但完全不会携带任何业务侧的失败根因。

实际开发处理的时候，先把任务本身返回的错误单独留存，再单独读取取消的根因。比如库存不足这类业务校验错误应该直接终止订单流程，完全不需要重复发起重试；如果是下游依赖服务超时这类错误，就可以根据接口幂等性和资源预算来判断要不要发起重试。

if errors.Is(err, ErrStockInsufficient) {
    markOrderRejected(orderID, "库存不足")
} else if errors.Is(err, context.DeadlineExceeded) {
    scheduleRetry(orderID)
} else {
    alertDependency(orderID, err)
}

把失败原因变成可以检查的状态

并发任务链运行的时候，多个执行支路可能在几乎同一时间抛出错误。取消原因本身遵循「第一个非nil原因优先生效」的规则，所以千万不要在每个收尾分支里随便写入新的自定义原因。更稳妥的实现方案是在离失败现场最近的位置调用带原因的取消函数，在所有上层统一出口只做根因读取的操作。

测试取消状态和根因

func TestHandleOrderCause(t *testing.T) {
    parent := context.Background()
    ctx, stop := context.WithCancelCause(parent)
    want := errors.New("coupon service unavailable")
    stop(want)

    if !errors.Is(ctx.Err(), context.Canceled) {
        t.Fatalf("unexpected state: %v", ctx.Err())
    }
    if !errors.Is(context.Cause(ctx), want) {
        t.Fatalf("unexpected cause: %v", context.Cause(ctx))
    }
}

这类测试可以拦住一个非常常见的线上回归问题：如果后续开发者不小心把 Cause 换回普通的 Err，取消逻辑本身仍能正常触发，但原有测试只判断了取消状态是否正常，就会直接通过，完全感知不到根因传递逻辑已经失效。

几个容易踩到的边界

• 不要把 stop(nil) 当成“清除原因”；取消一旦发生，父子上下文状态不会恢复。
• 父上下文先因超时结束时，子上下文能看到超时原因；子任务自己的原因只有在它先触发取消时才会成为根因。
• 错误需要可比较时优先使用包级哨兵错误或包装错误，日志里再补充订单号、任务名和下游地址。
• 如果任务已经完成，仍要让 goroutine 能安全写入结果通道，通道容量或收集逻辑必须和并发数量匹配。

相关问题

WithCancelCause 能替代 WithTimeout 吗？

不能。超时需要 WithTimeout 或 WithDeadline 控制时间，WithCancelCause 负责记录取消原因，两者可以组合使用。

context.Cause(ctx) 什么时候返回 nil？

上下文尚未被取消时返回 nil；取消后，如果没有传入自定义原因，通常会返回与取消状态对应的原因。

多个 goroutine 同时 stop 会发生什么？

只有第一个传入的非 nil 原因会被记录，后续取消调用不会覆盖它。因此根因应在最接近失败现场的位置确定。

收尾检查

把并发任务拆成多支路执行的时候，取消信号负责解决「让所有正在跑的任务都停下来」的问题，取消原因负责解决「大家到底为什么停下来」的问题。在订单处理、批量任务跑批、聚合类接口这些常见场景里，建议把两部分信息都同时落日志：用 Err() 控制主流程流转，用 Cause() 做业务侧的分支策略分流，最后用单元测试把这套约定逻辑校验住。