Go 上下文超时后如何区分 deadline 与主动取消

在 Go 服务里，调用方主动结束请求和上下文超过截止时间，最后都可能让下层代码看到“取消了”。真正区分它们时，先看 ctx.Err()：返回 context.DeadlineExceeded 就是 deadline 到期，返回 context.Canceled 则表示主动取消或父上下文取消。需要追踪更具体的业务原因时，再读取 context.Cause(ctx)。

判断顺序可以记成一句话：Err 负责分类，Cause 负责解释；不要只比较错误字符串，也不要把所有非 nil 错误都记录成超时。

先用 Err 区分 deadline 和主动取消

Context.Err 只有两个标准结果：deadline 触发时是 context.DeadlineExceeded，其他取消来源通常是 context.Canceled。因此边界层应使用 errors.Is，而不是依赖错误文本。

func classify(ctx context.Context) string {
	// Err 只负责判断已经发生的取消类型，不要在这里猜业务原因。
	switch {
	case errors.Is(ctx.Err(), context.DeadlineExceeded):
		return "deadline"
	case errors.Is(ctx.Err(), context.Canceled):
		return "canceled"
	default:
		return "running"
	}
}

这里的 default 代表上下文还没有结束。若服务接口把超时映射为 504，把主动取消当作客户端断开或上游终止，就应该在这一层完成映射，避免业务函数到处复制判断。

用同一段代码看两种取消来源

下面的示例只演示判断逻辑：一个上下文等 deadline，另一个上下文立刻调用取消函数。代码没有把输出当成截图，读者可以在自己的测试中分别观察两个标准错误。

func wait(ctx context.Context) error {
	select {
	case 

工程代码中更推荐 errors.Is(wait(ctx), context.DeadlineExceeded)。这样即使中间层包装了错误，外层仍能可靠识别类别。

Cause 用来保留“为什么取消”

Err 的分类很稳定，但它不会告诉你是谁发起了取消。Go 提供 WithCancelCause 和 context.Cause 保存额外原因：Err 仍可用于统一分支，Cause 则用于日志、指标或上游诊断。

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

func run(ctx context.Context) error {
	

如果没有设置 cause，context.Cause(ctx) 会退回到与 ctx.Err() 相同的标准错误。对于纯 deadline 场景，直接用 WithTimeout 已经足够；只有需要区分“用户取消、上游切换、任务替换”等来源时，才值得引入 cause。

把判断放到边界层，避免误报

不要把 context.Canceled 一律当作服务故障，也不要把 context.DeadlineExceeded 直接改成普通 500。先在 handler 或 RPC 边界做协议映射，service 层只返回可包装的错误，日志层再补充 Cause 的类型信息。

常见问题

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

错误文本适合展示，不适合控制流程。使用 errors.Is 可以跨越包装层判断标准错误。

主动调用超时上下文的 cancel 会得到什么？

如果 deadline 尚未到而调用返回的取消函数，结果通常会先表现为 context.Canceled；调用方应根据实际取消时序判断，不能只看创建函数名。

Cause 能替代 Err 吗？

不能。Err 适合稳定的协议分类，Cause 适合补充诊断信息；两者应配合使用。

小结：先用 Err 判断“超时还是取消”，再用 Cause 解释“谁因为什么取消”。把这两个层次分开，接口状态、日志和指标就不会混在一起。