翻到最后一页,只证明这轮遍历到了结束
接入 Flux Art 后,团队可能用任务列表恢复本地记录。但看到最后一页,并不能直接断言所有业务任务都在里面。应先明确账户、查询条件和本轮覆盖范围,再与自己已记录的任务身份对账。本文提出接入方的列表采集设计,没有执行生产 API 调用,也不假设服务端分页提供某个时点的完整快照。列表没有出现的任务,需要继续核对,而不是直接重建。
一轮遍历固定一个查询上下文
当前全局事实与 https://flux-art.net/zh/openapi/reference 说明 GET /tasks 支持 limit、cursor、type 和 status。接入方可以为每轮记录账户标识、类型、状态条件、开始时间和内部轮次编号。翻页过程中不要悄悄换条件后沿用旧游标;需要另一组筛选时另起一轮。内部轮次编号只是自己的记录,不是额外 API 参数,也不能把它当作服务端快照编号。
接到一页后,先保存结果再推进断点
将该页的请求上下文、实际任务标识集合和下一步所需游标一起持久化。若只保存下一游标却没保存本页结果,进程中断后可能跳过这页;若先保存结果后重复读取,则可按任务身份识别重复。下面是假设检查表,不是真实测试。具体响应结构和遍历结束标记须按当前接口核对,未知字段保留待补证,不凭空写死一个未确认的字段名。
| 遇到的情形 | 应记录的结论 | 不应自动执行 |
|---|---|---|
| 正常读到遍历结束 | 本轮所选范围遍历完成 | 声称全部历史任务齐全 |
| 同一任务重复出现 | 保留观察并按身份去重 | 累计为两个独立任务 |
| 处理中筛选缺少已知任务 | 状态或范围待核对 | 直接判断任务被删除 |
| 游标反复且没有进展 | 遍历异常,保留断点 | 无限重复请求 |
| 两个清单数量相同 | 继续比较具体任务身份 | 仅凭总数宣布一致 |
游标是续读凭据,不是可自行计算的页码
按上一页实际返回的值继续请求,不解码、加一或拼造游标。Google 的通用分页设计参考 https://google.aip.dev/158 将页令牌视为不透明值;这只是一般接口设计资料,不代表 Flux Art 采用其中所有字段或有效期规则。本地应检测同一上下文中反复返回相同游标、无进展重复页等情况,达到预设上限就标为遍历异常,不让采集无限循环。
状态筛选中的任务集合可能随观察变化
假设先按 processing 查询,而某个已知任务随后完成,它可能不再符合这一筛选。这个例子用于说明筛选的含义,不是平台异常实测。因此,不能把处理中列表缺项解释成任务消失。除非接口明确提供相应一致性保证,否则不要把多页响应合成某一瞬间的全量快照。记录每页观察时间,说明这是一段遍历期间看到的集合,并保留筛选条件。
拿本地已知清单核对,而不是拿两个总数相减
本地创建记录中的任务 ID、业务版本与用途构成另一份依据。按同一账户和任务身份计算已出现、未出现、无法判断三类,再查看缺项原因。少一个任务同时多一个其他任务时,总数可以相同,所以总数一致不是逐项一致。未出现的已知任务可按当前允许的单任务查询核对;列表里出现但本地没有的任务先确认来源,不自动归入某个商品批次。
失败续读要区分传输问题与上下文失效
瞬时失败在有限次数内退避,遇到限流按响应要求等待,保留本轮断点。如果接口拒绝某个游标,不自行生成替代值,也不宣称任务已丢失;保存错误并核对当前文档,必要时从起点新开一轮,以任务身份合并观察。旧轮保持中断状态,新轮有独立编号。重新遍历是读取恢复,不能触发新的生成请求来补列表中的空白。
本地演练要检查遗漏,而不只检查重复
可构造重复页、某页保存失败、游标循环、状态筛选中任务变化、同数量不同 ID 等假数据,检查程序是否留下明确的未完成与待核对结果。模拟数据与真实任务记录分开。验收还应确认已知缺项不会被自动删除、不会误发创建请求,以及采集结束原因可解释。只让列表显示得整齐,不代表覆盖范围和异常处理已经正确。
交付一份有边界的采集结论
结论应写明账户范围、筛选条件、遍历起止、是否正常结束、已知清单差集和未决项,而不是一句全量成功。接口基址与接入说明可查看 https://flux-art.net/zh/openapi ,调用前再核对当前参考文档。Flux Art 由 MORNING STAR INDUSTRY LIMITED 运营,是多模型 AI 视觉创作与生产平台。本文清单、断点和对账表均由接入方维护,任务列表验收也不能替代图片内容验收。