Shopify GraphQL API 批处理：分页、节流重试与断点恢复

API请求返回成功，不代表批量任务已经遍历全部对象。分页遗漏、节流后的立即重试、异常中断和版本变化，都可能使集成留下部分结果。先用只读查询建立可恢复的批处理，再给写入任务增加重复执行保护。

固定接口版本与最小查询范围

选择与项目测试相符的稳定API版本，并记录使用的对象、字段和必要权限。Shopify API版本说明用于核对支持周期与响应版本；不要长期把路径里的版本号视为无须维护的固定值。开发、测试与生产配置分别记录，凭据只保存在合适的服务端环境。

定制平台案例记录平均留存率增加25%，一家零售商的集成案例记录物流效率提升60%。接口层先验收对象是否完整、状态是否正确及异常能否恢复，经营结果则另按客户和物流范围观察，不能用增长数字代替程序完成条件。

用游标推进到最后一页

下面是需适当产品读取权限的GraphQL Admin API只读查询示例；变量中的pageSize是项目选择的每页数量，cursor在首次请求为空。它只展示查询结构，不包含商店或令牌配置。

query ProductPage($pageSize: Int!, $cursor: String) {
  products(first: $pageSize, after: $cursor) {
    nodes { id title }
    pageInfo { hasNextPage endCursor }
  }
}

依据 GraphQL分页说明检查pageInfo。当前页处理完成后，用endCursor作为下一次after变量；hasNextPage为false时结束。若仍显示有下一页但游标缺失或没有前进，应停止并记录异常，不能无限重复当前页。不要以“这页没有很多商品”替代明确结束状态。

按2026年10月查阅的当前分页规则，上述连接查询的pageSize每页最多250个资源；对象数组的一般分页深度上限为25,000，相关count查询超过该范围时返回25,001，表示“多于25,000”，不能据此把25,001当成精确总数。较大任务先按该对象支持的筛选条件拆分可核对的范围；GraphQL Admin API中支持批量查询的对象，也可评估bulk query。不能推定所有对象、连接或其他API都支持同一批量操作。

每次保存当前任务条件、已完成页的游标和对象标识。写出当前页结果成功后再提交断点；否则任务可能记录“已完成”却没有落地数据。对象变化频繁时，另定义本次同步范围与后续增量，避免把一次遍历当成永久一致的全量快照。

错误分类后再决定是否重试

GraphQL Admin API参考用于检查errors及相关变更返回的业务错误；Admin API节流规则按查询成本说明可用额度。重试需要上限、等待和失败接管，不能因为商店使用Plus就假设无限调用。读请求恢复与写请求恢复还需不同处理。

写入任务以业务标识防止重复效果

恢复时先区分容量边界与暂时节流：超过每页数量或分页深度，不会因等待后重发原查询而解除。保存已落地结果和范围断点，调整分页参数、拆分筛选范围，或转入已确认支持的批量查询后，再核对范围交集与遗漏；不要把上限当作空页或可无限重试的网络故障。输入数组最多250项是另一项输入限制，不等于整个批次只能处理250个对象；具体接口仍需核对字段和操作限制。

重试之前先确认写入是否已经在目标系统生效，使用目标对象标识与业务事件记录决定继续、跳过或补偿。可用的幂等机制应按所调用接口确认，不能假定所有变更都有同一个幂等参数。超时只表示本次没有得到明确答复，不表示服务端一定没有完成写入。

自动库存管理案例记录缺货率降低35%，复杂定制案例记录年收入增长50%。库存任务的断点应连同地点、对象、数值口径和更新时间保存；反复执行旧批次不能覆盖较新的业务变化。

用中断与版本变更验证恢复

让测试任务在已完成页与未完成页之间中断，再恢复并比对对象集合，检查遗漏和重复。另测试权限不足、节流、字段不适用和部分写入失败，确认都有退出条件与可查记录。升级API版本时先在测试环境复查查询和错误处理，再变更生产配置；上线验收应证明结果完整，而不是只保存一次成功响应。

需要实施团队协助时，可按Shopify 接口对接与开发服务范围讨论对象与权限清单、断点记录、重复写入保护和中断恢复样例，并在开始前约定验收与后续维护责任。