Go / 系统课时

接入下游服务客户端

接入下游服务客户端

服务间调用真正需要控制的是失败的边界:一次下游请求可以失败,但不能因为无限等待或重复重试拖垮整条链路。本节实现一个可复用的 Go HTTP 客户端,让连接池长期复用、单次尝试有明确超时、所有重试共享同一份总 deadline,并把失败转换成稳定的上游语义。

学习目标

  • 配置可复用的 http.Transport 与 http.Client,约束连接、TLS 握手和响应头等待时间
  • 用请求级 deadline、有限重试和退避共同限制一次下游调用的总成本
  • 将下游超时与不可用分别映射为稳定的 504 与 502 结果

把总预算放在重试之外

单次请求超时和总调用 deadline 解决的是不同问题。http.Client.Timeout 限制每次 Do 从发起请求到读取响应体的总时长,而调用方传入的 context.Context 覆盖整个“尝试 → 退避 → 再尝试”过程。总 deadline 必须建立在重试循环外,后续尝试才能继续消耗同一份剩余预算,而不是每次重置计时。

统一 deadline 约束多次下游 HTTP 尝试与退避

http.Transport 也应长期复用,因为连接池、keep-alive 和空闲连接都由它维护。每次请求临时创建 Transport 会反复建连,既增加延迟,也更容易在故障时放大连接抖动。下面把建连、TLS 握手、响应头等待和空闲连接生命周期都限制在有限范围内。

实现受约束的下游客户端

示例在本机随机端口启动两个临时 HTTP 服务:第一个前两次返回 503、第三次成功;第二个故意迟迟不返回响应头。客户端只提供 GET 操作,因此具备幂等前提,并且最多尝试三次。

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

预期输出

text
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,并补充并发上限、熔断、指标和追踪。核心边界不变:连接池长期复用,单次尝试有上限,所有重试共享总预算,只有明确安全且值得重试的失败才能进入下一次尝试。

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

目录与阅读设置

阅读设置

17

记录一个想法

接入下游服务客户端

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

登录哪都通