长任务的三个必备能力
生成一份长报告、批量处理上千条数据、跑多轮工具调用——这类长任务失败是常态。
要让用户敢用，必须具备三件事：可恢复、幂等、进度可见。
一、可恢复（断点续跑）
- 把任务拆成可独立完成的步骤，每步产出一个可持久化的中间结果；
- 记录"已完成到第几步"（检查点），失败后从检查点继续，而不是从头再来；
- 中间结果要落盘（数据库/对象存储），不要只留在内存里；
- 检查点要带输入指纹：输入变了就不能复用旧中间结果，否则会错。
实践上最有价值的一条：让每一步都能单独重跑（本地也能重跑），调试与恢复都靠它。
二、幂等（重复执行不出错）
长任务必然遇到重试与并发，幂等是底线：
- 每步用业务唯一键（不是随机 id）作为幂等键；
- 写操作采用 upsert 语义；
- 外部副作用（发信、扣费、调用第三方）放到最后，或用"先记录意图、再执行、再确认"的两阶段方式；
- 允许"至少执行一次"，但保证"结果一致"。
三、进度可见
- 对外暴露阶段（准备 → 处理 12/50 → 汇总）而不是一个转圈；
- 阶段名称要人话（"正在解析第 3 份文件"比 "processing" 有用）；
- 提供已用时与预计剩余（粗一点没关系，关键是"在动"）；
- 失败时给出明确的失败点与可执行的建议（重试 / 跳过 / 人工处理）。
常见的四个错
- 全部放在一个 HTTP 请求里跑（超时、断连就全丢）；
- 中间结果只存内存（进程一重启前功尽弃）；
- 无幂等键 → 重试后数据翻倍；
- 进度只写日志不返回给前端（用户不知道在动，只好反复点重试 → 加重负载）。
落地顺序
- 先把任务拆步并落盘中间结果（这一步收益最大）；
- 加幂等键与 upsert；
- 暴露阶段进度与失败点；
- 加一个"从检查点恢复"的按钮，并演练一次真恢复。