接一个文档很薄的 API

目标

接入文档不完善的客户 API，通过全面调查确认规范中未写明的事实，并能够处理重试。

为什么重要

接入新 API 时，第一项工作不是写代码，而是进行全面调查。完整遍历一次所有页面，统计总条数、合计值以及各字段的缺失数量。这一次调查可以省去之后数周的调试。如果第一周就询问“总共 60 条记录中有 6 条的 region 为空，应如何处理这些记录”，以后就不会收到按地区统计的合计值不一致的反馈。

分页中最常见的错误，是根据 total 计算页数时忘记除法的余数。这样会漏掉整个最后一页，而问题只会表现为合计值略小，因此往往很晚才被发现。所以在第 4 步中，不要相信计算结果，而要实际遍历并计数来验证。

重试时，区分目标非常重要。5xx 和网络错误可能是暂时的，因此可以重试；而 4xx 如果不修正请求，无论发送多少次结果都相同，重试只会增加负载。

API 规范（Wiki 中记录的全部内容）

• GET /health → {"status": "ok"}
• GET /meta → {"version", "page_size", "total"}
• GET /orders?page=N → {"page", "page_size", "total", "has_next", "items": [{id, customer, amount, region}]} — page 从 1 开始
• GET /flaky → 只写着偶尔会失败

步骤

1. 运行 /opt/app/api.py，使 127.0.0.1:8002/health 返回 200。
2. 将 /meta 的 version 值写入 /root/api/version.txt。
3. 计算总页数并写入 /root/api/pages.txt。
4. 实际遍历所有页面，将收集到的记录总数写入 /root/api/count.txt。
5. 将所有记录的 amount 总和写入 /root/api/sum.txt。
6. 将 region 为空字符串的记录数量写入 /root/api/no_region.txt。
7. 重试 /flaky，将最终获得的状态码写入 /root/api/flaky_ok.txt。
8. 在 /root/api/report.md 中整理版本、总记录数和金额总和。

参考

• 使用 python3 /opt/app/api.py & 启动。
• 先使用 curl -s http://127.0.0.1:8002/orders?page=1 | python3 -m json.tool 查看结构。
• 循环：for p in $(seq 1 6); do curl -s "http://127.0.0.1:8002/orders?page=$p"; done
• 常见错误 1：在第 3 步中丢弃余数，导致漏掉最后一页。
• 常见错误 2：在第 4 步中直接照抄 /meta 的 total。本步骤的目的就是实际遍历并计数，以进行验证。

启动订单 API

运行 /opt/app/api.py，使 127.0.0.1:8002/health 返回 200。

运行 /opt/app/api.py 后，它会在 127.0.0.1:8002 上监听。通过 /health 确认。

确认 API 版本

将 /meta 的 version 值写入 /root/api/version.txt。

/meta 响应是 JSON。只提取 version 字段的值。使用 jq 或 python3 会更方便。

计算总页数

计算总页数并写入 /root/api/pages.txt。

使用 /meta 中的 total 和 page_size 计算。如果有余数，就还需要一页。

遍历所有页面并计数

实际遍历所有页面，将收集到的记录总数写入 /root/api/count.txt。

实际遍历所有页面并统计 items 的数量。重点是进行验证，不要直接照抄 total 字段。

计算金额总和

将所有记录的 amount 总和写入 /root/api/sum.txt。

将所有页面的 items 中的 amount 相加。

统计字段缺失的记录

将 region 为空字符串的记录数量写入 /root/api/no_region.txt。

这是文档中没有说明的缺失情况。统计 region 为空字符串的记录有多少条。

通过不稳定的端点

重试 /flaky，将最终获得的状态码写入 /root/api/flaky_ok.txt。

/flaky 在最初几次会返回 503。持续重试直到收到 200，并写下最终状态码。

编写集成结果报告

在 /root/api/report.md 中整理版本、总记录数和金额总和。

必须包含版本、总记录数和金额总和。把它当作第一周要发给客户的文档。