Go 语言 context 超时与取消在 HTTP 调用链中的实战：从泄漏到可观测

一、问题从哪里来：超时只设在入口，等于没设

很多 Go 服务都配过 HTTP 超时：网关给下游 3 秒，上游给网关 5 秒，看起来每一环都有兜底。但线上仍然会出现这样的现象：客户端早已断开，下游还在跑一个 30 秒的查询；或者一个请求明明已经超时返回，下游服务却继续把结果写进数据库。原因不在超时时间本身，而在超时信号没有沿着调用链传下去。

Go 的 context 就是用来解决这个问题的：它把“截止时间、取消信号、请求级数据”打包成一个可以逐层传递的值。理解它的关键是：context 不是一个配置项，而是一条取消信号的传播链。任何一个环节不传递、不监听，这条链就断了。

二、context 的三件套：截止、取消、取值

context.Background() 是根，通常只在程序启动、后台任务等没有上游请求的场景使用。context.WithTimeout 和 context.WithCancel 会派生一个带取消函数的子 context，调用 cancel 会关闭子 context 的 Done 通道，所有监听它的 goroutine 都能收到信号。context.WithValue 则用来放请求级数据，比如 traceId、用户标识、租户标识，但只能放请求级、不可变的元数据，不能用来传业务参数，更不能放可变的大对象。

一个必须养成的习惯是：凡是 WithTimeout、WithCancel、WithDeadline，都要 defer cancel()。哪怕你觉得这次一定会正常返回，也不要省掉这一行。忘记 cancel 会导致内部的定时器和 goroutine 一直挂着，直到父 context 结束，这就是最常见的 context 泄漏来源之一。

三、HTTP 调用链的正确写法

在服务端，标准库已经把请求 context 做好了：r.Context() 会在客户端断开、请求超时时自动取消。问题出在我们经常把它丢掉，改用 context.Background() 去调下游。正确的做法是把请求 context 原样传下去，并在需要更严格超时时派生一个带超时的子 context：

func (s *Service) GetOrder(ctx context.Context, id string) (*Order, error) {
    ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
    defer cancel()
    req, err := http.NewRequestWithContext(ctx, http.MethodGet, s.base+"/orders/"+id, nil)
    if err != nil {
        return nil, err
    }
    resp, err := s.client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()
    // 解析响应并返回
    return decodeOrder(resp.Body)
}

这里有两个容易混淆的超时。http.Client.Timeout 是整个请求的总超时，包括建连、发请求、读响应；而 context 超时可以做到更精细的控制，比如“只给这次下游调用 2 秒”，并且可以在超时后立刻取消正在进行的数据库查询、RPC 调用。两者可以共存，但要分清各自的边界，不要用一个笼统的客户端超时代替调用链上的 context 传递。

四、取消信号要传到最底层才算数

只在 HTTP 层传 context 是不够的。数据库查询、缓存访问、消息发送都要接受 context，并在循环、批量处理中定期检查 ctx.Err()。否则上游已经取消，下游还在循环里跑完一万条记录。

一个实用的检查模式是：在长循环、分页拉取、重试循环的每次迭代开始时先判断一次：

for _, item := range items {
    select {
    case <-ctx.Done():
        return ctx.Err()
    default:
    }
    // 处理 item
}

同时要区分三种不同的取消原因，它们在日志和指标里应该分开统计：context.DeadlineExceeded 是超时，context.Canceled 是上游或客户端主动取消，而调用方主动 cancel 派生 context 也会得到 context.Canceled。把三者混成一个“请求失败”打进日志，排障时就很难判断到底是下游慢、上游断开，还是自己的代码提前取消。

五、不要把 context 当成万能口袋

WithValue 的滥用是另一类常见问题。把数据库连接、配置对象、业务实体塞进 context，看起来调用方便，实际上破坏了函数签名的可读性，也让测试变得困难：一个函数到底依赖什么，不看调用方根本不知道。我的原则是：context 里只放 traceId、请求 Id、租户 Id 这类贯穿全链路的元数据，业务参数一律用函数参数显式传递。

另外，context 的值应该是不可变的。不要在 context 里放指针指向的可变结构体，然后在下游偷偷修改它——这会让并发下的行为变得不可预测，也违背了 context 作为“请求级只读快照”的设计。

六、让超时和取消变得可观测

超时问题最难的不是修复，而是发现。建议在三个地方统一埋点：第一，入口处把 traceId 写入 context，并在所有日志里带上它，这样一次请求的完整链路可以按 traceId 串起来；第二，出口处记录下游调用的耗时、是否超时、是否被取消，用指标区分 DeadlineExceeded 和 Canceled；第三，对超时率、取消率设告警阈值，而不是只看平均耗时——平均耗时可能很好看，但 P99 和超时率已经在悄悄恶化。

上线前值得做一次演练：把下游接口人为延迟到超过超时时间，检查三件事：上游是否按时返回超时错误，下游是否真的停止了后续写入，日志里是否能按 traceId 找到这一次完整的取消链路。如果这三件事都成立，context 才算真正接通了；否则只是代码里出现了 context 这个参数，信号并没有真正传下去。

七、检查清单

收尾时把这套做法收敛成清单：入口 context 不丢弃、不替换成 Background；派生超时 context 一律 defer cancel；HTTP、数据库、RPC 调用全部接受 context；长循环和重试中定期检查 ctx.Err；超时、客户端取消、主动取消分开统计；context 只放不可变的请求级元数据。把这份清单过一遍，Go 服务在超时和取消面前才不会一边已经断开，另一边还在默默跑。