API 分页：跟踪页面边界与数据完整性
作者：Ai Flowi · 发布于
API 分页将一个数据集合拆成较小的响应，并规定调用方如何请求下一部分。要收集完整结果，需要保留每个页面边界、遵循接口约定中的续页规则，并检查明确规定的结束条件。首次响应成功只能确认该页的结果，不能说明已获取整个集合。
完整性有其适用范围：所选的筛选条件、排序方式、权限和集合版本。页面序列可以正常结束，却不包含调用方无权访问的记录。如果集合在遍历期间发生变化，即使序列从未中断，也未必代表同一个一致快照。
偏移分页与游标分页有何区别？
偏移分页请求有序结果中的某个位置，通常还会指定每页大小。游标分页则使用服务提供的值，请求某个续页位置。两种方式都需要接口约定说明排序、终止条件，以及底层记录变化时的行为。
| 方式 | 调用方保留的内容 | 需要注意的不确定性 |
|---|---|---|
| 偏移 | 请求的位置、大小、筛选条件和排序方式 | 在该位置之前插入或删除记录，可能使后续记录的位置发生偏移。 |
| 游标 | 返回的续页值及其关联查询 | 仅有游标，并不意味着存在固定快照、游标永久有效，或可获得记录总数。 |
将不透明游标视为数据，按规定原样传回。除非 API 允许，否则不要递增游标、将其解释为行号，或在不同筛选条件下复用。只有在所提供的接口约定明确规定时，不足一页或空页才是结束信号。
自行编写的三页响应约定
这个虚构的只读 API 按固定顺序提供六个合成条目 ID。仅在这个教学测试样例中，集合保持不变，每个非末页包含两个条目，且预期 ID 已知。字段 next_cursor 包含下一次请求所用的值；JSON null 明确表示遍历结束。缺少该字段意味着响应无效，不能将其当作替代的结束信号。
{"items":[{"id":"item-A"},{"id":"item-B"}],"next_cursor":"page-two"}
{"items":[{"id":"item-C"},{"id":"item-D"}],"next_cursor":"page-three"}
{"items":[{"id":"item-E"},{"id":"item-F"}],"next_cursor":null}这三个对象是自行编写的示例响应体，并非生产环境响应。首次请求不带游标；后续请求原样传入前一次的 next_cursor 值。这里用类似单词的游标值便于阅读；实际服务可能提供不具备人类可读含义的值。
| 页码 | 请求游标 | 观察到的 ID | 返回的 next_cursor | 台账决策 |
|---|---|---|---|---|
| 1 | 未提供：首次请求 | item-A, item-B | page-two | 保存本页；请求 page-two。 |
| 2 | page-two | item-C, item-D | page-three | 保存本页；请求 page-three。 |
| 3 | page-three | item-E, item-F | null | 已观察到结束标记；将全部六个 ID 与测试样例核对。 |
每行还应保留尝试编号、响应判定结果和观察时间。请求游标用于标识页面边界；独立的尝试编号用于区分同一边界上的重试。敏感续页值应存放在访问受限的证据记录中，而非公开日志中。
发现重复游标、重复 ID 和缺失页面
| 问题 | 发生变化的观察结果 | 台账发现的问题 | 处理方式 |
|---|---|---|---|
| 游标重复 | 第 2 页再次返回 page-two | 续页值指向一个已经验收的边界。 | 停止遍历；标记未取得进展。 |
| ID 重复 | 第 2 页包含 item-B 和 item-D | item-B 已在第 1 页出现；item-C 缺失。 | 保留两页的观察记录；将测试样例的 ID 唯一性检查判为失败。 |
| 页面缺失 | 调用方从第 1 页直接跳到 page-three | 下一次请求与第 1 页的续页值 page-two 不匹配。 | 即使末页返回 null，也应将集合标记为不完整。 |
静默删除重复 ID 会掩盖有用的证据。在执行任何允许的去重操作之前，先保留原始出现次数和来源页面。在这个冻结的示例中，重复记录违反约定；在持续变化的集合中，重复也可能表明记录跨越了页面边界。无论哪种情况，仅靠去重都无法找回缺失记录。
已知包含六个 ID 的测试样例提供了独立的完整性检查。实际调用方如果没有预期清单，不能仅凭唯一 ID 的数量证明所有源记录均已返回。它可以确认观察到的序列遵循了所提供的接口约定，再说明源数据完整性或快照一致性的限制。
收集前先定义“完整”的含义
只有在所有必需响应均通过约定的响应体检查、每个续页值均已跟进，并收到文档规定的终止条件后，才能验收集合。保持原始查询及所提供的快照引用不变。区分“遍历已完成”和“已依据独立来源核对清单”。
请求次数上限或截止时间可以防止调用方陷入无休止的遍历，但达到上限不代表成功终止。应记录不完整结果和下一处尚未解决的边界。如果游标过期，遵循服务的重启规则；不要把重启后的序列拼接到此前的页面上，再将混合结果称为同一个快照。
响应失败时，应将最后验收的页面与失败尝试分开保存。如果调用方在验证响应体之前就追加记录，无效页面可能污染收集结果。恢复过程必须保留查询标识和最后验证过的边界。
AI Flowi Workflow 请求中的分页
状态：已在文档中说明。 组件的请求字段请参阅 API Request 文档；这些字段的状态为已在组件目录中说明；未经 Ai Flowi 生产环境测试
。
示例配置，并非已记录的测试
在这个虚构的请求映射中，将查询参数命名为 cursor，并通过 query_params 传递：首次请求省略该参数，之后仅在验证前一页响应体后，才依次提供 page-two 和 page-three。这些是测试样例的值，并非组件目录中的选项。响应字段 next_cursor 与请求参数 cursor 特意采用不同名称；把响应键直接当作请求键，会违反这个虚构端点的约定。
验收第 2 页后，待发请求为 page-three，已保存的 ID 为 item-A 至 item-D。如果下一次尝试未能返回可用响应体，应将这四个 ID 保留为不完整集合，并将 page-three 保留为未解决项。不要仅因为请求已发出就推进台账。如果后续重试提供了有效的末页响应体，则只验收一次 item-E 和 item-F，再核对六个 ID 的清单。这是在测试样例上进行的人工推演，不代表原生自动分页能力。
使用你的 AI Flowi Workflow 账户，并向 API 提供方获取所需账户或凭证；外部服务使用费用仍单独计费。上面的响应体示例并未通过该组件获取。
常见错误与相关术语
- 将首个 200 响应保存为完整导出结果。
- 仍有有效续页值，却因 items 列表为空而结束。
- 在序列进行到一半时更改筛选条件，却没有新建集合记录。
- 检查页面连续性之前就删除重复项。
- 未获得一致性承诺，就把基于游标的集合称为快照。
如果结束条件、可见范围或一致性要求仍未解决，不要将收集的列表用于核对。更广泛的接口约定请参阅 API 对接；响应验证请参阅 API 测试；连续请求消耗的额度请参阅 API 限流；各页响应的含义请参阅 HTTP 状态码。