SuperAPI AI 工具集

cc-async-task-pattern

编程与开发

查看项目

更新于 10-15 21:11

技能介绍

用途:当单次操作可能跑超过 10 秒(批量数据处理、远程 API 批量调用、全表扫描、跨租户聚合)时,把同步接口改为 triggerAsync() + getStatus() 的异步状态机模式,避免网关 30-60s 截断导致 502/504、用户重复点击引发并发、状态缓存无界增长造成内存泄漏。触发条件包括:单次处理数据量 ≥ 1000 条;链路中远程 API 批量调用且 batch size × 单次延迟 > 5s;历史上同步实现出现过 504/502/30s timeout;用户描述出现“卡住”“转圈很久”“点完没反应”。

主要能力:提供 Spring 版状态机模板,状态含 IDLE、RUNNING、SUCCESS、FAILED;触发接口立即返回,状态查询接口返回快照;同租户 RUNNING 时拒绝重复触发;子线程手动恢复 TenantContext(同样适用 SecurityContextHolder、MDC);状态缓存按租户隔离并实现 TTL/LRU 清理;FAILED 的 errorMessage 透传前端;前端只保留一套 polling 机制,RUNNING 时按钮 disabled 并显示进度。

使用方式:先与 cc-query-performance-safety 配合,把同步性能压到能跑完的范围;只有再优化也压不到 10s 以内才走本规范。状态缓存清理可选入口清理 + TTL(推荐)、@Scheduled 定时清理或 Caffeine LRU 限容。前端进入页面先 getStatus(),RUNNING 时自动启动 polling,完成后 message 提示并刷新主列表。

适用场景:单租户单进程、1 小时以内的任务用 ConcurrentHashMap 状态机;多实例部署需共享状态时状态存 Redis(TTL 1h)+ 分布式锁;长任务(> 1 小时)或需重试时上 Spring Batch / XXL-Job / RocketMQ;工作流编排用 Temporal / Activiti。

限制与反模式:不要启动裸线程而非 Executor;不要把结果塞进 HTTP Session 或写文件;不要用 @Async 却不管返回值;不要用 setInterval 轮询却不 cleanup;同步接口加 @Async 注解因 self-invocation 不生效。RUNNING 状态不能被清理。不要过早上重型方案。