关于 async
一份异步优先设计速查技能，指导将耗时操作交给后台 Worker，避免 HTTP 请求或界面失去响应，并概述可靠性要求、框架选项和常见错误。
主要功能
- 01判断何时转交后台处理
- 02幂等性与去重
- 03重试、退避和死信队列
- 04并行竞争消费者
- 05生命周期日志、指标和告警
- 06PHP 与 Node.js 框架选项
适用场景
- 01将邮件和文档生成交给 Worker
- 02处理缓慢的第三方 API 调用
- 03规划重试和死信处理
- 04监控后台任务故障
安装
复制下面的命令，在终端中运行。
$
npx skills add https:/安装后在 Claude Code 中输入/async确认已加载。
附带文件REFERENCE.md
详细介绍
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）
// Message (immutable DTO)
final class SendWelcomeEmail
{
public function __construct(public readonly string $userId) {}
}
// Handler
final class SendWelcomeEmailHandler
{
public function __invoke(SendWelcomeEmail $message): void
{
// Idempotency check
if ($this->emailLog->wasSent($message->userId, 'welcome')) {
return;
}
$this->mailer->sendWelcome($message->userId);
$this->emailLog->record($message->userId, 'welcome');
}
}
// Dispatch (controller)
$this->bus->dispatch(new SendWelcomeEmail($user->id));
关键反模式
- ❌ 在没有幂等键的情况下，直接在 handler 中执行幂等操作（重放 = 产生双重效果）。
- ❌ 在 handler 中使用
try { ... } catch (\Throwable) { /* swallow */ }→ 即使消息处理失败，也会被标记为已处理。 - ❌ 将完整的邮件/PDF 负载存入消息 → 应优先使用 ID + 查询，否则 RabbitMQ 会不堪重负。
- ❌ 对第三方调用不使用断路器：服务提供商宕机会导致 DLQ 数量激增。
深入了解
完整详情、Laravel/Ecotone 模式、配置示例、OpenTelemetry 可观测性、生命周期事件以及各阶段检查清单：请参阅
@.claude/skills/async/REFERENCE.md。
评论
支持 Markdown