HTTPX：支持同步/异步与 HTTP/2 的下一代 Python HTTP 客户端｜安装与使用指南

仓库：https://github.com/encode/httpx 官方文档：https://www.python-httpx.org/ 许可证：BSD Python 版本要求：Python 3.9+

1. 项目简介与定位

HTTPX 是 Encode 团队维护的下一代 Python HTTP 客户端。它在设计上尽量贴近 requests 的易用 API，但原生同时提供同步与异步两套接口，并支持 HTTP/1.1 与 HTTP/2，还内置了一个可直接在命令行使用的客户端。

官方 README 对自身的定位是："A next-generation HTTP client for Python"。它不是服务端框架，而是一个用来发 HTTP 请求的库，既可以在脚本里 import httpx 调用，也可以在终端里直接敲 httpx 命令。

1.1 核心信息一览

1.2 适用场景

• 已经习惯 requests 的写法，但需要异步并发抓取；
• 需要原生 HTTP/2 支持，或需要直接请求 WSGI/ASGI 应用做测试；
• 想要一个带超时、类型注解、100% 测试覆盖的现代 HTTP 客户端；
• 想在命令行里直接发请求，而不是再装一个 curl 替代品。

2. 开源协议

HTTPX 采用 BSD 许可证。仓库根目录 LICENSE.md 即协议原文。BSD 协议允许自由使用、修改、再分发，包括商用，只要求保留版权声明与免责条款。

3. 官方仓库链接

• 仓库主页：https://github.com/encode/httpx
• 官方文档：https://www.python-httpx.org/
• 快速上手：https://www.python-httpx.org/quickstart/
• 异步用法：https://www.python-httpx.org/async/
• HTTP/2 说明：https://www.python-httpx.org/http2/
• API 参考：https://www.python-httpx.org/api/
• PyPI：https://pypi.org/project/httpx/
• Issues：https://github.com/encode/httpx/issues

4. 前置要求

来自官方 README 的硬性要求：

• Python 3.9 或更高版本；
• 操作系统：Linux / macOS / Windows 均可，官方未限定特定发行版；
• 网络可访问 PyPI（pip install）；
• 如需 HTTP/2，需要额外安装 h2（通过 httpx[http2]）；
• 如需 SOCKS 代理，需要额外安装 socksio（通过 httpx[socks]）；
• 如需命令行客户端，需要额外安装 rich 与 click（通过 httpx[cli]）。

5. 安装部署

官方 README 给出的安装命令原文：

$ pip install httpx

如需 HTTP/2 支持：

$ pip install httpx[http2]

如需命令行客户端：

$ pip install 'httpx[cli]'

可选依赖（官方 README "Dependencies" 章节列出）：

• h2 — HTTP/2 支持（httpx[http2]）；
• socksio — SOCKS 代理支持（httpx[socks]）；
• rich + click — 命令行客户端（httpx[cli]）；
• brotli 或 brotlicffi — Brotli 响应解压（httpx[brotli]）；
• zstandard — Zstd 响应解压（httpx[zstd]）。

底层依赖固定为 httpcore、h11、certifi、idna、sniffio，由 pip 自动安装。

6. 最小示例代码

官方 README 给出的最小同步示例：

>>> import httpx
>>> r = httpx.get('https://www.example.org/')
>>> r
<Response [200 OK]>
>>> r.status_code
200
>>> r.headers['content-type']
'text/html; charset=UTF-8'
>>> r.text
'<!doctype html>\n<html>\n<head>\n<title>Example Domain</title>...'

异步用法（官方文档 async 章节）：

import asyncio
import httpx

async def main():
    async with httpx.AsyncClient() as client:
        r = await client.get('https://www.example.org/')
        print(r.status_code, r.headers['content-type'])

asyncio.run(main())

命令行用法：

$ httpx http://httpbin.org/json

7. 配置项

HTTPX 没有配置文件，所有配置通过 Client / AsyncClient 构造参数与请求参数传入。官方 README 与文档中明确提到的常用项：

完整参数列表见官方 API 参考。

8. 常见问题

• 和 requests 有什么区别？ HTTPX 尽量做到 requests 兼容 API，但原生支持异步与 HTTP/2；不是所有 requests 插件都能直接复用。
• 必须用 async 吗？ 不是。httpx.get(...) 这种同步写法开箱即用，异步只是多出来的能力。
• 为什么 pip install httpx 后没有 httpx 命令？ 命令行客户端是可选依赖，需要 pip install 'httpx[cli]'。
• HTTP/2 为什么没生效？ 需要先 pip install httpx[http2]，并且构造 Client(http2=True)。
• 超时怎么设？ 官方强调严格超时，建议每次请求或每个 Client 都显式传 timeout=，不要依赖默认值。
• 能直接测 FastAPI / Flask 吗？ 可以，官方支持通过 ASGI / WSGI transport 直接把请求打到本地应用，不用真的起端口。

9. 与同类工具对比

• vs requests：requests 是事实标准，但只支持同步与 HTTP/1.1；HTTPX 是 requests 作者生态（Encode）推出的下一代，API 风格接近，原生异步 + HTTP/2。
• vs aiohttp：aiohttp 同时是客户端与服务端框架，异步生态成熟；HTTPX 客户端侧更贴近 requests 写法，且额外提供同步 API 与 CLI。
• vs urllib3：urllib3 是底层连接池库，很多上层库都依赖它；HTTPX 是面向应用开发者的高层客户端。
• vs pyppeteer / Playwright：后两者是浏览器自动化，能跑 JS；HTTPX 只发 HTTP 请求，不渲染页面。

10. 许可

HTTPX 以 BSD 许可证发布，允许：

• 个人与商业用途；
• 修改源码并再分发；
• 闭源衍生作品。

义务仅为在再分发时保留版权声明与免责条款。具体条款以仓库 LICENSE.md 原文为准。

11. 责任使用声明

使用 HTTPX 进行网页数据采集时，请遵守以下原则：

1. 遵守目标网站的 robots.txt 与服务条款（ToS），不要采集明确禁止抓取的路径；
2. 控制并发数并在请求之间加入延时，避免对目标服务器造成压力；
3. 不绕过登录态、付费墙或反爬机制，不伪造身份去获取本应付费或授权后才能访问的内容；
4. 不批量抓取个人隐私数据，不收集、存储、传播可识别个人身份的信息；
5. 仅将采集到的公开数据用于学习、研究与合规的业务用途；
6. 尊重原作者版权，转载或二次发布数据时注明来源并遵守相应授权。