Go / 系统课时

规划代理链路超时预算

规划代理链路超时预算

一条 HTTP 请求可能连续经过客户端、反向代理、应用服务和下游依赖。超时预算若顺序反了,外层会先断开,而内层仍继续计算。合理设计应让最内层先失败,并给上层留下返回错误和清理资源的时间。

学习目标

  • 按客户端、代理、服务端和下游调用排列超时预算
  • 解释代理侧 502、504 与客户端本地超时的区别
  • 让请求取消沿上下文向下游传播,避免无效工作继续执行

先按谁先放弃排列预算

一个实用原则是:越靠近真正工作的内层,截止时间越早;越靠近用户的外层,等待时间越长。这样下游先失败,应用还能生成明确响应,代理还能把响应转发给客户端。

层级 示例上限 主要作用
下游调用 1.2 秒 尽快结束数据库或远程 API 等内部工作
应用请求 1.8 秒 汇总下游结果并生成业务响应
反向代理等待 2.3 秒 等待应用返回响应头或响应体
客户端总时限 2.8 秒 给网络传输和代理错误响应留出余量

这些数字不是固定模板。真正配置时要根据延迟分位数、重试次数和链路开销留安全余量,并优先从父请求的剩余截止时间继续向内收紧,而不是在每一层重新创建互不相关的长超时。

客户端到下游的分层超时预算

用代码观察代理超时

下面程序创建一个故意延迟 300 毫秒返回响应头的上游服务,再让反向代理只等待 100 毫秒。代理的 ErrorHandler 把超时明确映射为 504,其他传输错误映射为 502。

go
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))
}

预期输出

text
status=504 body="gateway timeout\n"

Go 的 httputil.ReverseProxy 默认错误处理会对代理传输失败返回 502;如果希望把等待上游超时单独呈现为 504,需要像示例这样按错误类型分类。不同代理产品的状态码映射可能不同,所以不能只凭一个 502 或 504 就断定根因。

让截止时间继续向下游传播

应用服务收到请求后,不应使用脱离入站请求的 context.Background() 去发起普通下游调用。更合适的做法是以 r.Context() 为父上下文,再用 context.WithTimeout 设置更短的下游上限;父截止时间更早时,子调用也会随父上下文一起取消。

这条规则能解决最常见的资源浪费:客户端已经断开,代理也停止等待,但应用仍在执行数据库查询、远程请求或昂贵计算。前提是下游库和业务代码真正接收并检查该上下文,而不是创建新的独立上下文把取消链截断。

用状态码和日志共同定位

502 更接近“网关没有得到可用的上游响应”,常见来源包括连接失败、连接重置、TLS 或协议错误;某些代理也会把传输层超时归到 502。504 则通常表示网关明确判断等待上游超时。若客户端自己的总时限先到,客户端可能直接得到超时错误而没有任何 HTTP 状态码。

验收预算时应主动制造三类故障:让下游先超时、让应用进程不可达、让客户端时限故意短于代理。确认每种情况下谁先取消、最终状态码或客户端错误是什么,并检查上游工作是否随取消停止。只要外层经常先于内层结束,就说明预算顺序或上下文传播仍需调整。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

规划代理链路超时预算

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通