SuperAPI AI 工具集

async

部署与运维

查看项目

更新于 10-16 00:21

技能介绍

用途:该技能是一份异步优先(async-first)架构快速参考,目标是把耗时超过 200 ms 的处理卸载到后台 worker,保持 UI 与 API 的响应性。适用场景包括发送事务性邮件、生成 PDF 或导出 CSV、调用超过 200 ms 的第三方 API、夜间批处理;而简单的数据库读取则不需要异步。

五个必须遵守的不变量:HTTP 响应时间小于 200 ms,超出该阈值的操作一律外移;消息可能被重放,因此必须幂等(幂等键、去重);必须配置重试与死信队列,3 次尝试加指数退避与抖动,超出后进入 DLQ 并告警;使用竞争消费者,4 至 8 个 worker 并行以吸收峰值;进行生命周期追踪,记录结构化日志、指标(延迟、错误率、DLQ 深度)与告警。

推荐框架:Symfony 使用 Symfony Messenger,支持 AMQP、Redis、Doctrine 传输与 Stamps;Laravel 使用 Laravel Queue,生产环境用 Horizon,底层为 Redis 或 SQS;框架无关的 PHP 可用 Ecotone,支持 DDD、saga、调度器与统一消息;Node.js 可用 BullMQ 或 RabbitMQ,基于 Redis 并带仪表盘。

Symfony Messenger 最小模式:定义不可变 DTO 消息(如 SendWelcomeEmail 携带 userId),编写 Handler 时先做幂等检查再执行并记录,最后在控制器中通过 bus dispatch 该消息。

关键反模式:在 Handler 中做幂等操作却不带幂等键,重放会造成重复副作用;在 Handler 中用 catch (\Throwable) 静默吞掉异常,会让消息被标记为已处理但实际失败;在消息里存放邮件或 PDF 的完整负载,应改为存 ID 再查询,否则 RabbitMQ 会不堪重负;第三方调用周围不设熔断器,某个提供商宕机会使 DLQ 急剧上升。更完整的细节、Laravel 与 Ecotone 的模式、配置示例、OpenTelemetry 可观测性、生命周期事件与分阶段检查清单,见 @.claude/skills/async/REFERENCE.md。