Python 接入代理列表 API：安全快速入门

直接结论

Python 客户端应把代理列表 API 当作短期数据源。只获取需要的记录，保留协议和过期元数据，对临时错误使用有上限的退避重试，在真实请求失败后轮换节点。API key 放在代码之外，并把代理流量限制在获准、低风险的工作中。

适用范围与边界

本文适合开发者构建小型测试工具、数据质量任务或受控自动化，获取当前公开代理记录。它不会把公开节点变成私有或匿名连接，也不保证能访问某个目标站点。不要通过公开代理发送凭据、支付数据、会话令牌或生产密钥。

为什么使用 API，而不是抓取代理列表网页？

HTML 是展示格式，代理列表 API 则可以提供稳定的响应契约、明确的协议字段、时间戳和机器可读错误。客户端可以在建立连接前判断记录是否新鲜，也能缓存响应而不依赖网页布局。

FreeProxy 提供 GET /api/v1/proxies 获取筛选后的列表快照，以及 GET /api/v1/proxy 获取一条匹配记录。API 返回代理元数据和连接记录，不会代调用方抓取目标网页，也不是开放的正向代理接口。

1. 使用 Python 标准库获取小型快照

在服务端环境变量中设置 FREEPROXY_API_KEY。key 只放在请求头中，不写入 URL 或代码仓库。

import json
import os
import urllib.parse
import urllib.request

base_url = "https://proxylistapi.xyz/api/v1/proxies"
query = urllib.parse.urlencode({"protocol": "http", "limit": 20})
request = urllib.request.Request(
    f"{base_url}?{query}",
    headers={"X-API-Key": os.environ["FREEPROXY_API_KEY"]},
)

with urllib.request.urlopen(request, timeout=15) as response:
    snapshot = json.load(response)

for record in snapshot.get("proxies", []):
    print(record["protocol"], record["proxy"], record["expires_at"])

接口可能在成功响应中返回空的 proxies 数组。应将其视为空快照，而不是取消安全检查或无间隔地循环请求。

2. 按过期时间筛选，并保留验证证据

列表响应可能在任务运行期间变化。选取记录前先解析 expires_at，同时保留 validated_at 和 validation_latency_ms，这样日志可以解释选取依据。验证耗时只是验证过程的观测值，不是针对你的目标站点的下载速度承诺。

from datetime import datetime, timezone

now = datetime.now(timezone.utc)
usable = []
for record in snapshot.get("proxies", []):
    expires_at = datetime.fromisoformat(record["expires_at"].replace("Z", "+00:00"))
    if expires_at > now:
        usable.append(record)

把选择策略写清楚。短诊断任务可以选一条记录，并在少量失败后停止；较长任务应维护有上限的队列，在真实超时、连接错误或目标拒绝后移除节点。

3. 在 HTTP 客户端中单独配置代理

获取记录和使用记录是两个步骤。API 响应不会自动配置 urllib 或 Requests。使用 Requests 时，应把代理 URL 放到客户端配置中：

import requests

proxy_url = "http://HOST:PORT"  # 使用 API 返回的记录
proxies = {"http": proxy_url, "https": proxy_url}
response = requests.get(
    "https://example.com/health-check",
    proxies=proxies,
    timeout=10,
)
response.raise_for_status()

请使用自己控制或获准访问的 URL 和目标进行测试。不要因为目标 URL 使用 https 就默认未知代理可信。敏感请求应留在直接、受控的连接中，除非已经单独评估中间节点。

4. 处理错误，避免形成重试风暴

可以按以下响应契约设计错误处理：

响应	建议处理
200 且有记录	按协议和 expires_at 筛选，再选择有限候选。
200 且 count: 0	减少筛选条件或等待下一次快照，不要忙等。
304	复用缓存表示，并重新检查每条记录的过期时间。
401	检查 key 和订阅是否有效。
/api/v1/proxy 返回 404	没有匹配记录，稍后再带间隔重试。
429	遵守 Retry-After，使用带随机抖动的指数退避。
5xx	视为临时错误，限制次数并保留最后一次成功快照。

API key 和客户端 IP 使用独立的速率限制。请求小页并用 ETag 轮询，避免在循环中反复下载相同表示。

5. 使用 ETag 轮询

为完全相同的筛选条件保存响应 ETag，下次请求带上 If-None-Match：

headers = {
    "X-API-Key": os.environ["FREEPROXY_API_KEY"],
    "If-None-Match": cached_etag,
}
request = urllib.request.Request(
    "https://proxylistapi.xyz/api/v1/proxies?protocol=http&limit=20",
    headers=headers,
)

304 表示响应表示没有变化，但不会延长某条记录的 expires_at。调用方仍需检查过期时间。只缓存最后一次成功快照，收到新的 200 后再原子替换。

API key 管理规则

• 从服务端环境变量或密钥管理器读取 key。
• 不要放进查询参数、Git 历史、截图或前端 JavaScript。
• 日志中隐藏 Authorization 请求头和代理凭据。
• 怀疑泄露时立即轮换 key。
• 为任务记录测试目标及其授权边界。

下一步

要了解“已验证”记录的含义和限制，请阅读 免费代理 IP 列表质量判断指南。如果工作流需要更强的归属、隐私或稳定性承诺，再比较 免费代理与付费代理的取舍。