Go context.WithDeadlineCause 超时后 Cause 和 Err 有什么区别

如果你用 context.WithDeadlineCause 创建了一个带超时原因的上下文，deadline 到期后通常会看到两个不同层次的结果：ctx.Err() 返回稳定的 context deadline exceeded，context.Cause(ctx) 返回创建上下文时传入的具体错误。前者适合做统一分支判断，后者适合记录“为什么这次超时”。

这两个 API 不是互相替代的关系。本文只比较超时上下文中的 Cause 和 Err，不展开 HTTP 或数据库客户端的封装。

先分清 Err 与 Cause 的职责

Context.Err 是调用方最稳定的分类入口：上下文被主动取消时返回 context.Canceled，因为 deadline 到期时返回 context.DeadlineExceeded。调用方可以用 errors.Is 判断这两个标准错误，而不必依赖自定义文本。

context.Cause 则回答“这次取消的具体原因是什么”。如果取消是通过带 cause 的方式发生，Cause 可以返回业务或调度层传入的 error；如果没有额外原因，它会退回到与 Err 相同的值。上下文尚未取消时，Cause 返回 nil。

理解 WithDeadlineCause 的超时语义

WithDeadlineCause(parent, deadline, cause) 的行为类似 WithDeadline，但 deadline 真正到期时，会把传入的 cause 记录到返回的上下文中。它返回的仍然是普通 CancelFunc，这个函数只负责提前结束上下文，不负责设置 cause。

因此可以把结果记成一张小表：

这里的关键是“谁先取消”。如果父上下文先结束，子上下文的最终原因会受父上下文的第一次取消影响；如果返回的 cancel 先被调用，之后 deadline 到期也不会重新写入一个新的 cause。

用一个最小示例读取两个结果

下面的示例把 deadline 设置得很短，并给它一个可读的错误。代码只在 Done 关闭后读取结果，避免在取消发生前把 nil 当成最终结论。

package main

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

func main() {
    // 这个错误描述超时的具体业务原因，供 Cause 保留。
    cause := errors.New("report generation exceeded its budget")
    ctx, cancel := context.WithDeadlineCause(
        context.Background(),
        time.Now().Add(20*time.Millisecond),
        cause,
    )
    // 即使最终由 deadline 触发，也要释放定时器和关联资源。
    defer cancel()

    

这个场景的典型输出是 err: context deadline exceeded，同时 cause 是自定义错误。这里不要用字符串比较来判断超时，使用 errors.Is(ctx.Err(), context.DeadlineExceeded) 更能适应错误包装。

处理主动 cancel 和兼容边界

最容易混淆的是返回值类型：WithDeadlineCause 返回的是 CancelFunc，不是 CancelCauseFunc。调用这个 cancel 时不能传入新的 error，也不会把 cause 改成“手动取消”。如果业务需要在任意时刻主动写入自定义原因，应考虑 context.WithCancelCause，并调用它返回的带参数取消函数。

工程上可以这样分工：控制流用 Err 判断是否取消或超时；日志、指标和诊断字段读取 Cause；无论哪条路径结束，都保留 defer cancel()。另外，WithDeadlineCause 和 WithTimeoutCause 是 Go 1.21 加入的 API，老版本项目需要先确认编译环境，不能只改一处代码就假设所有构建节点都支持。

常见问题

为什么 Err 和 Cause 有时完全相同？

如果上下文没有记录额外 cause，Cause 会退回到与 Err 相同的值；主动取消或普通 WithDeadline 就常见这种结果。

调用 cancel 后还能等到自定义 cause 吗？

不能把返回的普通 CancelFunc 当成带原因的取消器。谁先触发第一次取消，谁决定最终取消状态；需要主动设置原因时，应从创建阶段选择 WithCancelCause。