n8n 分页漏数：请求成功不代表数据完整

HTTP 返回 200，n8n 节点全部执行成功，最后生成的摘要也像模像样，订单却漏了。作者排查后发现，缺失记录在 API 响应的第三页，而工作流只请求了第一页。整个过程没有报错，因为服务端从未承诺一次响应就是完整列表。

这篇文章讨论的是 AI 工作流里很容易被忽略的数据入口：分页。作者的核心主张是，把分页当成一套包含结束条件、去重、恢复和告警的处理流程。对接订单、事件或其他列表 API 的程序员，都值得检查自己的「成功」究竟覆盖了多少数据。

返回成功，为什么还会漏数据

作者每天运行的工作流会拉取新增记录、处理数据，再写出摘要。直到客户询问上周二的一笔订单为何缺失，他们才发现列表根本没有拉完。摘要可以准确描述已收到的数据，却无法证明输入完整。

请求成功，只能证明这一页拿到了，不能证明列表拿全了。

不同服务商的分页约定差别很大：有的每页默认只返回 20 条，有的返回 100 条；有的提供总数，有的只给游标。所谓游标，就是继续请求下一批数据时要带回去的位置标记。

因此，读取记录之前，先弄清三个问题：每页多少条，哪个字段提供下一页位置，以及服务商用什么信号表示结束。

作者提醒，空页不一定是终点，过滤条件发生变化时，中间也可能出现空页；返回条数少于每页上限，也未必能证明已经结束。这些情况是否存在，要以具体 API 的文档为准，不能把某个服务商的行为套给所有接口。

总数字段同样需要核实。它可能统计的是另一个范围，直接拿来和当前过滤结果比较，会制造新的误判。

循环什么时候停，必须由 API 的约定决定

作者建议，循环应跟随服务商的继续信号：取一页，读取下一游标，再携带它请求下一页。结束可能表现为游标为 null、没有下一页链接，或文档约定的其他状态。

固定循环五次的问题很直接：上个月三页能装完的数据，这个月可能需要六页。业务增长之后，原本看似正常的流程就会开始漏单。

「一直请求到空页」也有前提，只有服务商明确把空页定义为结束信号，这个条件才可靠。结束判断应集中放在一个地方，避免多个节点各自决定是否继续。

作者要求至少用跨三页的数据验证循环，重点检查第二页到第三页的游标传递，防止位置偏一造成漏页。

不过，正常结束条件之外，还需要一个最大页数上限。服务商故障、过滤失效或游标循环，都可能让任务整夜消耗 API 配额和执行时间。这个上限应高于合理业务规模，触发时必须告警。

达到安全上限，应报告列表被截断，不能继续宣称处理完成。

拉完所有页之后，还要处理重复和中断

分页结果未必互不重叠。使用 offset 分页时，新记录插入可能改变后续记录的位置，导致重复返回，甚至跳过记录；临时错误后的游标重试，也可能再次拿到已经处理过的一页。

作者的做法是按服务商分配的自然 ID 去重，例如订单 ID、事件 ID 或记录 ID。每收到一条数据，就检查它的 ID 是否已经出现。页码只是位置，不能代表记录身份。

这里要分清两个问题：去重可以消除重复，却不能补回 offset 漂移时已经跳过的数据。作者提出的规则解决了重复处理的一部分风险，没有给出并发写入场景下完整避免漏读的方案。

长列表还需要检查点，也就是把进度持久保存下来。作者举例，任务在总共十二页的第八页崩溃，如果重新从第一页运行，第一至第七页的副作用就可能重复执行。副作用包括写入结果、更新外部状态等操作，能否重复执行而不改变最终结果，属于幂等性问题。

文章建议逐页记录最后获取的游标、最后处理的记录和累计数量，重启后从检查点恢复。同时监控进度：同一游标连续三次运行不变，或者服务商总数增长而已获取页数不再增长，都需要调查。没有节点报错，不代表任务仍在前进。

我的判断

这套规则最有价值的地方，是把「列表完整性」从默认假设变成需要验证的结果。相较于固定循环次数、仅凭空页退出，它更适合长期运行、数据规模会变化的任务。

作者称这些经验来自自己出售和维护的真实模板，修复经过测试；但文章没有提供模板实现、测试样例或对照数据。因此，它是一套有事故依据的工程经验，不能据此认定所有细节都已经得到充分验证。

恢复机制尤其需要补足实现约定。「最后获取的游标」不一定等于「已经安全处理完的位置」：如果保存了下一页游标，当前页却尚未处理完成，崩溃后恢复就可能跳过记录。反过来，处理完成但检查点尚未保存，又可能重放。因此，检查点应对应已经提交的处理进度，并配合接收端幂等设计。文章没有说明这两个动作如何协调。

「至少测试三页」是实用建议，但「两页测试无法发现游标偏一错误」说得过满。能否发现错误，还取决于测试数据和断言。除了页数，还应检查实际请求的游标以及最终 ID 集合。

最后，与服务商总数对账很有帮助，前提是过滤范围、统计口径和时间边界一致。拉取期间数据持续变化时，数量不符也可能来自并发变更，需要调查原因。

能拿来做什么

• 给现有 n8n 或 Node 列表任务补一份分页约定，明确每页条数、下一页字段和结束信号；让 AI 生成接入代码时，也把这些约定放进输入。
• 用至少三页的固定数据验证请求顺序和最终 ID 集合，再加入重复记录、处理中断和游标循环，检查任务是否会漏读或重复执行。
• 将检查点绑定到已处理完成的进度，并让写入端按记录 ID 实现幂等，验证重启后可以继续处理。
• 在最终报告中区分完整结束、达到上限而截断、异常中断，并记录累计数量；有服务商总数时核对统计口径，出现差异就保留调查入口。