Python requests 超时与重试实战：Session 连接池这样配置更稳

Python 项目里调用外部 API 很常见：查物流、发短信、调支付、同步第三方系统。问题在于，很多代码只写了 requests.get(url)，没有超时、没有重试、没有连接池。平时看不出风险，一旦外部接口变慢，服务线程就会被长时间挂住，接口延迟和错误率一起上升。

本文用一个外部数据接口调用场景，完整演示 requests 的超时设置、Session 连接池、重试策略和慢调用日志。目标是让外部依赖“慢可以慢，但不能把自己的服务拖死”。

摘要

稳定的外部 API 调用至少要做到四件事：每次请求必须设置连接超时和读取超时；复用 Session 减少 TCP 握手成本；只对合适的错误做有限重试；记录耗时、状态码、重试次数和异常类型，方便定位是网络慢、服务端慢还是响应读取慢。

适合人群

适合正在写 Python 后端服务、脚本任务、数据同步、爬取工具或第三方接口封装的开发者。示例基于 requests 和 urllib3 的常见配置，能直接放进项目里的客户端封装层。

目录

1. 为什么不能裸用 requests.get
2. connect timeout 和 read timeout 的区别
3. 封装一个可复用的 Session 客户端
4. 配置有限重试和连接池
5. 记录日志定位慢调用
6. 常见坑与生产建议

一、为什么不能裸用 requests.get

裸调用最大的问题是默认没有明确超时。如果外部服务迟迟不返回，当前工作线程会一直等待。在线服务里，这会导致线程池被占满；批处理任务里，这会导致任务卡住很久；定时任务里，还可能造成下一轮任务堆积。

import requests

# 不推荐：没有 timeout，外部服务慢时容易拖住当前任务
resp = requests.get("https://api.example.com/data")
data = resp.json()

更稳妥的做法是给每个请求设置超时，并把外部 API 调用统一封装，避免业务代码到处散落不同的参数。

二、connect timeout 和 read timeout 的区别

requests 的 timeout 可以传一个二元组：(connect_timeout, read_timeout)。

• connect timeout：建立连接阶段的最大等待时间，包括 DNS、TCP 连接等；
• read timeout：连接已建立后，等待服务端返回数据的最大时间；
• 连接超时通常说明网络、域名解析、防火墙或对方端口有问题；
• 读取超时更多说明对方服务处理慢、响应体太大或链路拥塞。

import requests

timeout = (2.0, 5.0)  # 连接最多等 2 秒，读取最多等 5 秒
resp = requests.get("https://api.example.com/data", timeout=timeout)
resp.raise_for_status()
print(resp.json())

三、封装一个可复用的 Session 客户端

Session 可以复用连接池、Cookie 和部分请求配置。对于服务端项目，建议每个外部系统封装一个客户端对象，而不是每次请求都临时创建。

import logging
import time
from typing import Any

import requests

logger = logging.getLogger(__name__)


class ApiClient:
    def __init__(self, base_url: str, timeout: tuple[float, float] = (2.0, 5.0)):
        self.base_url = base_url.rstrip("/")
        self.timeout = timeout
        self.session = requests.Session()

    def get_json(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
        url = f"{self.base_url}{path}"
        start = time.perf_counter()
        try:
            response = self.session.get(url, params=params, timeout=self.timeout)
            response.raise_for_status()
            return response.json()
        except requests.exceptions.Timeout as err:
            logger.warning("api timeout url=%s params=%s error=%s", url, params, err)
            raise
        except requests.exceptions.RequestException as err:
            logger.warning("api request failed url=%s params=%s error=%s", url, params, err)
            raise
        finally:
            cost_ms = round((time.perf_counter() - start) * 1000, 2)
            logger.info("api request done url=%s cost_ms=%s", url, cost_ms)

这里把超时、状态码检查、异常日志、耗时统计都放到客户端里，业务层只关心调用结果。

四、配置有限重试和连接池

重试不是越多越好。适合重试的通常是临时网络错误、部分 5xx、429 限流；不适合重试的是参数错误、鉴权失败、业务校验失败。重试次数要有限，退避时间要逐步增加。

from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry


def build_session() -> requests.Session:
    retry = Retry(
        total=3,
        connect=2,
        read=2,
        backoff_factor=0.5,
        status_forcelist=[429, 500, 502, 503, 504],
        allowed_methods=["GET", "HEAD", "OPTIONS"],
        raise_on_status=False,
    )

    adapter = HTTPAdapter(
        max_retries=retry,
        pool_connections=20,
        pool_maxsize=50,
        pool_block=True,
    )

    session = requests.Session()
    session.mount("http://", adapter)
    session.mount("https://", adapter)
    return session

pool_connections 表示连接池缓存的主机数量，pool_maxsize 表示每个连接池的最大连接数。并发较高时建议显式配置，否则默认连接池可能成为隐藏瓶颈。

五、记录日志定位慢调用

只知道“请求慢”是不够的。排查时需要知道慢在哪个阶段：DNS、TCP、TLS、对方服务处理、响应读取。虽然 requests 默认不直接给出所有阶段耗时，但我们至少可以记录总耗时、状态码、异常类型、请求参数摘要和重试次数。

def safe_get_user(client: ApiClient, user_id: int) -> dict[str, Any]:
    try:
        return client.get_json("/users/detail", {"user_id": user_id})
    except requests.exceptions.ConnectTimeout:
        return {"ok": False, "reason": "connect_timeout"}
    except requests.exceptions.ReadTimeout:
        return {"ok": False, "reason": "read_timeout"}
    except requests.exceptions.HTTPError as err:
        return {"ok": False, "reason": f"http_error:{err.response.status_code}"}
    except requests.exceptions.RequestException:
        return {"ok": False, "reason": "request_error"}

如果服务对稳定性要求高，可以在失败时返回降级数据、默认配置或缓存结果，并把失败详情写入日志和监控系统。

六、常见坑与生产建议

1. 只设置一个 timeout 数字

timeout=5 虽然比不设置好，但无法区分连接阶段和读取阶段。生产更推荐写成 timeout=(2.0, 5.0)，便于后续排查。

2. 对所有请求都重试

POST、支付、下单、扣库存等接口要特别谨慎。如果接口本身没有幂等能力，重试可能造成重复操作。优先只对查询类 GET 接口开启自动重试。

3. 每次都创建新的 Session

频繁创建连接会增加 TCP 和 TLS 成本。服务进程里建议复用客户端对象，让连接池发挥作用。

4. 重试次数太多

重试会放大流量。外部服务已经抖动时，过多重试可能让对方更慢，也让自己的接口延迟更高。建议设置较小次数，并配合熔断或降级。

七、总结

Python 外部 API 调用要追求可控：明确超时，避免无限等待；复用 Session 和连接池，减少连接成本；对有限错误做有限重试，避免放大故障；记录结构化日志和关键指标，让慢调用可以被定位。把这些封装到统一客户端里，比在业务代码里零散补参数更可靠。