Go context 超时后怎么区分上游取消和下游失败

Go 里遇到“请求超时”，不要只看下游返回的 context deadline exceeded 就下结论。ctx.Err() 说明的是上下文为什么结束，context.Cause(ctx) 能补充上游取消时携带的原因，而下游函数自己的 error 仍然是另一条证据。把这三项分开记录，才能判断是调用方不要结果了、本地 deadline 到期，还是下游真的失败。

先用 Err 判断上下文结束的类型

Context 的 Done 关闭后，调用 Err 才有判断意义。最小检查可以写成：

func contextState(ctx context.Context) string {
    // Err 只回答上下文如何结束，不代表下游函数的业务结果。
    switch {
    case errors.Is(ctx.Err(), context.Canceled):
        return "upstream canceled"
    case errors.Is(ctx.Err(), context.DeadlineExceeded):
        return "deadline exceeded"
    default:
        return "context still active"
    }
}

如果父请求主动取消，通常得到 context.Canceled；如果 WithTimeout 创建的 deadline 先到，则是 context.DeadlineExceeded。这里的“上游”可以是 HTTP 请求、调用方的 goroutine，或者更外层的服务。它描述的是取消信号的生命周期，不等于数据库、RPC 或文件操作已经失败。

用 Cause 读取上游传下来的取消原因

当业务需要区分“用户离开页面”“上游切换候选”“限流主动终止”等主动取消原因时，可用 WithCancelCause：

func load(ctx context.Context) error {
    // 子函数只接收 context，不把取消原因塞进全局变量。
    if err := callBackend(ctx); err != nil {
        return fmt.Errorf("backend call: %w", err)
    }
    return nil
}

func run(parent context.Context) error {
    ctx, cancel := context.WithCancelCause(parent)
    defer cancel(nil) // 正常返回时释放关联资源，不覆盖已设置的 cause。

    if err := load(ctx); err != nil {
        // Cause 用于补充取消来源，Err 仍用于判断 Canceled/DeadlineExceeded。
        return fmt.Errorf("cause=%v ctx=%v: %w", context.Cause(ctx), ctx.Err(), err)
    }
    return nil
}

cancel(reason) 被调用后，context.Cause(ctx) 返回这个原因；如果只是普通取消或 timeout，没有自定义原因时，Cause 会回到与取消状态相匹配的 context 错误。不要把 Cause 当作下游错误容器：它只说明取消链上的原因。

把下游返回值和 ctx 状态分开映射

排障时最容易犯的错误是：下游函数返回一个错误，就直接拿 ctx.Err() 替换它。更稳妥的顺序是先保留原始错误，再检查上下文：

func fetch(ctx context.Context) error {
    err := callBackend(ctx)
    if err == nil {
        return nil
    }

    // 下游 error 保留具体资源信息；ctx 只补充请求生命周期信息。
    state := ctx.Err()
    cause := context.Cause(ctx)
    if errors.Is(state, context.Canceled) || errors.Is(state, context.DeadlineExceeded) {
        return fmt.Errorf("request state=%v cause=%v: backend=%w", state, cause, err)
    }
    return fmt.Errorf("backend failed: %w", err)
}

例如，后端返回“连接被拒绝”时，若上下文仍然活着，应归类为 downstream failure；若调用方已取消，请求最终收到的错误可能是下游对取消的响应，但根因记录应同时留下 ctx.Err() 和 Cause。两者都存在时，不能只凭错误字符串猜测。

用决策表覆盖超时、取消和失败

测试时不要只断言完整错误字符串。可以使用 errors.Is 检查状态，用哨兵错误检查下游错误是否仍被 %w 包装；这样即使日志增加了 Cause 或请求编号，测试仍关注真实边界。

var errBackend = errors.New("backend unavailable")

// 只验证错误类别，避免把日志格式当成接口契约。
if !errors.Is(err, errBackend) {
    t.Fatalf("backend error was lost: %v", err)
}
if !errors.Is(ctx.Err(), context.DeadlineExceeded) {
    t.Fatalf("unexpected context state: %v", ctx.Err())
}

常见问题

下游已经返回 context.Canceled，还要检查 ctx.Err 吗？

要。下游的返回值说明它如何响应取消，ctx.Err() 说明当前请求上下文的最终状态；两项一起记录，才能区别上游取消与下游自行返回的同名错误。

WithTimeout 能不能传入自定义取消原因？

WithTimeout 适合表达 deadline。需要明确业务原因时，在上游使用 WithCancelCause；不要把业务原因硬编码进错误字符串再反向解析。