Go context.WithDeadlineCause 超时后如何读取取消原因

如果 Go 请求超时后日志里只有 context deadline exceeded，先不要把它当成完整原因。ctx.Err() 只描述上下文当前的状态；使用 context.WithDeadlineCause 创建上下文后，应该在 返回时调用 context.Cause(ctx)，才能读到为这次 deadline 配置的具体错误。

为什么 Err() 和 Cause() 会给出两种结果

这两个 API 解决的是不同问题。Err 是兼容所有 Context 实现的状态判断，适合用 errors.Is 判断是否超时或取消；Cause 是原因通道，允许调用方保留“上游依赖超时”“租约已过期”这类诊断信息。

因此，日志通常可以同时记录两者：先用 errors.Is(err, context.DeadlineExceeded) 做程序分支，再把 context.Cause(ctx) 作为排查信息输出。不要用 cause 的字符串替代标准错误判断。

用 WithDeadlineCause 读取自定义超时原因

第三个参数就是 deadline 到期时要保存的错误。下面的示例让子上下文在 20 毫秒后结束，并把原因保存为一个可被上层识别的错误。

package main

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

var errUpstreamBudget = errors.New("上游依赖耗尽调用预算")

func main() {
    // 用一个很短的截止时间演示子 context 自己先超时的场景。
    ctx, cancel := context.WithDeadlineCause(
        context.Background(),
        time.Now().Add(20*time.Millisecond),
        errUpstreamBudget,
    )
    defer cancel() // 无论何时结束都释放定时器和父子引用。

    

实际服务里不必等待固定时间；被调用的数据库、HTTP 客户端或后台任务应监听同一个 ctx.Done()。关键是只在取消后读取 cause，否则 context.Cause(ctx) 仍然是 nil。

提前 cancel 或父 context 先结束时怎么判断

WithDeadlineCause 的 cause 不是强制覆盖值。若返回的 cancel() 先被调用，子上下文的状态是 context.Canceled，原因也不会变成第三个参数，因为这个返回的 CancelFunc 不负责设置 cause。

父上下文更早取消时同样要看父级结果。父级的 deadline、主动取消或自定义 cause 会沿着派生关系传到子级；如果父级已有更早 deadline，子级配置的时间和 cause 都没有机会先触发。可以把下面的判断表放进排障清单：

日志和返回错误怎样保留两个层次

推荐让业务函数返回稳定的标准状态，让日志字段记录具体 cause。例如：

func checkContext(ctx context.Context) error {
    // 先等待取消，再分开记录状态和具体原因，避免字符串比较。
    

这样监控可以按 DeadlineExceeded 聚合，日志仍能区分是上游预算、批处理窗口还是请求截止时间。若业务代码确实需要主动传递自定义取消原因，应改用 context.WithCancelCause，而不是误以为 WithDeadlineCause 返回的普通 CancelFunc 也能接收原因。

常见问题

为什么 context.Cause(ctx) 还是 context deadline exceeded？

常见原因是使用了 WithDeadline 或 WithTimeout，没有配置 cause；也可能是父 context 先结束，子级的 cause 尚未触发。

调用 defer cancel() 会覆盖自定义 cause 吗？

如果 deadline 已经先触发，后面的 cancel() 不会覆盖已记录的原因。若 cancel 先发生，则它会让上下文以主动取消结束，不会写入第三个参数。

应该只记录 Cause 还是只记录 Err？

两者都记录更稳妥：Err 用于稳定分支和指标聚合，Cause 用于定位是哪一种业务预算或上游约束导致取消。

排查这类问题时，最后只确认一件事：到底是谁先关闭了 Done()。只要把触发者、Err() 和 Cause() 放在同一条日志里，超时就不会只剩下一句无法定位的通用报错。