跳到正文

API返回成功却缺少记录:先检查分页

阅读其他语言版本 ไทย English

API返回成功却缺少记录:先检查分页

一次请求成功不代表取得全部数据

通过API获取客户或商品时,系统显示成功,但用户发现后面的记录缺失。此时应先检查分页机制,而不是认定源系统没有更多数据。成功响应可能只证明某一页请求执行成功,并不保证接收系统已经读取全部页面。

Microsoft Graph文档介绍了服务端分页,以及仍有结果时返回@odata.nextLink的机制。本文用Graph说明原理;其他API可能采用cursor、offset或不同字段名。因此,应先阅读实际端点的数据约定,再定义结束条件,不能把某个服务的规则套用到所有API。

250条记录却只读取100条的示例

假设一个受控测试集包含250个已知且唯一的ID,服务分成100、100和50条三页返回。若代码只读取第一次响应,就会取得100条正确记录,却漏掉150条。已读取记录的正确性与整个数据集的完整性是两个不同条件,都需要验证。这些数字仅为测试示例,并非所有API都支持的分页大小。

即使所有页面相加得到250条,仍需检查重复和缺失ID,因为重复读取某页也可能让总数看似正确。应比较预期ID集合与实际收到的集合,再核对状态、单据关联等关键字段。保留未通过的记录供调查,而不是删除它们来凑齐数量。

按服务文档处理下一页

对于Microsoft Graph,应按文档使用完整的@odata.nextLink URL,而不是提取skiptoken后自行拼接请求。不能仅因为某页少于请求数量或没有记录就宣布结束。文档说明某页可能包含零条记录,因此仍需检查下一页信号。结束条件必须遵循服务约定。

自动跟随URL必须限制在配置允许的服务范围内。发送凭据前验证目标,不得通过不可信链接把令牌转发到其他域名。可记录运行编号、状态和记录数用于排查,但不应仅为调试就把凭据或完整客户数据写入日志。

完成可靠处理后再保存续传位置

续传检查点应与已经成功保存的数据相对应。若先推进检查点再存储,崩溃后可能跳过该页;若已存储但检查点未推进,则可能重读同一页。因此,必须同时设计检查点与可安全处理重复数据的机制,例如按适当业务标识更新,而不是每次都新增记录。

某页失败时,应保持“数据集未完成”的状态,并遵循服务的重试要求,不能为了让任务显示成功就跳过该页。令牌过期或游标失效时,需要依照文档制定重启或恢复流程,并确认已存储记录不会被意外再次新增。

读完所有页,也可能不是同一时刻的数据快照

在读取期间,其他用户可能新增、修改或删除记录。读到最后一页,本身并不保证得到同一时刻的快照。应确认端点是否保证快照或稳定排序。只有服务确实支持时,才按其条件使用时间过滤、快照导出或增量机制。存在nextLink并不等于具备所有一致性保证。

上线前,应在获准环境中测试不满的最后一页、空页但仍有续页链接、重复页面,以及运行中途失败。验收依据应包括唯一ID数量、未解决记录和符合API约定的完成状态。如需Chawinnix协助集成,可准备端点文档、脱敏示例和验收标准。关于数据迁移后验证的延伸阅读,可帮助在解决分页问题后进一步核对数据。

概念图:连续的数据卡片页面汇集到笔记本电脑旁的数据堆

参考资料

返回全部文章

开始沟通

简要告诉我们您的顾虑,团队会与您联系。您提交的内容将严格保密。