Go / 系统课时
规划代理链路超时预算
规划代理链路超时预算
一条 HTTP 请求可能连续经过客户端、反向代理、应用服务和下游依赖。超时预算若顺序反了,外层会先断开,而内层仍继续计算。合理设计应让最内层先失败,并给上层留下返回错误和清理资源的时间。
学习目标
- 按客户端、代理、服务端和下游调用排列超时预算
- 解释代理侧 502、504 与客户端本地超时的区别
- 让请求取消沿上下文向下游传播,避免无效工作继续执行
先按谁先放弃排列预算
一个实用原则是:越靠近真正工作的内层,截止时间越早;越靠近用户的外层,等待时间越长。这样下游先失败,应用还能生成明确响应,代理还能把响应转发给客户端。
| 层级 | 示例上限 | 主要作用 |
|---|---|---|
| 下游调用 | 1.2 秒 | 尽快结束数据库或远程 API 等内部工作 |
| 应用请求 | 1.8 秒 | 汇总下游结果并生成业务响应 |
| 反向代理等待 | 2.3 秒 | 等待应用返回响应头或响应体 |
| 客户端总时限 | 2.8 秒 | 给网络传输和代理错误响应留出余量 |
这些数字不是固定模板。真正配置时要根据延迟分位数、重试次数和链路开销留安全余量,并优先从父请求的剩余截止时间继续向内收紧,而不是在每一层重新创建互不相关的长超时。

用代码观察代理超时
下面程序创建一个故意延迟 300 毫秒返回响应头的上游服务,再让反向代理只等待 100 毫秒。代理的 ErrorHandler 把超时明确映射为 504,其他传输错误映射为 502。
package main
import (
"context"
"errors"
"fmt"
"io"
"net"
"net/http"
"net/http/httptest"
"net/http/httputil"
"net/url"
"time"
)
func isTimeout(err error) bool {
if errors.Is(err, context.DeadlineExceeded) {
return true
}
var ne net.Error
return errors.As(err, &ne) && ne.Timeout()
}
func main() {
upstream := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
// 下游必须监听请求上下文,代理放弃后即可停止无效工作。
select {
case <-time.After(300 * time.Millisecond):
_, _ = io.WriteString(w, "upstream ok")
case <-r.Context().Done():
return
}
}))
defer upstream.Close()
target, _ := url.Parse(upstream.URL)
proxy := httputil.NewSingleHostReverseProxy(target)
// 代理只给上游 100ms 等待响应头,短于客户端 500ms 的总预算。
proxy.Transport = &http.Transport{
ResponseHeaderTimeout: 100 * time.Millisecond,
}
proxy.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
if isTimeout(err) {
http.Error(w, "gateway timeout", http.StatusGatewayTimeout)
return
}
http.Error(w, "bad gateway", http.StatusBadGateway)
}
gateway := httptest.NewServer(proxy)
defer gateway.Close()
client := &http.Client{Timeout: 500 * time.Millisecond}
resp, err := client.Get(gateway.URL)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Printf("status=%d body=%q\n", resp.StatusCode, string(body))
}预期输出
status=504 body="gateway timeout\n"Go 的 httputil.ReverseProxy 默认错误处理会对代理传输失败返回 502;如果希望把等待上游超时单独呈现为 504,需要像示例这样按错误类型分类。不同代理产品的状态码映射可能不同,所以不能只凭一个 502 或 504 就断定根因。
让截止时间继续向下游传播
应用服务收到请求后,不应使用脱离入站请求的 context.Background() 去发起普通下游调用。更合适的做法是以 r.Context() 为父上下文,再用 context.WithTimeout 设置更短的下游上限;父截止时间更早时,子调用也会随父上下文一起取消。
这条规则能解决最常见的资源浪费:客户端已经断开,代理也停止等待,但应用仍在执行数据库查询、远程请求或昂贵计算。前提是下游库和业务代码真正接收并检查该上下文,而不是创建新的独立上下文把取消链截断。
用状态码和日志共同定位
502 更接近“网关没有得到可用的上游响应”,常见来源包括连接失败、连接重置、TLS 或协议错误;某些代理也会把传输层超时归到 502。504 则通常表示网关明确判断等待上游超时。若客户端自己的总时限先到,客户端可能直接得到超时错误而没有任何 HTTP 状态码。
验收预算时应主动制造三类故障:让下游先超时、让应用进程不可达、让客户端时限故意短于代理。确认每种情况下谁先取消、最终状态码或客户端错误是什么,并检查上游工作是否随取消停止。只要外层经常先于内层结束,就说明预算顺序或上下文传播仍需调整。