第 4 章:用 Python 发请求
前三章都在讲"请求长什么样",这一章开始写代码。目标很具体:发得出去、等得住、错得起、收得回。
学习目标
- 用
requests完成一次 GET 和一次 POST,正确处理状态码与 JSON - 知道超时该设在哪、设多少,理解"不设超时"的后果
- 会写带退避的重试,知道哪些错误不该重试
- 理解连接复用为什么能让连续请求快一倍,会用
Session - 知道什么时候该换
httpx(异步场景)
4.1 最小可用的一次请求
pip install requestsimport requests
resp = requests.get("https://httpbin.org/json", timeout=10)
resp.raise_for_status() # 4xx/5xx 直接抛异常
data = resp.json() # 解析 JSON
print(data["slideshow"]["title"])四行代码里有四个关键动作,缺一个都不算"写对了":
| 动作 | 作用 | 漏掉的后果 |
|---|---|---|
timeout=10 | 最多等 10 秒 | 对方不响应时,程序永久卡住 |
raise_for_status() | 状态码非 2xx 抛异常 | 把错误响应当正常数据解析 |
resp.json() | 反序列化 | 自己 json.loads(resp.text) 多此一举 |
| 取字段前判空 | 防 KeyError/None | 换个响应结构就崩 |
POST JSON
payload = {
"model": "gpt-4o",
"messages": [{"role": "user", "content": "用一句话解释 HTTP"}],
}
resp = requests.post(
"https://api.example.com/v1/chat/completions",
json=payload, # 自动序列化 + 设 Content-Type
headers={"Authorization": "Bearer sk-xxx"},
timeout=(5, 60), # (连接超时, 读取超时)
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])要点:
- 用
json=payload,不要data=json.dumps(payload)。前者会自动设Content-Type: application/json,后者会当成表单发(第 3 章讲过这个坑); timeout可以是数字,也可以是(connect, read)元组。连接超时通常设 5 秒,读取超时按接口耗时设(大模型接口可能要 60 秒)。
4.2 超时:不设它,等于把程序交给运气
requests 默认没有超时。对方如果一直不返回,你的程序会一直等——在服务里,这意味着一个请求占住一个线程,几个卡住的请求就能把服务拖垮。
三个概念别混:
| 名称 | 含义 | 典型值 |
|---|---|---|
| 连接超时(connect) | 建立 TCP 连接最多等多久 | 3–5 秒 |
| 读取超时(read) | 连接建立后,等响应最多多久 | 按接口定,10–120 秒 |
| 总超时 | 整个请求的上限 | 有些库支持,requests 靠两者组合 |
原则:所有外部调用都必须设超时。没有"这个接口很快所以不用设"这种事,网络抖动不看你的预期。
4.3 重试:错得起,但别把对方打挂
重试不是"失败了就再来一次",要先分类:
用 urllib3 的 Retry(推荐)
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
session = requests.Session()
retry = Retry(
total=3, # 最多重试 3 次
backoff_factor=1, # 退避:1s、2s、4s
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET", "HEAD"], # 只对幂等方法重试
respect_retry_after_header=True, # 遵守 429 的 Retry-After
)
session.mount("https://", HTTPAdapter(max_retries=retry))关键在 allowed_methods:默认只对 GET 这类幂等方法重试。如果把 POST 加进去,一次超时可能变成两次下单。
非幂等请求怎么办
两个办法:
- 幂等键:请求头带
Idempotency-Key,服务端保证同一个键只处理一次,重试安全; - 先查后重:超时后先查"这笔操作是否已生效",确认没有再重发。
4.4 Session:连接复用能省一大截
# 不复用:每次新建连接(DNS + TCP + TLS 都重来)
for i in range(10):
requests.get("https://api.example.com/v1/models", timeout=10)
# 复用:同一个 Session 走完 10 次
with requests.Session() as s:
for i in range(10):
s.get("https://api.example.com/v1/models", timeout=10)差别在握手成本:HTTPS 每次新建连接都要做 TCP 三次握手 + TLS 协商,往返几次,几十到几百毫秒。复用之后这些全省了。
在循环里调同一个接口(拉列表分页、批量查数据),一定要用 Session,快的不只是"一点"。
4.5 httpx:需要异步时就换它
requests 是同步的,一个线程一次只能等一个请求。要并发调 10 个接口,要么开线程,要么换异步库。
httpx 的 API 和 requests 几乎一样,同时支持同步和异步:
pip install httpximport httpx
# 同步用法(和 requests 很像)
with httpx.Client(timeout=10) as client:
r = client.get("https://httpbin.org/json")
print(r.json()["slideshow"]["title"])
# 异步用法:并发请求
import asyncio
async def main():
async with httpx.AsyncClient(timeout=10) as client:
results = await asyncio.gather(
client.get("https://httpbin.org/json"),
client.get("https://httpbin.org/uuid"),
)
for r in results:
print(r.status_code)
asyncio.run(main())什么时候换:
| 场景 | 选择 |
|---|---|
| 写脚本、单次调用 | requests 够用 |
| 要并发几十个请求 | httpx 异步 |
| 已经在 FastAPI / asyncio 项目里 | httpx.AsyncClient |
| 需要 HTTP/2 | httpx |
Lv2 的「大模型 API 调用」和 Lv3 的 FastAPI 都会用到异步客户端,这里先建立"同步够用、异步更快"的印象即可。
4.6 一个生产可用的封装
把前面的要点收拢成一个函数:
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry
_session = requests.Session()
_session.mount("https://", HTTPAdapter(max_retries=Retry(
total=3, backoff_factor=1,
status_forcelist=[429, 500, 502, 503, 504],
allowed_methods=["GET"],
)))
def call_api(url: str, payload: dict | None = None, token: str | None = None):
headers = {"Content-Type": "application/json"}
if token:
headers["Authorization"] = f"Bearer {token}"
resp = _session.request(
"POST" if payload else "GET",
url,
json=payload,
headers=headers,
timeout=(5, 60),
)
resp.raise_for_status()
try:
return resp.json()
except ValueError:
# 返回了 200 但体不是 JSON(常见于网关错误页)
raise RuntimeError(f"响应不是 JSON:{resp.text[:200]}")这个封装覆盖了:超时、重试、鉴权头、JSON 解析、非 JSON 响应的兜底。它不完美(没有日志、没有指标),但比"随手一写"稳得多。
一个容易被忽略的分支:200 但响应体不是 JSON。中间有网关、CDN、反代时,错误可能被包装成 HTML 页面返回 200。resp.json() 这时会抛 ValueError,捕获后打印前 200 个字符,能立刻看出问题。
本章小结
| 要点 | 说明 |
|---|---|
| 四件事 | 设超时、判状态码、解析 JSON、防御取值 |
json= vs data= | 前者自动设 Content-Type,后者按表单发 |
| 超时必须设 | 连接 3–5s,读取按接口定 |
| 重试要分类 | 超时/429/5xx 可重,4xx 不重 |
| 退避 | 1s、2s、4s,别连续猛打 |
allowed_methods | 默认只重试幂等方法 |
| Session 复用连接 | 省掉 DNS/TCP/TLS 握手 |
| httpx | 异步并发、HTTP/2 时用 |
| 200 但不是 JSON | 网关错误页,需兜底 |
下一章
请求能发了,但每个接口都要求"证明你是谁"。下一章讲鉴权:API Key 放哪、Bearer 是什么、.env 怎么用、为什么密钥绝不能进 Git,以及 401、403、429 分别该怎么处理。