API 练习、自测与掌握标准

使用方法

先不看答案完成概念题，再独立重写项目中的核心循环。自测的目标不是记住全部状态码，而是面对一个陌生 API 时能找到契约、写出有边界的调用、解释失败并保护凭据。

第一组：读文档与请求构造

选择一个不需要真实 key 的公开 API 文档，或直接使用本地教学服务，完成一页“调用卡”：

服务与文档：
base URL：
method + path：
认证：
query/path/header/body 参数：
成功状态与响应 schema：
错误状态与机器错误码：
分页：
限流：
超时/重试/幂等约定：
版本或获取日期：

验收：另一位学习者只读这张卡，就能构造请求，且不会猜测 header 名、分页终止条件或重试规则。

第二组：代码小练习

练习 1：安全读取 JSON

写 fetch_json(url)：

• 只允许 https://，本地测试额外允许 http://127.0.0.1；
• 使用 (connect, read) timeout；
• 设置 Accept: application/json；
• 先检查状态码和 content type；
• 无效 JSON 抛出独立异常；
• 不捕获后返回空字典。

练习 2：有界分页

从空白文件实现 cursor 分页：

• 可配置 max_pages 和 max_items；
• cursor 不透明；
• 检测重复 cursor；
• 每页校验 items 为数组；
• 使用生成器，不一次加载全部数据。

练习 3：解析 Retry-After

分别处理："15"、合法 HTTP 日期、过去日期、负数、空字符串、非 ASCII 数字 "²" 和任意文本。明确无效值是回退到本地退避还是立即失败；若合法值超过等待预算，必须停止/延期而不是截短后提前重试。用 sleep spy 和固定时钟写测试固定选择。

练习 4：错误分类

构造以下输入并断言异常类型：连接被拒绝、404 problem JSON、503、200 HTML、200 无效 JSON、200 但缺少必填字段。

练习 5：安全日志

给定包含 Authorization、Cookie、签名 query、用户邮箱和 request ID 的请求信息，输出一条允许的结构化日志。采用字段白名单，不做“先输出全部，再字符串替换”。

第三组：综合任务

在 可靠 API 客户端项目 基础上实现“可恢复导入器”：

1. 分页读取 items；
2. 每条以稳定 id 写入本地 JSONL；
3. 每成功处理一页后保存下一个 cursor；
4. 程序中断后可继续；
5. 已写入的 ID 不重复；
6. 429/503 有限重试，其他 4xx 进入失败报告；
7. 日志不含 body 全文或敏感 header；
8. 测试模拟第 2 页处理后中断，再次运行得到完整且不重复的数据。

项目不是“运行没报错”就完成。必须提供：测试命令、成功输出、一个故意失败用例、设计说明，以及未覆盖风险。

概念自测

1. response.json() 成功能否证明请求成功？为什么？
2. 401 与 403 的排查方向有什么不同？
3. timeout=10 是否表示整次下载最多 10 秒？
4. 为什么读取超时后 POST 结果可能未知？
5. GET 是幂等方法，是否意味着可以无限重试？
6. 为什么多个 worker 各自处理 429 可能形成重试风暴？
7. offset 分页在数据持续插入时可能出现什么问题？
8. 同一个幂等键何时复用，何时必须新建？
9. 为什么自然语言错误 message 不适合作为稳定程序分支？
10. 日志中最值得保留、又不应泄漏凭据的诊断字段有哪些？

参考答案

1. 不能；它只证明 body 可解析，仍需检查状态码、content type、schema 与业务状态。
2. 401 优先检查凭据缺失、过期和目标服务；403 优先检查 scope、角色、资源归属和策略。
3. 不一定；Requests 的 timeout 主要约束连接与 socket 无数据等待，不是完整操作 deadline。
4. 服务端可能已执行，但响应在返回途中丢失。
5. 不能；仍需最大次数、deadline、退避、限流与故障分类。
6. 它们可能同时等待、同时再试，进一步超过服务端容量；应协调全局速率/并发并加入 jitter。
7. 前面插入/删除会让位置移动，造成重复或漏读。
8. 同一逻辑操作的重试复用；新逻辑操作新建。前提是服务端明确支持。
9. 文案会变化、翻译且不保证结构；应使用状态码和文档化机器错误码。
10. 服务、方法、路由模板、状态码、耗时、尝试次数、错误分类和 request ID；不记录 token、Cookie、签名 URL 或敏感正文。

常见误区判断

判断对错并给出理由：

• “只要用了 HTTPS，就可以把 token 写在 URL。”
• “所有 5xx 都应该重试到成功。”
• “幂等键由客户端加一个随机 header 就自动生效。”
• “分页响应为空数组，任何 API 都必然结束。”
• “SDK 已经封装 HTTP，因此不必关心超时和状态码。”
• “把异常捕获后返回 None 能让 Agent 更稳定。”

答案均为错。HTTPS 不阻止 URL 进入日志；重试必须有条件和预算；幂等键需要服务端契约；分页终止规则各异；SDK 仍有可靠性默认值；None 会抹掉失败语义并导致后续错误决策。

最终掌握标准

基础理解

• 能拆解 request/response，并解释 method、URL、headers、body、status。
• 能区分认证与授权、API key 与 OAuth、access token 与 refresh token。
• 能解释 2xx、4xx、5xx 类别，并正确处理常见状态码。

独立实现

• 能用 venv + pip 从零建立环境并使用 Requests。
• 每次请求设置合理连接/读取超时，外层任务有 deadline 意识。
• 能实现有界 cursor 分页与断点恢复。
• 能根据操作语义和错误类型决定是否重试。
• 能实现有上限、带 jitter、尊重 Retry-After 的退避。
• Retry-After 超过等待预算时会停止或延期，不会提前请求。
• 对支持的 API 能正确复用幂等键并处理冲突。

诊断与安全

• 能区分配置、构造、传输、HTTP、格式、schema 与业务错误。
• 日志保留 request ID、耗时、状态与尝试次数，不泄漏凭据或敏感 body。
• 面对不确定结果会标记“未知并查询/补偿”，而不是伪装成明确失败。
• 能写通过路径和故障路径测试，并如实说明未执行的网络调用。
• API/examples 的 35 项测试通过，并能区分 29 项脚本化 Session/loopback HTTP 证据与 6 项离线参考页静态合同。

全部达到后，回到 API 学习目录，按总路线进入 LLM API集成 等后续知识库。

参考资料与继续学习

• RFC 9110: HTTP Semantics
• RFC 9457: Problem Details for HTTP APIs
• Requests User Guide
• Python unittest

获取日期：2026-07-22。