HTTPX 入门：Python 的现代 HTTP 客户端
HTTPX 是 requests 的现代继任者：同步异步双 API、HTTP/2、连接池、超时重试、流式响应。本文讲解 HTTPX 的核心用法与生产实践。
直接回答：HTTPX 提供与 requests 几乎一致的易用 API，但补齐了它的时代短板：原生 async/await 异步支持、HTTP/2、精细超时控制与连接池配置。 新项目的 HTTP 客户端，选它。
为什么是 HTTPX
requests 伟大但停在了同步 HTTP/1.1 时代。异步框架里用 requests 会阻塞事件循环；微服务间大量并发调用时，需要合理安排线程或采用异步客户端，不能给出统一吞吐损失。HTTPX 由 encode 团队（Django REST framework 作者）打造，httpx.get(...) 的用法你闭着眼都会，而 AsyncClient 打开了异步大门。
安装与基础请求
pip install httpx
import httpx
resp = httpx.get("https://api.example.com/users", params={"page": 2})
print(resp.status_code) # 200
print(resp.json()) # 解析 JSON
resp.raise_for_status() # 非 2xx 抛异常
POST/PUT/DELETE 同理，JSON 提交 httpx.post(url, json={...})，文件上传用 files=。
Response 对象
status_code、headers、json()、text、content（字节）之外，流式读取大响应：
with open("big.zip", "wb") as f:
with httpx.stream("GET", "https://example.com/big.zip") as r:
r.raise_for_status()
for chunk in r.iter_bytes():
f.write(chunk)
下载几个 G 也不撑爆内存。
超时与重试
timeout = httpx.Timeout(10.0, connect=5.0) # 连接阶段 5s，其余阶段 10s，不是总截止时间
# 连接级重试交给 transport
transport = httpx.HTTPTransport(retries=3)
client = httpx.Client(transport=transport, timeout=timeout)
生产铁律：所有外部调用必须设超时——HTTPX 默认有 5 秒网络无活动超时，不是只有连接超时；connect/read/write/pool 分别控制各阶段。transport retries 只重试 ConnectError/ConnectTimeout，状态码和读取失败需另设幂等重试策略。
异步：性能的真正释放
import asyncio, httpx
async def fetch_all(urls):
async with httpx.AsyncClient(timeout=10) as client:
tasks = [client.get(u) for u in urls]
return await asyncio.gather(*tasks)
responses = asyncio.run(fetch_all(urls))
100 个并发请求不再是 100 次串行等待——异步客户端 + asyncio.gather 让 IO 密集聚合接口的并发等待得以重叠，但实际提升取决于服务限流、连接池和负载。FastAPI 路由里直接 await client.get(...)，与框架同频共振。
HTTP/2 与连接池
client = httpx.Client(http2=True) # 需 pip install httpx[http2]
limits = httpx.Limits(max_connections=100, max_keepalive_connections=20)
client = httpx.Client(limits=limits)
HTTP/2 多路复用可能减少连接开销，但不保证提速；连接池复用 TCP 连接，高频调用同一 API 时延迟显著下降。Client 要复用并在退出时关闭（同步用 with，异步用 async with 或生命周期钩子），别每次请求新建——新建客户端等于放弃连接池。
常见问题（FAQ）
Q：存量 requests 项目要迁移吗？
A：API 相近但重定向、超时和异常语义等不同，需要回归测试。同步项目无痛点可以不急；异步框架（FastAPI/aiohttp）里的 requests 调用应尽快迁。
Q：httpx 和 aiohttp 怎么选？
A：aiohttp 只有异步但生态老；httpx 同步异步一体、API 更现代、HTTP/2 支持好。新代码选 httpx。
Q：怎么 Mock httpx 做测试？
A：官方推荐 httpx.MockTransport：把 handler 函数传进 Client，无需改业务代码即可返回假响应，比 patch 整个模块优雅。
官方参考
本文基于官方文档整理，未进行运行时或性能测试。示例中的业务函数、数据模型和部署地址需结合项目补全；局部片段不等同于完整生产应用。
