📚 课程目录第4章 HTTP客户端超时设置

4、HTTP客户端超时设置：从requests到aiohttp的实践

说到HTTP客户端超时，很多同学第一反应就是「加个timeout参数就完事了」。真的这么简单吗？我个人习惯把超时看作一个分层防御体系——连接层、读取层、总时间层，每一层都有它的用武之地。你想想看，一个请求卡在那儿十分钟不动，整个系统的吞吐量全被它拖死，这种情况我在项目中见过太多次了。

4.1 requests库的timeout参数

requests库是Python最流行的HTTP客户端，它提供了直观的timeout机制。但这个参数有两张面孔：单一值和元组值。

import requests

# 方式1：单一超时（连接+读取共享同一个阈值）
resp = requests.get('https://api.example.com/data', timeout=5)

# 方式2：元组超时（分别控制连接和读取）
resp = requests.get('https://api.example.com/data', timeout=(3.0, 7.0))

# 方式3：完全不设超时（千万别这么做！）
resp = requests.get('https://api.example.com/data')  # 永远等待

我个人习惯用元组形式。第一个数字是连接超时，第二个是读取超时。连接超时一般设置2～5秒，读取超时根据接口响应特征来定，通常在10秒以内。

参数形式	含义	推荐场景
`timeout=5`	连接和读取总超时5秒	简单请求，响应时间稳定
`timeout=(3, 7)`	连接3秒，读取7秒	后端有跨区域服务，延迟波动大
`timeout=None`	不超时	不要用！

小技巧：如果你不确定该设多少，先从 (3, 10) 开始，观察生产环境的99分位响应时间，再逐步收紧。我曾经把一个内部工具的读取超时从30秒压到5秒，系统整体的平均响应时间反而降了一半。

4.2 urllib3的连接超时与读取超时

requests底层用的是urllib3，但直接与urllib3打交道的情况也不少——比如自定义连接池、HTTP代理、长连接管理。urllib3的超时配置更加细致。

import urllib3
from urllib3.util.timeout import Timeout

# 创建连接池管理器
http = urllib3.PoolManager(
    timeout=Timeout(connect=3.0, read=10.0),
    retries=2,
    maxsize=20
)

# 发起请求
resp = http.request('GET', 'https://api.example.com/data')

# 也可以按请求覆盖
resp = http.request(
    'GET', 'https://api.example.com/data',
    timeout=Timeout(connect=5.0, read=15.0)
)

特别注意：urllib3的Timeout对象还支持 total 参数，它限制了整个请求的最大时长，包括重试等待时间。我遇到过一种情况：连接超时设了3秒，读取超时设了10秒，但因为重试了3次，一个请求最终耗时快40秒，整个线程池被拖垮。设置 total 能兜底。

嗯，这里要说一个常见的坑。我在项目中遇到过CDN回源超时的排查问题，现象是客户端有时收到连接拒绝，有时正常。后来发现是urllib3连接池里闲置连接被远程关闭了，但客户端不知道。解决办法是结合传输适配器超时和连接健康检查一起用。

超时类型	urllib3参数	默认值	我的推荐值
连接超时	`connect`	3.0秒	2～5秒
读取超时	`read`	无	5～15秒
总超时	`total`	无	30～60秒

避坑指南：我曾经把连接池的 maxsize 从10改到200，想提升并发能力，结果发现大量连接处于 TIME_WAIT 状态，服务器端口被耗尽。后来我同时调整了 timeout 和 retries，才真正把连接池用起来。

4.3 aiohttp的异步超时配置

异步场景下，超时处理会更灵活，但也更容易被忽略。aiohttp提供了 ClientTimeout 对象，支持更细粒度的控制。

import aiohttp
import asyncio

# 创建自定义超时配置
timeout = aiohttp.ClientTimeout(
    total=30,        # 整个HTTP请求的总超时
    connect=5,       # 连接建立超时
    sock_connect=3,  # 套接字连接超时
    sock_read=10     # 套接字读取超时
)

async def fetch_data():
    async with aiohttp.ClientSession(timeout=timeout) as session:
        async with session.get('https://api.example.com/data') as resp:
            return await resp.json()

# 运行
data = asyncio.run(fetch_data())

    核心差异点：aiohttp的 sock_connect 和 sock_read 是针对每个连接尝试的超时，而 connect 和 read 是针对整个连接过程的超时。如果启用了连接池复用，sock_connect 几乎不会触发，这更符合实际场景。

为什么会异步还要关注超时？我曾经在压测环境里，几千个并发请求因为某个后端服务变慢，全部卡在读取阶段，event loop被阻塞，连心跳检测都超了。最后我在 ClientTimeout 里同时设置了 total 和 sock_read，才彻底解决问题。

aiohttp参数	作用层级	建议值
`total`	整体HTTP事务	30～60秒
`connect`	连接建立全过程	5～10秒
`sock_connect`	单次套接字连接	3～5秒
`sock_read`	单次套接字读取	10～20秒

4.4 三个库的超时策略对比

说到底，不管用哪个库，超时的本质没变：你希望系统在异常情况下优雅失败，而不是死等。我整理了一个对比表，帮你快速选择。

维度	requests	urllib3	aiohttp
连接超时分离	支持（元组）	支持（Timeout对象）	支持（sock_connect）
读取超时分离	支持（元组）	支持（Timeout对象）	支持（sock_read）
总超时兜底	不支持	支持（total参数）	支持（total参数）
超时后重试	需第三方库	内置retries机制	需手动实现
适用场景	同步简单请求	需要精细控制连接池	高并发异步场景

切记：无论用哪个库，永远不要省略timeout参数。我曾经接手过一个老项目，所有requests调用都没设超时，生产环境某次数据库故障引发上游服务响应缓慢，结果整个API网关的所有worker线程全部卡住，服务雪崩，恢复花了将近40分钟。

最后总结一句话：超时参数不是「加了就行」，而是要分层设置、结合场景、持续优化。从requests到urllib3再到aiohttp，每一层都提供了对应工具。你得根据你的服务架构、网络环境、容忍延迟，去找到那个最优解。我个人花了很多时间在超时调优上，但每次看到线上告警减少、系统更稳定，就觉得值了。