Python urllib.request 构造带超时的 HTTP 请求

用 Python 标准库发送一个可靠的 HTTP 请求，关键不在于把 URL 传给 urlopen 就结束，而是要把请求对象、超时、响应生命周期和异常类型分开处理。最小组合是：用 Request 保存 URL 与请求头，把 timeout 传给 urlopen，再用 with 管理返回的响应对象。

官方地址：https://docs.python.org/3/library/urllib.request.html

如果只是发起一次 HTTP 请求，可以直接使用 urllib.request.Request + urlopen(..., timeout=秒数)；读取响应时使用上下文管理器，并把网络错误与 HTTP 状态错误分开捕获。

接口目标：让调用方只关心一次请求

urllib.request 是 Python 标准库中的底层 HTTP/URL 打开接口。Request 负责描述请求，urlopen 负责执行请求并返回一个可作为上下文管理器使用的响应对象。

本文只处理三个边界：请求如何携带头部、超时应该放在哪里、响应如何在读取后关闭。连接池、重试策略和异步客户端不放进同一个示例，以免把一次调用的资源边界和更高层的客户端策略混在一起。

调用方需求：Request 保存请求，timeout 限制阻塞

把 URL、Accept 和自定义的 User-Agent 放进 Request，把秒数传给 urlopen。这样请求描述和执行时限各有明确位置，后续更换 URL 或请求头不会改动异常处理。

from urllib.request import Request, urlopen

url = "https://example.com/health"

# Request 描述目标地址和协议头；这里不直接发起网络访问。
request = Request(
    url,
    headers={
        "Accept": "application/json",
        "User-Agent": "17golang-python-client/1.0",
    },
    method="GET",
)

# timeout 以秒为单位，限制阻塞式连接等网络操作；它不是响应业务字段。
with urlopen(request, timeout=5) as response:
    body = response.read(64 * 1024)  # 限制单次读取量，避免示例无限制吞入响应体。
    status = response.status
    content_type = response.headers.get("Content-Type", "")

print(status, content_type, body[:80])

这里的 timeout=5 应该被看成调用边界的一部分，而不是写在 Request 的 headers 中。超时参数是数值，不会变成发送给服务器的 HTTP 头部。

参数设计：把可变业务信息留在入口

如果代码会被多个接口复用，可以把 URL、超时和读取上限作为函数参数，但请求头仍由一个小函数集中生成。这样调用方能调整时限，却不会意外遗漏最基本的协商头部。

from urllib.request import Request

def build_request(url: str, *, accept: str = "application/json") -> Request:
    """组装一次 GET 请求，保持调用方与 urllib 的细节隔离。"""
    # 只把协议层需要的字段放入 headers，业务参数不要伪装成 HTTP 头。
    return Request(
        url,
        headers={
            "Accept": accept,
            "User-Agent": "17golang-python-client/1.0",
        },
        method="GET",
    )


request = build_request("https://example.com/health")
# timeout 由执行端决定，便于按接口延迟预算调整，而不改变 Request 内容。
with urlopen(request, timeout=3) as response:
    payload = response.read(64 * 1024)

请求头表达的是“我希望接收什么”，超时表达的是“我最多等待多久”。二者拆开后，调用方可以为健康检查使用较短超时，为普通查询使用更长超时，而不需要复制一套请求构造代码。

错误处理：HTTP 状态与网络失败不是一回事

HTTP 服务端返回 404 或 500 时，urlopen 通常会抛出 HTTPError；DNS、连接拒绝或代理失败等协议层问题通常落在 URLError。超时可能以 TimeoutError 或被包装在底层原因中出现，所以日志应保留异常链。

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

def fetch_json_bytes(request: Request, *, timeout: float = 5.0) -> bytes:
    # 让调用方拿到原始字节，编码和 JSON 解析可以在更高层按接口约定处理。
    try:
        with urlopen(request, timeout=timeout) as response:
            return response.read(256 * 1024)  # 设置上限，避免异常响应耗尽进程内存。
    except HTTPError as exc:
        # HTTPError 同时携带状态码和响应信息，适合记录服务端拒绝原因。
        raise RuntimeError(f"HTTP status={exc.code} url={request.full_url}") from exc
    except URLError as exc:
        # URLError 的 reason 可能包含 DNS、代理或连接层的具体原因。
        raise RuntimeError(f"network failure url={request.full_url}: {exc.reason}") from exc
    except TimeoutError as exc:
        # 超时单独保留，调用方可据此决定是否降级或稍后重试。
        raise RuntimeError(f"request timeout url={request.full_url}") from exc

不要把所有异常都改写成“接口返回失败”。上层通常需要知道是服务端状态、网络路径还是等待时间超限，才能选择告警、降级或重试。

兼容策略：响应按字节读取，解析交给上层

响应体可能声明不同字符集，也可能返回空体、压缩内容或并非 JSON。底层函数先返回有限大小的字节，能避免把内容类型判断、文本解码和业务反序列化硬塞进网络函数。

如果接口确实约定 UTF-8 JSON，可以在上层显式执行 decode("utf-8") 和 json.loads，并把解码异常单独记录。不要因为示例接口看起来简单，就默认所有响应都能无条件转成字典。

一个可复用的最小客户端

下面把前面的决策合并成一个最小函数：入口接收 URL、超时和读取上限；成功时返回状态码、响应头与字节内容；失败时保留原因链。它适合脚本、探活或低频管理任务，复杂的连接池和重试可以在这个边界之上继续封装。

from dataclasses import dataclass
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen

@dataclass
class HttpResult:
    status: int
    content_type: str
    body: bytes


def get(url: str, *, timeout: float = 5.0, max_bytes: int = 256 * 1024) -> HttpResult:
    # 把请求头集中管理，调用方只提供地址与本次调用的预算。
    request = Request(
        url,
        headers={"Accept": "application/json", "User-Agent": "17golang-python-client/1.0"},
        method="GET",
    )
    try:
        # with 保证正常返回和读取异常时都释放响应资源。
        with urlopen(request, timeout=timeout) as response:
            return HttpResult(
                status=response.status,
                content_type=response.headers.get("Content-Type", ""),
                body=response.read(max_bytes),
            )
    except HTTPError as exc:
        raise RuntimeError(f"HTTP status={exc.code} url={url}") from exc
    except URLError as exc:
        raise RuntimeError(f"network failure url={url}: {exc.reason}") from exc
    except TimeoutError as exc:
        raise RuntimeError(f"request timeout url={url}") from exc

取舍清单：什么时候继续用 urllib.request

最容易被忽略的检查点有三个：timeout 没有被误写进 headers；响应对象确实在 with 中读取；异常日志没有丢掉状态码、URL 和底层原因。把这三点固定下来，Python 标准库也能支撑一段可维护的 HTTP 调用。

相关问题

timeout 是连接超时还是整个响应超时？它用于阻塞式网络操作，不能简单当作完整业务流程的总耗时预算；如果业务还包含解析、重试和后续处理，需要在更高层另行计时。

为什么不直接把响应读成字符串？字节是更稳妥的底层边界，文本编码应依据响应头或接口约定显式处理。

请求失败后能不能自动重试？只有在方法幂等、错误可恢复且总预算允许时才考虑重试；不要在底层函数里无条件重复发送。