[!info] 关联笔记

• 所属 MOC：Web 后端 · 标准库 · 学习路线
• 相关：JSON · 调用 AI 接口

Python HTTP 客户端

这个概念为什么出现

服务集成几乎总是 HTTP。不设超时的客户端会在故障时拖垮线程/协程池。

[!abstract] 一句话理解 HTTP 客户端负责请求构建、超时、状态码处理与连接复用；标准库可用，工程上常用 requests/httpx。

最小可运行示例

场景：用标准库 GET 示例（无外网时可本地跳过）

# urllib_get_demo.py
# 业务意图：演示标准库 GET 与超时参数形态。
# 教学点：Request/urlopen；超时；状态。

from urllib.error import URLError
from urllib.request import Request, urlopen


def fetch(url: str, timeout_s: float = 3.0) -> int:
    req = Request(url, headers={"User-Agent": "thought-forest-demo"})
    with urlopen(req, timeout=timeout_s) as resp:
        return getattr(resp, "status", 200)


def main() -> None:
    try:
        code = fetch("https://example.com")
        print("status:", code)
    except URLError as exc:
        print("network error:", type(exc).__name__)


if __name__ == "__main__":
    main()

建议运行：

python urllib_get_demo.py

期望输出：status: 200 或 network error: ...（取决于网络）。

结合场景再看三个关注点

1. timeout 必填习惯。
2. 生产 JSON API 常用 session。
3. 异步栈考虑 httpx/aiohttp。

核心概念与准确模型

库	特点
urllib	标准库，API 偏底层
requests	同步生态事实标准之一
httpx	同步+异步 API

• 幂等重试要谨慎
• 区分连接错误与 4xx/5xx

边界情况与反直觉行为

1. 重定向与 SSRF
2. 流式下载 内存
3. 代理与证书

常见误区

[!warning] 常见误区：不设超时 错误理解：默认永远返回。
正确模型：默认必须有超时预算。

工程实践

• 统一 client 封装
• 日志 correlation id
• 重试只对幂等

本节总结

客户端是可靠性边界。超时、错误分类与会话管理优先于“能请求就行”。

自测题

1. 为何要超时？
2. 5xx 与连接错误差别？

参考答案

1. 防止故障传播与资源占死。
2. 前者有 HTTP 响应，后者可能未完成传输。

延伸阅读与资料来源

资料	类型	支撑内容
urllib.request	文档	标准库
HTTPX	文档	现代客户端