httpx.AsyncClient 如何设置连接池大小与最大空闲连接

httpx.AsyncClient 的连接池参数名是 limits，需传入 httpx.Limits 对象来配置 max_connections、max_keepalive_connections 和 keepalive_expiry。

httpx.AsyncClient 的连接池参数名是什么

httpx.AsyncClient 不提供类似 max_pool_size 这样的顶层参数，实际控制连接池的是底层 httpcore.AsyncConnectionPool 实例，需通过 limits 参数传入 httpx.Limits 对象。常见误区是试图设置 pool_limits 或直接传字典——这会静默失效或报错。

如何用 Limits 控制并发连接与空闲连接

httpx.Limits 有三个关键字段：max_connections（总并发上限）、max_keepalive_connections（最大空闲连接数）、keepalive_expiry（空闲连接存活秒数）。它们共同决定连接复用行为：

• max_connections 是硬上限，超出会抛 httpx.PoolTimeout
• max_keepalive_connections 必须 ≤ max_connections，否则启动时就报 ValueError
• keepalive_expiry 默认 5.0 秒，设为 0 表示禁用 keep-alive（不推荐）

示例：

import httpx

client = httpx.AsyncClient(
    limits=httpx.Limits(
        max_connections=100,
        max_keepalive_connections=20,
        keepalive_expiry=30.0
    )
)

为什么设置了 max_keepalive_connections 却没看到空闲连接复用

空闲连接复用依赖两个条件同时满足：

• 请求目标 URL 的 host:port 完全一致（含端口，即使默认 443/80 也必须显式匹配）
• 连接未超时（受 keepalive_expiry 控制），且当前空闲数未达 max_keepalive_connections

常见干扰项：

• 使用 httpx.get(..., client=client) 但每次新建 AsyncClient 实例——连接池无法复用
• HTTP/1.1 请求带 Connection: close header，服务端主动断连
• HTTPS 场景下 SNI 不一致或证书变化，触发连接重建

连接池大小对高并发性能的实际影响

盲目调大 max_connections 可能适得其反：

• 超过服务端承受能力时，大量连接卡在 SYN_WAIT 或触发 TCP 重传，反而降低吞吐
• Python 异步事件循环（如 asyncio）本身调度开销随并发连接数上升，通常 50–200 是较稳区间
• max_keepalive_connections 过小会导致频繁建连；过大则可能占住服务端连接资源，尤其当后端是 Nginx 或云 LB 时

建议先用 httpx.Limits(max_connections=50, max_keepalive_connections=25) 基线压测，再根据 httpx.PoolTimeout 报错频率和端到端延迟调整。

真正难调的不是数字本身，而是确认你用的是同一个 AsyncClient 实例、目标域名解析稳定、且服

务端没有中间件悄悄关闭长连接。