Go context deadline exceeded 怎样区分上游还是本地超时

看到 context deadline exceeded，先不要急着把所有超时都归到当前服务。ctx.Err() 只说明你检查的这个上下文已经因为截止时间结束；要区分本地总预算和上游调用预算，应该给不同层的超时绑定不同原因，再结合返回错误判断。

先把 deadline exceeded 拆成两类

一个请求通常有两层时间限制：入口请求给整个业务流程的总预算，例如 800 毫秒；调用数据库、HTTP 服务或 RPC 上游时，又给单个阶段设置 300 毫秒预算。两层都可能最终表现为 context.DeadlineExceeded，但处理动作不同：本地预算耗尽要减少当前流程工作，上游预算耗尽则应检查远端、代理或该阶段的参数。

Context.Err() 在 Done() 关闭后返回 context.DeadlineExceeded 或 context.Canceled。它不是调用链追踪器，所以不能仅靠比较这个错误的字符串来定位来源。Go 官方 context 包提供的 cause API，正好用来给不同预算留下标签。

给本地超时绑定明确的 cause

本地预算不要只写一个裸的 WithTimeout。如果这个预算代表“当前服务留给上游阶段的时间”，可以定义一个包级哨兵错误，并用 WithTimeoutCause 生成子上下文：

package main

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

var errLocalBudget = errors.New("local service budget exhausted")

func doWork(parent context.Context) error {
	ctx, cancel := context.WithTimeoutCause(parent, 800*time.Millisecond, errLocalBudget)
	defer cancel() // 及时释放定时器和子上下文资源。

	select {
	case 

如果外层的父上下文提前结束，子上下文会跟着结束，context.Cause(ctx) 通常会继承父级 cause；如果是这里设置的 800 毫秒到期，则能命中 errLocalBudget。因此，日志要保留 cause，而不是只打印 err.Error() 后再做字符串包含判断。

为上游调用单独设置预算并返回来源

上游阶段也应有自己的哨兵错误。下面的示例把“上游预算耗尽”和“外层本地预算耗尽”放在不同的错误分支里；外层调用者收到错误后，可以直接知道是哪个阶段先结束。

var errUpstreamBudget = errors.New("upstream request budget exhausted")

func callUpstream(parent context.Context) error {
	upstreamCtx, cancel := context.WithTimeoutCause(parent, 300*time.Millisecond, errUpstreamBudget)
	defer cancel() // 上游返回后停止仍可能存在的计时器。

	if err := simulatedRequest(upstreamCtx); err != nil {
		if errors.Is(err, context.DeadlineExceeded) || errors.Is(err, errUpstreamBudget) {
			// 只把本阶段的 cause 暴露给调用方，保留上游来源。
			return fmt.Errorf("upstream timeout: %w", context.Cause(upstreamCtx))
		}
		return fmt.Errorf("upstream request failed: %w", err)
	}
	return nil
}

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

生产代码中的 HTTP 客户端、数据库驱动或 RPC 客户端应真正把 upstreamCtx 传进去。若它们自己返回了带有远端状态的错误，要同时保留该错误和当前上下文 cause；不能因为看到 context deadline exceeded 就断定远端服务已经超时。

按调用链记录，避免误判

排查时至少记录四个字段：入口请求的 deadline、当前阶段开始时间、当前阶段子上下文的 cause，以及上游返回错误。创建子上下文后应继续向下传递，不能在中途改用 context.Background()，否则上游会失去父级取消信号。

func handle(ctx context.Context) error {
	if deadline, ok := ctx.Deadline(); ok {
		// 记录入口剩余时间，帮助判断是否在进入上游前已所剩不多。
		fmt.Println("deadline:", deadline)
	}

	if err := callUpstream(ctx); err != nil {
		// 先区分上游预算，再检查入口上下文是否已结束。
		if errors.Is(err, errUpstreamBudget) {
			return err
		}
		if errors.Is(ctx.Err(), context.DeadlineExceeded) {
			return fmt.Errorf("request budget exhausted: %w", errLocalBudget)
		}
		return err
	}
	return nil
}

这里的顺序很重要：先查看阶段错误，再查看父上下文。父级可能在上游返回错误的同时到期，单看最后一次 ctx.Err() 会把两个事件混为一谈。若链路有反向代理，还要分别记录“客户端到代理”和“代理到上游”的预算。

上线前的超时排查清单

1. 为本地总预算、数据库预算、HTTP/RPC 预算使用不同的 cause 错误。
2. 每次创建带 timeout 或 deadline 的上下文都 defer cancel()。
3. 把子上下文传给真正执行 I/O 的客户端，不要传回没有 deadline 的背景上下文。
4. 同时记录 ctx.Err()、context.Cause(ctx)、上游返回错误和阶段耗时。
5. 用 errors.Is 判断哨兵错误，不要用字符串前缀猜测来源。

最终判断可以压缩成一句话：当前上下文的 cause 命中哪一个预算，就优先归因于哪一层；如果只有上游返回超时而父上下文仍正常，则把它当作上游阶段问题继续排查。

常见问题

只用 errors.Is(err, context.DeadlineExceeded) 能知道是谁超时吗？

不能。它只能判断错误属于 deadline exceeded 类别，来源需要靠不同层的 cause 或上游错误包装补充。

WithTimeoutCause 的 cancel 调用会覆盖自定义 cause 吗？

不会。主动调用返回的 CancelFunc 会结束上下文，但不会为已经设置的 deadline cause 改写原因；仍应及时调用它释放资源。