Skip to content
Lv1HTTP 与 JSON进度 4 / 6

第 4 章:用 Python 发请求 ​

前三章都在讲"请求长什么样",这一章开始写代码。目标很具体:发得出去、等得住、错得起、收得回。


学习目标 ​

  • 用 requests 完成一次 GET 和一次 POST,正确处理状态码与 JSON
  • 知道超时该设在哪、设多少,理解"不设超时"的后果
  • 会写带退避的重试,知道哪些错误不该重试
  • 理解连接复用为什么能让连续请求快一倍,会用 Session
  • 知道什么时候该换 httpx(异步场景)

4.1 最小可用的一次请求 ​

bash
pip install requests
python
import 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 ​

python
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(推荐) ​

python
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 加进去,一次超时可能变成两次下单。

非幂等请求怎么办 ​

两个办法:

  1. 幂等键:请求头带 Idempotency-Key,服务端保证同一个键只处理一次,重试安全;
  2. 先查后重:超时后先查"这笔操作是否已生效",确认没有再重发。

4.4 Session:连接复用能省一大截 ​

python
# 不复用:每次新建连接(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 几乎一样,同时支持同步和异步:

bash
pip install httpx
python
import 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/2httpx

Lv2 的「大模型 API 调用」和 Lv3 的 FastAPI 都会用到异步客户端,这里先建立"同步够用、异步更快"的印象即可。


4.6 一个生产可用的封装 ​

把前面的要点收拢成一个函数:

python
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 分别该怎么处理。

👉 第 5 章:鉴权与密钥管理

本文阅读--次|全站访问--次|访客--人