HTTPX Limits 怎么分别限制连接池和空闲连接数量

如果 HTTPX 客户端需要控制连接池，真正要看的不是一个“连接数”开关，而是 httpx.Limits 中的三个参数：max_connections 控制允许的最大连接数，max_keepalive_connections 控制最多保留多少条空闲 keep-alive 连接，keepalive_expiry 控制空闲连接保留多久。它们负责连接池资源管理，不负责请求重试或请求超时。

官方地址：https://www.python-httpx.org/advanced/resource-limits/

HTTPX 官方文档给出的默认值分别是 100、20 和 5 秒。实际项目中可以先按并发压力设置总连接上限，再按复用价值设置空闲上限和回收时间。

先把三个限制放回连接池

可以把连接池想成一个同时管理“正在使用”和“暂时空闲”的资源盒子。max_connections 是整个连接池允许使用的总上限；max_keepalive_connections 只关注请求完成后仍可复用的空闲连接；keepalive_expiry 则决定一条空闲 keep-alive 连接最多闲置多久。

因此，空闲连接上限不是总连接上限的替代品：前者影响连接复用的“库存”，后者约束连接池的总体规模。配置上通常让 max_keepalive_connections 不大于 max_connections，这样参数意图更清楚。

用一段最小配置绑定 Client

同步客户端可以直接把 Limits 传给 Client。下面的配置把总连接数限制为 20 条，最多保留 5 条空闲连接，空闲超过 10 秒后不再保留：

import httpx

# 总连接数限制并发资源，空闲连接限制复用库存，过期时间负责回收闲置连接。
limits = httpx.Limits(
    max_connections=20,
    max_keepalive_connections=5,
    keepalive_expiry=10.0,
)

# 复用同一个 Client，让连接池真正跨请求发挥作用。
with httpx.Client(limits=limits, timeout=10.0) as client:
    response = client.get("https://example.com/")
    response.raise_for_status()
    print(response.status_code)

这里的 timeout=10.0 只是示意请求超时配置，和三个 Limits 参数是两套边界。不要因为连接池排队或连接数量受限，就把 timeout 当成并发控制器。

按任务调整总连接与空闲连接

如果服务需要更高并发，先问“同时允许多少连接存在”，再问“请求完成后要保留多少连接等待复用”。前者对应 max_connections，后者对应 max_keepalive_connections。短时突发、目标主机较少的客户端，可以适当提高空闲保留数；请求很分散或连接长期闲置时，则应缩短 keepalive_expiry 或降低空闲上限。

三个参数也都允许使用 None 表示不设对应限制，但这不等于“应该全部设为 None”。生产配置仍要结合上游服务容量、进程资源和连接复用价值来决定，先给出明确上限通常更容易观察。

同步与异步客户端都复用同一组思路

AsyncClient 也接受同一个 limits 参数。异步代码中重点仍然是把客户端生命周期放在合适的范围内，而不是每个请求都创建新客户端：

import httpx

async def fetch(url: str) -> str:
    # 异步客户端沿用同一组连接池限制，参数含义不会因 async 改变。
    limits = httpx.Limits(
        max_connections=50,
        max_keepalive_connections=10,
        keepalive_expiry=15.0,
    )
    async with httpx.AsyncClient(limits=limits) as client:
        response = await client.get(url)
        response.raise_for_status()
        return response.text

这个函数展示的是参数绑定方式。若应用会连续发起多次请求，更适合在应用生命周期内复用一个 AsyncClient，并在生命周期结束时关闭它；不要把连接池限制和重试策略混在同一段配置里。

几个容易混淆的边界

• 总连接数不等于空闲连接数。前者是连接池整体上限，后者只统计可复用的空闲连接。
• 空闲过期时间不等于请求超时。keepalive_expiry 针对空闲 keep-alive 连接，timeout 针对请求阶段。
• 限制连接池不等于自动重试。连接数量不足时，应用仍应单独设计超时、排队和错误处理策略。
• 不要只创建一次 Limits 就忽略客户端生命周期。真正产生连接复用的是长期复用的 Client 或 AsyncClient。

常见问题

只想限制空闲连接，能把 max_connections 设为 None 吗？

可以。HTTPX 文档将 None 定义为不设对应限制，但是否适合这样做要看进程资源和上游服务容量；如果总连接数也不设上限，突发并发可能失去清晰的资源边界。

keepalive_expiry 设得很大是不是一定更快？

不一定。它只延长空闲连接的保留时间，可能提高后续复用机会，也可能让空闲资源占用更久。应结合请求间隔和上游连接策略选择，而不是单独追求更大的数值。

记住一条配置顺序即可：先用 max_connections 定总规模，再用 max_keepalive_connections 定复用库存，最后用 keepalive_expiry 定空闲回收节奏。