Go HTTP 请求超时怎么处理：context.WithTimeout 的最小配方与常见坑

线上接口偶尔卡到几十秒，最先需要确认的不是把 Nginx 超时再调大，而是这次请求有没有一条明确的截止时间。Go 开发里通常从入口请求的 Context 派生一个带超时的 Context，再把它传给 HTTP、数据库和内部函数；超时到点后，下游配合检查 ctx.Done()，调用链才会一起正常收口。

为什么设置了客户端超时，请求还可能拖住

一个常见误区是只写 http.Client{Timeout: 3 * time.Second}，然后默认业务链路已经有了超时兜底。这个字段能限制单次 HTTP 事务的总耗时，但它不会自动帮你取消数据库查询、内部计算或是其他没有接收 Context 的自定义函数。

更麻烦的情况是：入口请求已经给前端返回响应了，后台对应的 goroutine 仍然拿着请求相关数据继续空等。这类代码表面看起来没有报错，服务的连接数和 goroutine 数却会偷偷慢慢上涨。遇到这个问题先别急着改各类组件的超时参数，应该先把“谁负责结束等待”的逻辑明确写到函数签名和全链路调用路径里。

最小配方：给 HTTP 下游调用加上 WithTimeout

下面的例子模拟一个订单服务调用库存接口的常规场景。超时从入口请求派生，HTTP 请求使用同一个 Context；无论请求提前成功还是到点失败，defer cancel() 都会释放派生 Context 关联的计时资源。

package inventory

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

func CheckStock(parent context.Context, client *http.Client) error {
    ctx, cancel := context.WithTimeout(parent, 800*time.Millisecond)
    defer cancel()

    req, err := http.NewRequestWithContext(ctx, http.MethodGet,
        "https://inventory.example.test/stock/sku-42", nil)
    if err != nil {
        return err
    }

    resp, err := client.Do(req)
    if err != nil {
        return fmt.Errorf("库存请求失败: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return fmt.Errorf("库存接口返回状态 %s", resp.Status)
    }
    return nil
}

这里的核对点有三个：请求通过 http.NewRequestWithContext 绑定了 Context；client.Do 返回后关闭了响应体；错误保留了原始原因，日志里才能继续判断是超时、连接失败还是非 2xx 响应。

把同一个截止时间传过调用链

入口函数优先使用 r.Context()。业务层的方法把 ctx context.Context 放在第一个参数，仓储层和 RPC 客户端也遵循这个统一约定。这样上游主动取消时，所有正在等待的下游逻辑都能收到同一个信号。

func (s *OrderService) Create(ctx context.Context, sku string) error {
    if err := s.stock.Check(ctx, sku); err != nil {
        return err
    }
    return s.repo.Save(ctx, sku)
}

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
    defer cancel()

    if err := h.orders.Create(ctx, r.URL.Query().Get("sku")); err != nil {
        if ctx.Err() != nil {
            http.Error(w, "请求处理超时", http.StatusGatewayTimeout)
            return
        }
        http.Error(w, "订单处理失败", http.StatusBadGateway)
        return
    }
    w.WriteHeader(http.StatusCreated)
}

不要在 Check 或 Save 内部重新创建 context.Background()，那会直接切断上游的取消信号。也不要把 Context 塞进服务结构体里长期保存；它代表单次请求的生命周期，不属于服务的固定配置。

慢函数要自己监听 Done，否则超时只是表面动作

HTTP 客户端和多数主流数据库驱动已经原生支持 Context，但自定义的轮询、批处理或等待函数不一定做了适配。只要函数逻辑存在阻塞可能，就应当给等待点增加一个 select 分支。

func WaitForStock(ctx context.Context, ready 

如果函数内部还有循环逻辑，不能只在循环外检查一次取消信号。每轮处理前或是每个可能耗时的阶段都要检查一次取消状态；否则上游已经返回，当前 goroutine 仍会把剩余所有任务执行完。

三类错误怎么分，重试边界在哪里

超时不是“再试一次”的充分理由。付款、库存扣减这类有副作用的调用，重试前必须有幂等键或业务去重逻辑；查询类请求才更适合在剩余截止时间允许时做一次短重试。

常见问题：WithTimeout 的几个边界

父 Context 已经有更短的截止时间，会发生什么？

子 Context 不会把父 Context 的截止时间延后，实际生效的是更早的那个时间点。给下游设置 800 毫秒超时，并不代表它一定还能使用完整 800 毫秒的等待时长。

为什么每次 WithTimeout 都要 defer cancel？

请求提前完成时调用 cancel 可以停止关联计时器并解除子 Context 的引用。即使超时最终会自动触发，也不应把资源清理责任留给后台定时器。

context.Err() 什么时候才有值？

在 Done() 关闭后检查最可靠；返回 context.Canceled 表示主动取消，返回 context deadline exceeded 表示截止时间已到。

能不能把超时写在服务结构体里复用？

不建议。超时属于单次调用的生命周期，应从方法参数传入；结构体里保存固定时长配置可以，但不要保存某一次请求的 Context。

上线前的快速检查

• 入口是否从 r.Context() 派生超时，而不是从空 Context 开始？
• 所有 HTTP、数据库和 RPC 方法是否接收并继续传递 ctx？
• 自定义循环和等待点是否监听了 ctx.Done()？
• 是否记录了请求耗时、下游名称、截止时间和原始错误？
• 重试是否有幂等边界，并且不会超过父 Context 剩余时间？

把这几项放进接口回归测试后，超时就不再只是某个客户端参数，而会成为整条 Go 请求链路都能遵守的约束。