Go / 系统课时
接入下游服务客户端
接入下游服务客户端
服务间调用真正需要控制的是失败的边界:一次下游请求可以失败,但不能因为无限等待或重复重试拖垮整条链路。本节实现一个可复用的 Go HTTP 客户端,让连接池长期复用、单次尝试有明确超时、所有重试共享同一份总 deadline,并把失败转换成稳定的上游语义。
学习目标
- 配置可复用的
http.Transport与http.Client,约束连接、TLS 握手和响应头等待时间 - 用请求级 deadline、有限重试和退避共同限制一次下游调用的总成本
- 将下游超时与不可用分别映射为稳定的
504与502结果
把总预算放在重试之外
单次请求超时和总调用 deadline 解决的是不同问题。http.Client.Timeout 限制每次 Do 从发起请求到读取响应体的总时长,而调用方传入的 context.Context 覆盖整个“尝试 → 退避 → 再尝试”过程。总 deadline 必须建立在重试循环外,后续尝试才能继续消耗同一份剩余预算,而不是每次重置计时。

http.Transport 也应长期复用,因为连接池、keep-alive 和空闲连接都由它维护。每次请求临时创建 Transport 会反复建连,既增加延迟,也更容易在故障时放大连接抖动。下面把建连、TLS 握手、响应头等待和空闲连接生命周期都限制在有限范围内。
实现受约束的下游客户端
示例在本机随机端口启动两个临时 HTTP 服务:第一个前两次返回 503、第三次成功;第二个故意迟迟不返回响应头。客户端只提供 GET 操作,因此具备幂等前提,并且最多尝试三次。
package main
import (
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net"
"net/http"
"sync/atomic"
"time"
)
var (
ErrDownstreamTimeout = errors.New("downstream timeout")
ErrDownstreamUnavailable = errors.New("downstream unavailable")
)
type quoteResponse struct {
Value string `json:"value"`
}
type downstreamClient struct {
httpClient *http.Client
baseURL string
maxAttempts int
}
func newDownstreamClient(baseURL string) *downstreamClient {
transport := &http.Transport{
Proxy: http.ProxyFromEnvironment,
DialContext: (&net.Dialer{Timeout: 200 * time.Millisecond, KeepAlive: 30 * time.Second}).DialContext,
ForceAttemptHTTP2: true,
MaxIdleConns: 50,
MaxIdleConnsPerHost: 20,
IdleConnTimeout: 60 * time.Second,
TLSHandshakeTimeout: 300 * time.Millisecond,
ResponseHeaderTimeout: 300 * time.Millisecond,
ExpectContinueTimeout: 100 * time.Millisecond,
}
return &downstreamClient{
httpClient: &http.Client{Transport: transport, Timeout: 500 * time.Millisecond},
baseURL: baseURL,
maxAttempts: 3,
}
}
func retryableStatus(status int) bool {
return status == http.StatusBadGateway ||
status == http.StatusServiceUnavailable ||
status == http.StatusGatewayTimeout
}
func sleepContext(ctx context.Context, d time.Duration) bool {
timer := time.NewTimer(d)
defer timer.Stop()
select {
case <-timer.C:
return true
case <-ctx.Done():
return false
}
}
func (c *downstreamClient) getQuote(ctx context.Context) (string, int, error) {
var lastErr error
for attempt := 1; attempt <= c.maxAttempts; attempt++ {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/quote", nil)
if err != nil {
return "", attempt, err
}
resp, err := c.httpClient.Do(req)
if err == nil {
if resp.StatusCode == http.StatusOK {
var payload quoteResponse
decodeErr := json.NewDecoder(io.LimitReader(resp.Body, 8<<10)).Decode(&payload)
resp.Body.Close()
if decodeErr != nil {
return "", attempt, fmt.Errorf("%w: invalid JSON", ErrDownstreamUnavailable)
}
return payload.Value, attempt, nil
}
// 只读取有限错误体;若未读到 EOF,连接可以被关闭而不是无限消耗内存。
_, _ = io.Copy(io.Discard, io.LimitReader(resp.Body, 4<<10))
resp.Body.Close()
if !retryableStatus(resp.StatusCode) {
return "", attempt, fmt.Errorf("%w: status=%d",
ErrDownstreamUnavailable, resp.StatusCode)
}
lastErr = fmt.Errorf("status=%d", resp.StatusCode)
} else {
if errors.Is(ctx.Err(), context.DeadlineExceeded) {
return "", attempt, ErrDownstreamTimeout
}
var netErr net.Error
if errors.As(err, &netErr) && netErr.Timeout() {
lastErr = ErrDownstreamTimeout
} else {
lastErr = err
}
}
if attempt == c.maxAttempts {
break
}
// 退避继续消耗同一份总 deadline;预算耗尽时立即停止。
if !sleepContext(ctx, time.Duration(attempt)*100*time.Millisecond) {
return "", attempt, ErrDownstreamTimeout
}
}
if errors.Is(ctx.Err(), context.DeadlineExceeded) ||
errors.Is(lastErr, ErrDownstreamTimeout) {
return "", c.maxAttempts, ErrDownstreamTimeout
}
return "", c.maxAttempts, fmt.Errorf("%w: %v", ErrDownstreamUnavailable, lastErr)
}
func upstreamResult(err error) (int, string) {
switch {
case err == nil:
return http.StatusOK, "ok"
case errors.Is(err, ErrDownstreamTimeout):
return http.StatusGatewayTimeout, "downstream_timeout"
default:
return http.StatusBadGateway, "downstream_unavailable"
}
}
func startLocalServer(handler http.Handler) (string, func(), error) {
ln, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
return "", nil, err
}
server := &http.Server{Handler: handler}
go func() {
_ = server.Serve(ln)
}()
closeServer := func() {
_ = server.Close()
}
return "http://" + ln.Addr().String(), closeServer, nil
}
func main() {
var calls atomic.Int32
transientURL, closeTransient, err := startLocalServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if calls.Add(1) < 3 {
http.Error(w, "temporary", http.StatusServiceUnavailable)
return
}
w.Header().Add("Content-Type", "application/json; charset=utf-8")
_ = json.NewEncoder(w).Encode(quoteResponse{Value: "42"})
}))
if err != nil {
panic(err)
}
defer closeTransient()
client := newDownstreamClient(transientURL)
ctx, cancel := context.WithTimeout(context.Background(), 900*time.Millisecond)
value, attempts, err := client.getQuote(ctx)
cancel()
status, code := upstreamResult(err)
fmt.Printf("transient: attempts=%d status=%d code=%s value=%s\n",
attempts, status, code, value)
slowURL, closeSlow, err := startLocalServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
select {
case <-time.After(2 * time.Second):
_ = json.NewEncoder(w).Encode(quoteResponse{Value: "late"})
case <-r.Context().Done():
}
}))
if err != nil {
panic(err)
}
defer closeSlow()
slowClient := newDownstreamClient(slowURL)
slowCtx, slowCancel := context.WithTimeout(context.Background(), 900*time.Millisecond)
_, _, err = slowClient.getQuote(slowCtx)
slowCancel()
status, code = upstreamResult(err)
fmt.Printf("slow: status=%d code=%s\n", status, code)
}预期输出
transient: attempts=3 status=200 code=ok value=42
slow: status=504 code=downstream_timeout实际随机端口和内部超时发生时刻可能不同,但这两行结果由示例中的重试次数和错误映射决定。
为什么重试没有放大故障
这个实现同时设置三道边界:最多三次尝试、每次请求自己的传输与客户端超时、以及覆盖全部尝试和退避的 900ms 调用 deadline。即使下游持续无响应,请求也不能因为“再试一次”无限延长;退避通过 select 监听 ctx.Done(),剩余预算不足时会直接退出。
状态码重试也保持保守,只处理 502、503、504。下游 4xx 通常表示请求语义、权限或资源状态有问题,重复发送不会自动变正确。对于 POST、扣款、发消息等非幂等写操作,更不能直接复用这条重试循环;只有协议明确提供幂等键或去重语义时,才适合设计受控重试。
把失败转换为稳定上游语义
调用方不应把 net/http 的底层错误文本直接暴露给 API 使用者。示例把总 deadline 或传输超时归一为 504 downstream_timeout,把其他下游失败归一为 502 downstream_unavailable;内部日志仍可保留原始错误用于定位 DNS、连接、TLS 或响应解析问题。
生产服务通常还会从上游请求的剩余预算派生下游 deadline,并补充并发上限、熔断、指标和追踪。核心边界不变:连接池长期复用,单次尝试有上限,所有重试共享总预算,只有明确安全且值得重试的失败才能进入下一次尝试。