Go context deadline exceeded 和 canceled 怎么区分

排查 Go 请求失败时，context deadline exceeded 和 context canceled 不是同一种情况：前者表示上下文的截止时间已经到达，后者表示调用方或父上下文主动取消。实际代码中不要比较错误字符串，优先用 errors.Is(err, context.DeadlineExceeded) 和 errors.Is(err, context.Canceled)；如果还要知道“谁取消了它”，再读取 context.Cause(ctx)。

先看 Err：两个错误代表什么

Context 的 Done() 只告诉你取消信号已经发生，真正区分原因要看 Err()。由 WithCancel 创建的上下文，调用 cancel() 后通常得到 context.Canceled；由 WithTimeout 或 WithDeadline 创建的上下文，截止时间先到则得到 context.DeadlineExceeded。如果父上下文先结束，子上下文也会沿着这条链路结束。

这里的“超时”只说明 context 的时限已过，并不等于每个底层函数都会原样返回这个错误。网络库、数据库驱动或业务层可能在它外面再包一层，因此判断时要保留错误链。

用 errors.Is 处理被包装的返回值

下面的辅助函数把分类和日志文本分开。它不运行重试，只负责识别原因；这样上层可以根据请求类型决定是否重试，避免把用户主动取消误当成服务故障。

package main

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

func classify(ctx context.Context, err error) string {
    // 优先检查错误链，兼容 fmt.Errorf("...: %w", err) 这样的包装。
    if errors.Is(err, context.DeadlineExceeded) {
        return "timeout"
    }
    if errors.Is(err, context.Canceled) {
        return "canceled"
    }
    // ctx.Err() 可作为底层没有返回错误、但取消信号已到达时的补充判断。
    if ctxErr := ctx.Err(); ctxErr != nil {
        return ctxErr.Error()
    }
    return "other"
}

func main() {
    ctx, cancel := context.WithCancel(context.Background())
    defer cancel() // 释放派生 context 的关联资源。

    wrapped := fmt.Errorf("query stopped: %w", context.Canceled)
    fmt.Println(classify(ctx, wrapped)) // canceled
}

代码中的顺序也有讲究：先看函数实际返回的 err，再用 ctx.Err() 补充上下文状态。不要只因 ctx.Err() 是超时，就把一个已经返回的独立业务错误改写成超时。

把取消原因传到业务层

只需要标准分类时，context.Canceled 和 context.DeadlineExceeded 已经够用。需要区分“用户取消”“上游熔断”“批处理主动停止”等情况时，可从 WithCancelCause 得到 CancelCauseFunc。控制分支仍看 ctx.Err()，诊断信息则看 context.Cause(ctx)，两者职责不要混在一起。

package main

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

var errUserStopped = errors.New("user stopped request")

func main() {
    ctx, cancel := context.WithCancelCause(context.Background())
    cancel(errUserStopped) // 记录主动取消的具体原因。

    // Err 用于稳定的控制分类，Cause 用于日志和排障上下文。
    fmt.Println(errors.Is(ctx.Err(), context.Canceled)) // true
    fmt.Println(context.Cause(ctx))                     // user stopped request
}

如果是 WithTimeoutCause 到期，ctx.Err() 仍然是 context.DeadlineExceeded，而 context.Cause(ctx) 可以提供更具体的超时原因。注意：调用返回的 cancel 仍应放进 defer，即使你预计 deadline 很快就会到。

迁移时检查日志、重试与清理

把旧代码从字符串判断迁移到标准错误判断时，可以按下面的清单收尾：

• 入口函数把 ctx 作为第一个参数传递，不把 Context 存进结构体。
• 每次创建 WithCancel、WithTimeout 或 WithDeadline 都确认有对应的 cancel()。
• 超时日志带上操作名、耗时和依赖；主动取消通常降低日志级别，不触发无意义重试。
• 数据库、HTTP 或队列调用继续把同一个子 context 传下去，避免只在外层判断而底层仍阻塞。

一句话记忆：canceled 是“有人让它停”，deadline exceeded 是“给它的时间用完了”；Err 负责分类，Cause 负责解释。

相关问题

为什么不能直接比较 err.Error()？

错误文本可能被包装、翻译或补充上下文，字符串不稳定。用 errors.Is 才能沿错误链识别标准错误。

调用 cancel 后一定马上得到 Canceled 吗？

取消函数发出信号并不等待业务协程结束。调用方需要在协程中监听 Done()，并在返回路径清理资源。

有了 Cause 还需要判断 Err 吗？

需要。Err 是稳定的控制分类，适合决定退出和重试；Cause 适合写入日志、指标标签或排障信息。