HTTPX 完整用法总结

httpx：新一代 Python HTTP 客户端，同时支持同步 + 异步，支持 HTTP/1.1、HTTP/2；API 风格和 requests 非常接近，是异步项目首选（FastAPI 项目标配）。 对比 requests：requests 只有同步；httpx 原生 async，支持 http2，推荐在异步 web 项目使用。

安装

# 基础安装
uv pip install httpx
# 如需HTTP2支持
uv pip install "httpx[http2]"

一、最简一次性请求（不推荐大量请求，每次新建连接）

import httpx

# GET请求，params 自动拼接url查询参数
resp = httpx.get(
    "https://httpbin.org/get",
    params={"name": "leo", "age": 20}, # url ?name=leo&age=20
    headers={"User-Agent": "my-httpx-client"}
)

# 响应对象常用属性
print(resp.status_code)        # 状态码 200 /404
print(resp.headers)            # 响应头
print(resp.text)               # 返回文本字符串
print(resp.json())             # 自动解析json（返回dict）
print(resp.content)            # bytes二进制（图片/文件）
print(resp.url)                # 最终请求的完整url

# 抛出异常：4xx/5xx直接抛错
resp.raise_for_status()

# POST JSON请求
resp = httpx.post(
    "https://httpbin.org/post",
    json={"username": "test", "pwd": "123456"} # json参数，自动设置Content-Type:application/json
)

# POST表单提交（form-data/x-www-form-urlencoded）
resp = httpx.post(
    "https://httpbin.org/post",
    data={"username":"test"} # form表单
)

二、Client 同步客户端（推荐！复用连接池，性能更好）

业务开发优先用 Client，复用 TCP 连接，减少握手开销，全局统一 header、cookie、超时

import httpx

# with上下文管理器，自动关闭连接
with httpx.Client(
    base_url="https://httpbin.org", # 基础域名，后续路径写相对地址
    headers={"User-Agent": "my-app"},
    timeout=10.0, # 全局超时秒
    follow_redirects=True # 自动跟随重定向
) as client:
    # 相对路径请求
    resp1 = client.get("/get", params={"a":1})
    resp2 = client.post("/post", json={"msg":"hello"})
    print(resp1.json())

# 不使用with写法，手动关闭
client = httpx.Client(base_url="https://httpbin.org")
resp = client.get("/get")
client.close() # 必须关闭释放连接

三、AsyncClient 异步客户端（FastAPI / 异步项目重点）

import httpx
import asyncio

async def demo():
    # 异步上下文管理器 async with
    async with httpx.AsyncClient(
        base_url="https://httpbin.org",
        timeout=httpx.Timeout(connect=5, read=10) # 细分连接超时/读取超时
    ) as client:
        # await 发起请求
        resp = await client.get("/get", params={"id":1})
        print(resp.status_code)
        print(await resp.json()) # json() 异步要加await

if __name__ == "__main__":
    asyncio.run(demo())

异步并发请求（高性能批量请求）

import httpx
import asyncio

async def fetch(url, client):
    resp = await client.get(url)
    return resp.status_code

async def main():
    urls = [
        "https://httpbin.org/get",
        "https://httpbin.org/headers",
    ]
    async with httpx.AsyncClient() as client:
        # 并发任务
        tasks = [fetch(u, client) for u in urls]
        results = await asyncio.gather(*tasks)
        print(results)

asyncio.run(main())

四、常用高级功能

1. 超时设置

# 全局统一超时
httpx.Client(timeout=10)
# 精细控制：连接超时5s，读取响应10s，写入10s，总超时30s
timeout = httpx.Timeout(connect=5, read=10, write=10, pool=30)
client = httpx.Client(timeout=timeout)
# 单次请求单独覆盖超时
client.get(url, timeout=20)

2. Cookie 自动维持

with httpx.Client(base_url="https://httpbin.org") as client:
    # 服务端set-cookie会自动保存在client，后续请求自动带上
    resp1 = client.get("/cookies/set?user=leo")
    resp2 = client.get("/cookies")
    print(resp2.json())

3. 文件上传

# 上传文件
files = {"file": open("test.txt", "rb")}
resp = httpx.post("https://httpbin.org/post", files=files)

4. Basic 基础认证

resp = httpx.get("https://httpbin.org/basic-auth/user/pass", auth=("user", "pass"))

5. 流式响应（SSE、大模型流式输出、大文件下载）

# 同步流式
with httpx.Client() as client:
    with client.stream("GET", "https://httpbin.org/stream/5") as resp:
        for chunk in resp.iter_text():
            print(chunk)

# 异步流式（LLM SSE非常常用）
async def stream_demo():
    async with httpx.AsyncClient() as client:
        async with client.stream("POST", "xxx", json={}) as resp:
            async for line in resp.aiter_lines():
                print(line)

6. 代理设置

# http/socks代理
proxies = {"http://": "http://127.0.0.1:7890", "https://": "http://127.0.0.1:7890"}
client = httpx.Client(proxies=proxies)

五、异常捕获（常用异常）

import httpx

try:
    resp = httpx.get("https://httpbin.org/get", timeout=2)
    resp.raise_for_status()
except httpx.ConnectError:
    print("连接失败，域名/端口不可达")
except httpx.ReadTimeout:
    print("读取超时")
except httpx.HTTPStatusError as e:
    print(f"响应错误，状态码{e.response.status_code}")
except Exception as e:
    print("其他异常", e)

六、重点区分 & 开发建议

1. 一次性请求 ：httpx.get()，适合简单测试，不适合循环大量请求，每次新建 TCP 连接，性能差
2. 同步项目 ：用 httpx.Client()，复用连接池
3. 异步项目（FastAPI） ：必须使用 AsyncClient，不能用同步 Client，否则阻塞事件循环
4. 支持 HTTP2：创建客户端时加 http2=True

client = httpx.AsyncClient(http2=True)

七、和 requests 对比小结

表格

	requests	httpx
同步	✅	✅
异步	❌	✅（核心优势）
HTTP2	❌	✅
连接池	✅	✅
生态	成熟	现代项目首选（FastAPI）

八、常见踩坑点

1. AsyncClient 里面调用 .json() 需要 await resp.json()，同步不需要 await；
2. FastAPI 内部不要在路由函数里面直接写一次性httpx.get，尽量全局复用 AsyncClient；
3. 一定要加超时！不设置超时会永久卡住；
4. 异步代码不要混用同步 Client，会阻塞事件循环。