拉卡拉开放平台

有些动作没法在几秒内给出结果：生成一份大文件、处理一批数据、触发一次全量核对。这类动作通常采用异步方式，分成提交与查询两步完成。

为什么不适合同步返回

与其让调用方一直等，不如先确认收到，处理完再通知或等待查询。

任务标识的作用

提交成功之后，通常会拿到一个任务标识。这个标识是后续一切动作的关键：

• 用它可以查询任务当前进展；
• 用它可以获取最终结果；
• 重复提交时可以用它做去重判断。

任务标识必须妥善保存。丢了它，就等于失去了与这次任务的唯一联系。

查询节奏怎么定

查得太频繁浪费资源，查得太稀疏影响及时性。常见的做法是：

1. 提交后先等一小段时间再首次查询；
2. 之后逐步拉长查询间隔；
3. 设置总时长上限，超时未完成的转人工处理。

长时间未完成怎么办

• 先确认任务是否仍在队列中，而不是已经失败；
• 再看是否有同类任务积压，可能是整体变慢；
• 最后确认任务参数是否合理，避免超大规模请求。

异步结构的收益是显而易见的：调用方不用阻塞等待，处理方可以按自己的节奏推进。代价则是多了一次状态管理——但相比同步超时带来的不确定性，这点代价是值得的。

通知与查询怎么选

异步任务完成后，结果可以通过通知送达，也可以等待主动查询。两者的取舍与同步场景类似：

稳妥的做法是两者并行：以通知为主，查询作为兜底。

结果的保存期限

异步任务的结果不会永久保留，通常有一个可获取的期限。

• 拿到结果后应立即落库，不要依赖再次查询；
• 生成的文件类结果更要及时下载；
• 期限临近前应有提醒或自动转存机制。

重试的边界

任务失败后是否重试，取决于失败原因：

1. 参数问题：重试无用，修正后重新提交；
2. 资源紧张：可以等待后重试；
3. 部分完成：不要整体重提，只补未完成部分。

整体重提是最省事的做法，也最容易造成重复处理——在异步场景里，这个代价往往比想象中大。

给任务留一个出口

异步任务长时间没有结果，系统不能一直等下去。应当设定一个总时长上限，超过之后转为人工处理或标记待核查。这个出口保证了任何任务都有终点，不会悄悄变成无人过问的死角。

任务状态的设计

异步任务的状态划分应当简洁但够用，通常包括排队中、处理中、已完成、已失败四类。

状态划分清楚之后，调用方的轮询逻辑会简单很多，不会出现「不知道该继续等还是该放弃」的困境。