Go context.WithCancelCause 实战：让超时、主动取消和上游失败各自可追踪

服务端同时遇到“用户点了取消”“下游真的超时”和“上游返回业务错误”时，单看 ctx.Err() 往往只能得到 context canceled 或 context deadline exceeded。Go 1.20 提供的 context.WithCancelCause 可以把取消动作和具体原因一起带过调用链，让日志、重试判断和接口返回各自拿到更准确的信息。

先看一个请求为什么只剩下模糊的取消错误

下面的场景很常见：HTTP handler 启动一个下游查询，用户在结果返回前关闭页面；另一种情况是下游服务卡住，整体预算耗尽。两种请求都可能在日志里留下相同的结束状态，但处理方式并不一样。前者通常不必报警，后者需要看超时比例，业务失败则可能需要重试或降级。

func load(ctx context.Context) error {
    if err := query(ctx); err != nil {
        return err
    }
    return nil
}

// 旧代码通常只看到这两类状态：
if errors.Is(err, context.Canceled) { /* 请求被取消 */ }
if errors.Is(err, context.DeadlineExceeded) { /* 时间预算耗尽 */ }

这两个判断没有错，但它们回答的是“上下文为什么结束”，没有回答“谁决定结束、为什么决定结束”。当上游要把 quota exhausted 或 upstream unavailable 传给日志时，原因就丢在了中间层。

WithCancelCause 和 Cause 各自解决什么问题

context.WithCancelCause 返回一个派生上下文和一个接收 error 的取消函数。调用取消函数时传入的错误会成为该上下文的原因，任何拿到这个上下文的下游都可以通过 context.Cause 读取它。

package main

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

var ErrQuota = errors.New("quota exhausted")

func main() {
    ctx, cancel := context.WithCancelCause(context.Background())
    cancel(ErrQuota)

    fmt.Println(ctx.Err())            // context canceled
    fmt.Println(context.Cause(ctx))   // quota exhausted
    fmt.Println(errors.Is(context.Cause(ctx), ErrQuota)) // true
}

这里故意保留两个读取入口：Err() 是兼容性的粗粒度状态，Cause() 是可用于诊断和业务分支的细粒度原因。旧的中间件继续检查 Err() 不会失效，新代码可以补充原因字段。

三类取消原因应该怎样落到代码里

用户主动终止：记录取消，不升级成服务故障

例如连接断开、客户端撤销搜索，调用方可以传入一个明确的原因。日志采集层遇到 errors.Is(cause, ErrUserAbort) 时只记调试信息，避免把用户行为算进服务端错误率。

var ErrUserAbort = errors.New("user aborted request")

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

if clientClosed {
    cancel(ErrUserAbort)
    return
}

时间预算耗尽：保留 DeadlineExceeded 的通用语义

如果业务只是想让下游知道预算已用完，可以直接使用 context.WithTimeout。如果还需要指出是“库存服务超时”还是“推荐服务超时”，则在负责聚合请求的那一层创建 cause，并把服务名写进包装错误。

var ErrInventoryTimeout = errors.New("inventory request timeout")

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

if err := callInventory(ctx); err != nil {
    if errors.Is(err, context.DeadlineExceeded) {
        cancel(ErrInventoryTimeout)
    } else {
        cancel(err)
    }
    return err
}

上游业务失败：把可判断的 sentinel error 传下去

上游返回限额不足、权限不足或熔断时，不要只拼字符串。定义稳定的错误值，再用 fmt.Errorf("...: %w", err) 保留判断链，日志字段可以同时输出错误文本和 cause 类型。

第一次取消决定最终原因

同一个上下文可能被多个 goroutine 观察，也可能出现超时和主动取消同时发生。原因不是后来者覆盖的共享字段，而是第一次有效取消确定的结果。因此需要让负责生命周期的代码拥有取消权，其他 goroutine 只报告候选错误。

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

go func() {
    if err := fetchA(ctx); err != nil {
        cancel(fmt.Errorf("fetch A: %w", err))
    }
}()

go func() {
    if err := fetchB(ctx); err != nil {
        cancel(fmt.Errorf("fetch B: %w", err))
    }
}()

上面代码可以工作，但两个并发分支竞争“谁先取消”。如果产品需要稳定地优先保留某一类原因，就要在聚合层用 channel 收集错误，按明确的优先级选择一次，再调用 cancel。

接入现有 HTTP 服务时的检查顺序

1. 在请求入口创建带 cause 的派生 context，并规定谁拥有取消函数。
2. 在下游返回处先判断原始错误，再决定是否包装成服务名或业务 sentinel。
3. 响应层先用 errors.Is(err, context.Canceled) 和 errors.Is(err, context.DeadlineExceeded) 保持旧行为。
4. 日志层额外输出 context.Cause(ctx)，不要把整个 error 直接当作可索引标签。
5. 为主动取消、预算超时、业务失败各写一个测试，验证第一次取消和错误链。

兼容旧版本时，最稳妥的做法是把 cause 能力留在应用层，公共函数参数仍然使用 context.Context。这样下游只依赖接口，不需要知道入口具体选择了哪一种 context 构造函数。

常见问题

context.Cause(ctx) 会替代 ctx.Err() 吗？

不会。Err() 仍然提供兼容的取消状态；Cause() 用来补充首次取消时保存的具体错误。

cancel(nil) 会不会清空已经设置的原因？

不会。它适合放在 defer 中做资源收尾，已经确定的 cause 不会被后续取消调用覆盖。

超时场景一定要使用 WithCancelCause 吗？

不一定。只关心截止时间时使用 WithTimeout 更直接；当日志或重试策略需要区分具体下游时，再增加 cause。

如何避免多个 goroutine 抢先写入错误原因？

让 goroutine 只上报错误，由单独的聚合层按优先级选出一个最终原因，并由聚合层调用取消函数。

把取消状态和真正原因一起留下

context.WithCancelCause 的价值不在于多了一个 API，而在于把“请求结束了”和“请求为什么结束”拆成两个可验证的问题。保留 Err() 作为通用状态，再用 Cause() 保存稳定、可判断的业务原因，既能兼容已有中间件，也能让超时率、用户取消和上游故障在日志里分开统计。