Go context.Cause 如何区分超时和业务主动取消

服务进入 分支后，ctx.Err() 只能告诉你“被取消了”还是“超时了”；要知道业务为什么主动终止，应该再读取 context.Cause(ctx)。最实用的分工是：用 Err 决定大类，用 Cause 做日志、重试和告警的细分判断。

先把 ctx.Err 和 context.Cause 分工

这两个 API 解决的是不同问题。ctx.Err() 返回标准取消状态：主动取消通常是 context.Canceled，超过截止时间通常是 context.DeadlineExceeded。context.Cause(ctx) 则返回第一次取消时记录的原因；如果没有额外原因，它会退回到与 Err 相同的错误。

因此不要把 err.Error() 的字符串直接当作分支条件。错误身份应使用 errors.Is，这样原因被包装后仍然可以匹配。

主动取消要用 WithCancelCause 留下原因

例如订单已经被其他流程关闭，当前 goroutine 不需要继续工作。用 WithCancel 只能得到 context.Canceled；换成 WithCancelCause 后，可以保留一个稳定的业务错误。

var ErrOrderClosed = errors.New("order closed")

func runOrder(ctx context.Context) error {
    // 业务取消与超时都从 Done 退出，避免继续写入已关闭的订单。
    select {
    case 

真实项目里通常把哨兵错误定义在包级别，调用方用 errors.Is 比较，而不是依赖完整文本。注意取消函数只记录第一次取消原因，后续再次传入错误不会覆盖它。

超时场景用 WithTimeoutCause 标记来源

超时也可以有比 context.DeadlineExceeded 更具体的说明，例如“库存服务预算耗尽”。使用 WithTimeoutCause 时，传入的 cause 只在截止时间真正到达时生效；如果代码提前调用返回的 CancelFunc，这个函数不会把自定义超时原因写进去。

var ErrInventoryBudget = errors.New("inventory budget exceeded")

func callInventory(parent context.Context) error {
    // 到时后 Cause 是 ErrInventoryBudget，提前 cancel 则是 Canceled。
    ctx, cancel := context.WithTimeoutCause(parent, 800*time.Millisecond, ErrInventoryBudget)
    defer cancel() // 无论哪条路径结束，都要停止计时器并释放资源。

    if err := requestInventory(ctx); err != nil {
        if errors.Is(context.Cause(ctx), ErrInventoryBudget) {
            return fmt.Errorf("库存请求超时: %w", err)
        }
        return err
    }
    return nil
}

如果只需要标准超时状态，WithTimeout 依旧够用；需要区分不同下游预算、阶段或策略时，再为 cause 定义稳定错误。这里的 Cause 是解释信号，不会替代请求函数本身返回的网络错误。

父子 Context 同时取消时谁的原因生效

父 Context 取消会向下传播，但“第一次取消”很关键。父先取消，子还没有自己的取消原因时，子会继承父的 Cause；子先用 WithCancelCause 取消，则子保留自己的 Cause，之后父再取消也不会覆盖已经确定的子原因。

可以把它理解成一条只写一次的原因链：

线上排查时按这张表读取取消信号

在统一中间层里，建议先保存 Err 和 Cause，再决定重试、降级或告警。这样既不会把客户端主动断开误报成服务故障，也不会把真正的预算超时吞成一个笼统的“已取消”。

func classifyCancellation(ctx context.Context) string {
    // 先用 Cause 做稳定身份判断，再用 Err 兜底未知 Context。
    cause := context.Cause(ctx)
    switch {
    case errors.Is(cause, ErrOrderClosed):
        return "business-cancel"
    case errors.Is(cause, ErrInventoryBudget):
        return "timeout-inventory"
    case errors.Is(ctx.Err(), context.DeadlineExceeded):
        return "timeout-unknown"
    case errors.Is(ctx.Err(), context.Canceled):
        return "cancelled"
    default:
        return "not-cancelled"
    }
}

排查日志至少保留分类结果、ctx.Err() 和 context.Cause(ctx) 的错误身份；不要只记录 Cause 的字符串。若 Cause 来自外部输入，还应在日志层做字段截断和脱敏。

常见问题

context.Cause(ctx) 没有自定义错误怎么办？

如果 Context 通过普通 WithCancel 或 WithTimeout 创建，Cause 会退回到 ctx.Err()。这不是读取失败，而是上游没有提供额外原因。

调用 cancel(nil) 会得到什么？

WithCancelCause 返回的取消函数传入 nil 时，Cause 会变成 context.Canceled。它适合只做资源清理、不需要附加业务语义的路径。

能不能用字符串比较超时原因？

不建议。用包级哨兵错误和 errors.Is 比较，错误被 %w 包装后仍能保持可判断性。