当前位置：首页>python>深入浅出 httpx:Python 新一代 HTTP 客户端完全实战指南

深入浅出 httpx:Python 新一代 HTTP 客户端完全实战指南

2026-08-18 23:11:35

来源：网络

如果你还在用 requests 一行一行地发同步请求，那 httpx 会让你明白：同样是调接口，原来还能这么快、这么优雅。

一、为什么是 httpx？requests 不香了吗？

requests 曾被誉为"人类最好用的 HTTP 库"，但它是 2011 年的产物，天生的两个局限在今天越来越扎眼：不支持异步、不支持 HTTP/2。当你的服务要同时调几十个外部接口、或要对接现代化的 HTTP/2 服务时，requests 就力不从心了。

httpx 正是为解决这两个痛点而生。它由 Python 核心开发者之一 Tom Christie（Starlette、Uvicorn 的作者）打造，目标是"requests 的 API + 异步 + HTTP/2"。PyPI 上月下载量早已破亿，FastAPI、HTTPX 生态已成现代 Python 网络编程的事实标准。

⚡ 同步异步一套代码 — 同一个 Client，.get() 是同步，.aget() 是异步，迁移零成本。

🚀 原生 HTTP/2 — 一行配置开启，连接复用、头部压缩，性能与兼容性双提升。

🛡️ 类型友好 — 全面支持类型注解，编辑器补全和静态检查都更顺手。

一句话总结：httpx = requests 的简洁 + asyncio 的并发 + HTTP/2 的现代。requests 没做错什么，只是时代往前走了一步。

二、安装与第一个请求

安装时建议带上 http2 可选依赖，这样后面才能启用 HTTP/2：

pip install "httpx[http2]"

第一个请求，你会发现它和 requests 几乎一模一样：

import httpx  r = httpx.get("https://www.baidu.com") print(r.status_code)   # 200 print(r.text[:50])     # 响应文本（前 50 个字符） print(r.headers["content-type"])

如果你用过 requests，这段代码无需任何学习成本就能上手：status_code、text、headers 字段完全一致。这就是 httpx 最友好的设计——它不强迫你重写已有代码。

💡 小技巧：httpx 顶层函数（httpx.get 等）每次都会新建临时连接，仅适合一次性调用。生产环境请务必用下面讲到的 Client 会话复用连接。

三、GET/POST 与参数：和 requests 几乎一样

日常调用离不开查询参数、请求体、JSON。httpx 的写法你绝对眼熟：

import httpx  # 查询参数 r = httpx.get("https://httpbin.org/get", params={"q": "python", "page": 1})  # 表单提交 r = httpx.post("https://httpbin.org/post", data={"user": "alice", "pwd": "123"})  # 发送 JSON（自动序列化 + 设置 Content-Type） payload = {"name": "httpx", "stars": 5} r = httpx.post("https://httpbin.org/post", json=payload)  print(r.json())   # 解析 JSON 响应，等价于 json.loads(r.text)

几个关键点：

• params 会自动拼到 URL 上并做 URL 编码，不用自己手拼字符串。

• data 发表单（application/x-www-form-urlencoded），json 发 JSON 并自动设置请求头。

• r.json() 直接拿到解析好的 Python 对象，少写一步 json.loads。

四、超时与重试：别让请求"裸奔"

requests 默认没有超时，一个卡死的接口能让你整个程序挂起——这是线上事故的高发区。httpx 把超时做成一等公民：

import httpx  # 整体超时 5 秒（连接+读+写都算在内） r = httpx.get("https://httpbin.org/delay/2", timeout=5)  # 更精细地分别设置 timeout = httpx.Timeout(10.0, connect=3.0, read=5.0) r = httpx.get("https://httpbin.org/get", timeout=timeout)

超时抛出的异常是 httpx.TimeoutException。生产环境还要配合重试机制，httpx 官方推荐用 tenacity 这类库：

import httpx from tenacity import retry, stop_after_attempt, wait_fixed  @retry(stop=stop_after_attempt(3), wait=wait_fixed(1)) def fetch():     return httpx.get("https://httpbin.org/delay/1", timeout=3)  r = fetch() print(r.status_code)

这样遇到瞬时抖动会自动重试 3 次、每次间隔 1 秒，稳定性显著提升。

五、同步 vs 异步：httpx 的杀手锏

这是 httpx 和 requests 最本质的区别。同步代码一次只能等一个请求；而 httpx 的异步客户端能在等待 A 时去发起 B、C、D。两者API 形态几乎一致，只是多了一个 async/await：

同步：client.get(url) → 阻塞等待返回。

异步：await client.get(url) → 等待期间让出控制权，事件循环去处理别的任务。

import asyncio import httpx  async def main():     async with httpx.AsyncClient() as client:         # aget 是异步版 get；也可用 await client.get(...)         r = await client.get("https://www.baidu.com")         print(r.status_code)  asyncio.run(main())

记住核心原则：异步客户端必须在事件循环里用，且要在 async with 中复用同一个 Client。新建连接的成本很高，反复创建会让你"异步了个寂寞"。

六、并发请求实战：100 个请求 1 秒搞定

异步真正的威力在并发。下面用 asyncio.gather 同时发起 100 个请求：

import asyncio import time import httpx  urls = [f"https://httpbin.org/delay/1" for _ in range(100)]  async def fetch(client, url):     r = await client.get(url)     return r.status_code  async def main():     async with httpx.AsyncClient() as client:         tasks = [fetch(client, u) for u in urls]         results = await asyncio.gather(*tasks)     return results  start = time.time() codes = asyncio.run(main()) print(f"成功 {len(codes)} 个，耗时 {time.time() - start:.2f}s") # 100 个各延迟 1s 的请求，并发仅需 ≈1s

同步写法要 100 秒，异步并发只要约 1 秒——这就是上篇 asyncio 教程里讲过的"把排队变成并行"。httpx 作为原生异步客户端，是把这个能力落地到"调接口"场景的最顺手工具。

⚠️ 重要：超高并发会给目标服务造成压力，生产环境记得用 asyncio.Semaphore 控制并发上限（参考上篇 asyncio 教程），做个有礼貌的调用方。

七、高级玩法：Headers、Cookies、Auth、代理

真实业务里少不了鉴权、自定义头和代理。httpx 都内建支持，且能在 Client 级别统一设置，避免每个请求重复写：

import httpx  with httpx.Client(     headers={"User-Agent": "MyApp/1.0"},     # 公共请求头     cookies={"session": "abc123"},            # 公共 Cookie     auth=("user", "pass"),                     # Basic 鉴权     proxies="http://127.0.0.1:7890",          # 代理     verify=False,                              # 关闭证书校验（慎用）     timeout=10, ) as client:     r = client.get("https://httpbin.org/headers")     print(r.json())

常用鉴权：auth=("user","pass")（Basic）、httpx.Auth 自定义类（Bearer Token 等）。

代理：proxies= 支持 http/https/socks5，科学上网、内网穿透都靠它。

统一配置：Client 级别的参数对所有请求生效，是"优雅封装"的基础（见下文实战）。

八、开启 HTTP/2：一步进入现代协议

很多现代站点（如 Google、Cloudflare 背后）都跑在 HTTP/2 上。httpx 只需在创建客户端时声明 http2=True：

import httpx  with httpx.Client(http2=True) as client:     r = client.get("https://www.google.com")     print(r.http_version)   # "HTTP/2"

r.http_version 会告诉你实际协商到的协议版本。HTTP/2 的多路复用让单个 TCP 连接上并发多个请求，配合连接池，性能优势在高频调用场景下非常明显。

九、会话复用：连接池是性能关键

前面反复强调要用 Client 而非顶层函数，核心原因就是连接池复用。每次新建 TCP 连接（尤其 HTTPS 还要握手）开销很大。Client 默认会复用连接：

• limits=httpx.Limits(max_connections=100, max_keepalive_connections=20) — 控制连接池上限。

• 一个 Client 发 100 个请求，底层可能只建了几个连接，省下大量握手时间。

• 同步用 with httpx.Client()，异步用 async with httpx.AsyncClient()，退出时自动释放连接。

十、实战：封装一个健壮的 HTTP 工具类

把前面所有要点合起来，写一个生产可用的 HTTP 客户端：统一超时、公共头、自动重试、JSON 友好：

import httpx  class HttpClient:     def __init__(self, base_url="", token=None):         headers = {"Accept": "application/json"}         if token:             headers["Authorization"] = f"Bearer {token}"         self._client = httpx.Client(             base_url=base_url,             headers=headers,             timeout=httpx.Timeout(10.0, connect=3.0),             limits=httpx.Limits(max_connections=50),         )      def get_json(self, path, params=None):         r = self._client.get(path, params=params)         r.raise_for_status()           # 非 2xx 自动抛 HTTPStatusError         return r.json()      def post_json(self, path, payload):         r = self._client.post(path, json=payload)         r.raise_for_status()         return r.json()      def close(self):         self._client.close()  # 用法 api = HttpClient(base_url="https://api.example.com", token="xxx") data = api.get_json("/users", params={"page": 1}) api.close()

代码亮点：base_url 省去重复前缀，raise_for_status() 让异常显式可控，Limits 压住连接数——这就是团队里真正能用的封装骨架。

十一、新手最常踩的 4 个坑

1. 忘记设超时：即使是 httpx 也建议显式 timeout=，否则个别慢响应会拖垮整体。

2. 异步里用同步 Client：httpx.Client 不能在 async 函数里 await；异步场景必须用 AsyncClient。

3. 每次请求都新建 Client：连接池失效，性能倒退，务必复用同一个 Client 实例。

4. 忽略状态码：先 raise_for_status() 或判断 status_code，别拿到错误页还当成功数据处理。

十二、总结：requests 用户迁移清单

如果你是从 requests 过来的，下面这张对照表帮你无痛切换：

requests	httpx
requests.get(url)	httpx.get(url) 或 Client.get
session = requests.Session()	client = httpx.Client()
默认无超时	建议显式 timeout=
不支持异步	AsyncClient 原生异步
仅 HTTP/1.1	http2=True 开启 HTTP/2

一句话总结：httpx 不是要"推翻"requests，而是把它的好用延续到了异步和 HTTP/2 时代。你的旧代码几乎能原样跑起来，而一旦需要并发或现代协议，它随时顶得上。新项目直接上 httpx，基本不会后悔。

长按或扫描下方二维码，免费获取 Python公开课和大佬打包整理的几百G的学习资料，内容包含但不限于Python电子书、教程、项目接单、源码等等

▲扫描二维码-免费领取

推荐阅读这 25 个 Pandas 实用技巧你都会吗
五分钟竟能轻松掌握 Python 自动化测试 Selenium ！
25个超实用Python极简代码技巧｜新手直接复用
Java Map vs Python 字典：异同点深度剖析，一篇让你彻底搞懂

点击 阅读原文了解更多

本文来自网友投稿或网络内容，如有侵犯您的权益请联系我们删除，联系邮箱：wyl860211@qq.com 。

深入浅出 httpx:Python 新一代 HTTP 客户端完全实战指南

来源：网络

一、为什么是 httpx？requests 不香了吗？

二、安装与第一个请求

三、GET/POST 与参数：和 requests 几乎一样

四、超时与重试：别让请求"裸奔"

五、同步 vs 异步：httpx 的杀手锏

六、并发请求实战：100 个请求 1 秒搞定

七、高级玩法：Headers、Cookies、Auth、代理

八、开启 HTTP/2：一步进入现代协议

九、会话复用：连接池是性能关键

十、实战：封装一个健壮的 HTTP 工具类

十一、新手最常踩的 4 个坑

十二、总结：requests 用户迁移清单

最新文章

热门文章

随机文章

深入浅出 httpx:Python 新一代 HTTP 客户端完全实战指南

来源：网络

一、为什么是 httpx？requests 不香了吗？

二、安装与第一个请求

三、GET/POST 与参数：和 requests 几乎一样

四、超时与重试：别让请求"裸奔"

五、同步 vs 异步：httpx 的杀手锏

六、并发请求实战：100 个请求 1 秒搞定

七、高级玩法：Headers、Cookies、Auth、代理

八、开启 HTTP/2：一步进入现代协议

九、会话复用：连接池是性能关键

十、实战：封装一个健壮的 HTTP 工具类

十一、新手最常踩的 4 个坑

十二、总结：requests 用户迁移清单

深入浅出 Typer:用 Python 写出专业级命令行工具

6分钟试看不过瘾?教你用Python把整部剧“爬”回家,实现观影自由!

最新文章

热门文章

随机文章