Go context 超时了为什么下游请求还没停

我排查 Go 接口超时时，最容易误判的一幕是：入口请求已经返回超时，但下游 HTTP 调用的日志还在继续打印。问题通常不在 context.WithTimeout 本身，而在超时信号没有沿着调用链传给真正执行工作的那一层。

Go 的 context 取消是协作式的。只有下游 API 接收并使用同一个 context，或者业务代码主动监听 ctx.Done()，超时才有机会让工作提前结束。

这次我把原因收敛成三类：请求创建时没有绑定 context；下游函数虽然收到了 context，却在内部换成了 context.Background()；自定义等待或重试逻辑没有监听取消信号。下面按这条调用链拆开看。

超时信号为什么会在下游丢失

context 不是一个会强制杀掉 goroutine 的开关，它携带截止时间、取消信号和请求级数据。父 context 到期后，派生 context 会一起进入取消状态，但下游必须读取这个状态或把它交给支持 context 的 API。

因此，单独写出 ctx, cancel := context.WithTimeout(...) 并不能保证网络请求会停。下面两种写法看起来只差一行，实际已经切断了取消链：

// 错误示例：请求没有绑定带超时的 ctx，超时只影响外层逻辑。
req, err := http.NewRequest(http.MethodGet, targetURL, nil)
if err != nil {
    return err
}
resp, err := client.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close()

如果下游函数内部重新使用 context.Background()，效果也一样：它创建了一个和当前请求无关的新根 context。排查时可以沿函数参数向下追，看到 Background、TODO 或重新创建的超时，就先检查这里。

HTTP 请求要从创建时绑定 context

我现在处理这类问题，会把“带 context 的请求”作为函数边界，而不是在调用 client.Do 前临时补救。http.NewRequestWithContext 会把 context 放进请求对象，net/http 执行请求时才知道何时应停止等待。

package main

import (
    "context"
    "errors"
    "fmt"
    "net/http"
    "time"
)

func fetch(ctx context.Context, client *http.Client, targetURL string) error {
    // 让请求继承调用方的截止时间和取消信号，不要在这里改用 Background。
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, targetURL, nil)
    if err != nil {
        return fmt.Errorf("create request: %w", err)
    }

    // Do 会在请求 context 取消时结束等待；响应存在时仍要关闭 Body。
    resp, err := client.Do(req)
    if err != nil {
        if errors.Is(err, context.DeadlineExceeded) {
            return fmt.Errorf("downstream timeout: %w", err)
        }
        if errors.Is(err, context.Canceled) {
            return fmt.Errorf("downstream canceled: %w", err)
        }
        return fmt.Errorf("downstream request: %w", err)
    }
    defer resp.Body.Close()

    // 这里只示范请求边界；生产代码还应按业务检查状态码和响应大小。
    if resp.StatusCode >= http.StatusBadRequest {
        return fmt.Errorf("downstream status: %s", resp.Status)
    }
    return nil
}

func main() {
    // 上层决定总预算，下游只负责继承，不偷偷延长预算。
    ctx, cancel := context.WithTimeout(context.Background(), 800*time.Millisecond)
    defer cancel()
    _ = fetch(ctx, http.DefaultClient, "https://example.com/health")
}

这里的关键不是把超时时间写成 800 毫秒，而是把同一个 ctx 传给 NewRequestWithContext。如果函数还会调用数据库、RPC 或消息客户端，也应优先选择它们的 ...Context 版本。

自定义等待和重试也要听取消信号

实际项目里，下游不一定是一个直接的 HTTP 调用，也可能是轮询、重试、等待队列或读取内部 channel。只传参数而不监听 Done，同样会出现“上游超时、下游继续跑”。

func waitResult(ctx context.Context, results 

重试代码尤其容易遗漏这一点：每次 sleep、退避等待和发起下一次请求前，都应该重新检查 context。否则第一轮请求可能已经被取消，重试循环却继续消耗资源。

如何区分 DeadlineExceeded 和 Canceled

调用方预算耗尽时，通常可以通过 context.DeadlineExceeded 判断；上游主动结束请求或手动调用 cancel 时，则更接近 context.Canceled。不过网络库可能会把原始错误包在更外层，判断时用 errors.Is，不要只比较字符串。

func classify(ctx context.Context, err error) string {
    // 先看调用返回的错误，再用 ctx.Err() 补充当前上下文状态。
    switch {
    case errors.Is(err, context.DeadlineExceeded) || errors.Is(ctx.Err(), context.DeadlineExceeded):
        return "timeout"
    case errors.Is(err, context.Canceled) || errors.Is(ctx.Err(), context.Canceled):
        return "canceled"
    default:
        return "other"
    }
}

拿到错误后不要继续读取可能已经失效的响应，也不要为了“等下游自己结束”而启动第二个不受控的 goroutine。记录请求 ID、阶段名称和 ctx.Err()，通常比打印一串重复的“超时”更容易定位断点。

这类超时排查的边界

context 只能请求协作方停止，不能从外部强制终止任意阻塞的第三方函数。如果第三方库没有 context 参数，也没有可关闭的连接或句柄，就只能查看它是否提供独立的超时配置、关闭方法或替代 API；把它包进 goroutine 并等待超时，并不会自动停止里面的工作。

我会按下面顺序复查：先看入口是否派生了带预算的 context；再看每个下游函数是否原样传参；接着查 HTTP、SQL、RPC 是否使用了带 Context 的调用；最后检查自定义循环、sleep、channel 等待和重试是否监听 Done。只有这四层都连上，超时才会真正贯穿请求链。

常见问题

只给 http.Client 设置 Timeout 还需要 context 吗？

客户端总超时可以作为兜底，但它不能替代请求级 context。请求级 context 能继承上游取消，并且可以把同一份预算传给数据库、RPC 和其他工作。

为什么 ctx 已经超时，业务 goroutine 还存在？

因为 context 不会强杀 goroutine。goroutine 必须在等待点、循环或调用的 API 中主动观察 ctx.Done() 或 ctx.Err()。

下游函数应该自己再创建一个更长的超时吗？

通常不应该偷偷延长上游预算。若业务确实需要分阶段预算，应明确派生子 context，并保证它不会晚于父 context 结束。

怎么快速判断是不是 context 没传下去？

从真正发起 I/O 的那一行反向检查：HTTP 请求是否由 NewRequestWithContext 创建，数据库是否调用 QueryContext 等方法，自定义等待是否有 分支。看到 Background() 或没有 context 参数时，优先处理它。