Go context.WithCancelCause 怎么保留取消原因：从 ctx.Err 到可诊断错误

线上批量查询场景下，日志里偶尔会打印出完全相同的一句 context canceled：用户关掉页面、上游网关超时、库存服务主动拒绝，最后看起来全都一模一样。Go 1.20 在 context 包里加入了 WithCancelCause 和 Cause，可以在不破坏 ctx.Err() 兼容语义的前提下，把真正的取消原因带到调用链末端。

把 ctx.Err() 当成“是否取消”的判断，把 context.Cause(ctx) 当成“为什么取消”的诊断信息；两者不是互相替代，而是分工使用。

为什么批量查询最后只剩 context canceled

先看一个常见的服务边界。LoadDashboard 同时拉取订单、库存和优惠信息，调用方只关心请求有没有被取消：

func LoadDashboard(ctx context.Context, userID string) error {
    if err := loadOrders(ctx, userID); err != nil {
        return err
    }
    return loadInventory(ctx, userID)
}

func loadOrders(ctx context.Context, userID string) error {
    select {
    case 

这种写法本身没有问题，但它只保留了取消状态。调用方可以用 errors.Is(err, context.Canceled) 判断请求被取消，却无法区分“客户端提前断开”和“业务策略主动停止请求”。如果所有取消都打 ERROR 级别日志，正常用户行为会把告警池占满，真出问题反而看不到；如果全部打成 INFO，又可能漏掉上游触发的容量保护类故障。

Go 1.20 的变化到底影响了什么

WithCancelCause 返回的取消函数可以接收一个 error。上下文完成取消后，ctx.Err() 仍按旧契约返回 context.Canceled；context.Cause(ctx) 才返回具体原因：

var ErrClientLeft = errors.New("client left")
var ErrCapacityGuard = errors.New("capacity guard")

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

cancel(ErrCapacityGuard)

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

这里有个很容易踩的坑：取消函数第一次传入的原因会直接生效，后续再传入新的原因也不会覆盖旧值。因此不要把同一个 CancelCauseFunc 分散给多个业务分支，让每个分支都随便调用取消。更稳妥的做法是由拥有上下文生命周期的那一层统一决定返回的原因，底层业务逻辑只返回自己的原生错误。

如果项目还需要兼容 Go 1.19 或更早版本，直接调用新函数会在编译阶段报错。升级前先确认 go.mod、构建镜像和 CI 版本，不要只改本地开发环境的 Go 版本。

让取消原因沿着调用链变成可判定错误

实际项目里，原因最好用包级哨兵错误或者带自定义字段的错误类型，而不是每次都临时拼接一段日志字符串。这样上层可以稳定地使用 errors.Is 和 errors.As：

type CancelReason struct {
    Stage string
}

func (e *CancelReason) Error() string {
    return "request stopped at " + e.Stage
}

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

    if err := loadInventory(ctx, "u-42"); err != nil {
        var reason *CancelReason
        if errors.As(err, &reason) {
            cancel(reason)
        }
        return err
    }
    return nil
}

func classify(ctx context.Context) string {
    switch {
    case errors.Is(context.Cause(ctx), ErrClientLeft):
        return "normal-cancel"
    case errors.Is(context.Cause(ctx), ErrCapacityGuard):
        return "capacity-warning"
    default:
        return "unknown-cancel"
    }
}

注意不要只在最外层打印 Cause，却在中间层把错误重新包装成丢失原始错误的纯字符串。需要补充订单号、用户 ID 或者执行阶段信息时，用 fmt.Errorf("inventory: %w", err) 保留完整错误链，再把业务上下文放到结构化日志字段里。

迁移时先改哪一层，才不会放大风险

1. 先在 go.mod 和 CI 中确认项目要求的最低 Go 版本至少为 1.20。
2. 只给真正拥有取消决策权的业务边界创建 WithCancelCause，不要在每个函数里都重复派生新的上下文。
3. 现有的 ctx.Err() 判断逻辑完全保留不动，只在日志打印和指标统计的分支补充 context.Cause(ctx) 的相关逻辑。
4. 为用户主动断开、上游超时、容量保护各写一个单元测试，按错误类型做分类判断，不要直接比对错误字符串内容。

如果底层第三方库只返回 context.Canceled，上层也不能凭空猜测背后的原因。可以在明确的业务分支触发取消时记录对应原因；对于来源不明的取消，保留 context.Cause 的实际值并归入未知类别，留待后续结合链路日志补充排查证据。

最小验证：同时检查 Err、Cause 和父子关系

func TestCancelCause(t *testing.T) {
    parent, stopParent := context.WithCancelCause(context.Background())
    child, stopChild := context.WithCancelCause(parent)
    defer stopParent(nil)
    defer stopChild(nil)

    stopChild(ErrClientLeft)
    

再补一个父子上下文同时取消的测试用例：先触发父级取消，再触发子级取消，确认你业务里关心的边界行为符合预期。这个测试能提醒开发团队，原因记录和取消传播之间存在竞态，不能把某一条日志里抓到的原因当成整个请求的唯一根因。

相关问题

context.Cause 会改变 ctx.Err() 的返回值吗？

不会。Err 继续返回通用的取消或超时错误，具体原因由 Cause 提供。

调用 cancel(nil) 有什么意义？

它表示只结束上下文、不提供额外原因。如果没有更具体的原因，Cause 会回退到标准取消错误。

所有 context 都应该改成 WithCancelCause 吗？

不需要。只有上层确实要区分取消来源、并且拥有原因决策权的场景才值得迁移；普通的超时控制场景保持原有写法更简单。

小结

WithCancelCause 不是新增的取消机制，只是给现有成熟的取消传播逻辑补了一条诊断通道。保留 ctx.Err() 的兼容判断逻辑，用 context.Cause 做原因分类，再通过错误链和结构化日志补齐业务上下文，通常就能在不大量改动底层接口的前提下，把模糊的“请求被取消”告警，细化到能明确判断“为什么被取消、要不要触发告警”。