vibe_coding/.cursor/skills/message-queue/SKILL.md

name, version, description

name	version	description
message-queue	1.0.0	配置 Hyperf AsyncQueue + Redis 实现后台任务处理。当需要异步任务、消息队列或延迟队列时使用。含重试策略和事件驱动模式。

Hyperf Async Queue (Message Queue)

触发条件

用户需要异步处理任务：通知发送、数据同步、超时检测、日志记录、批量操作。

执行流程

Phase 0: 加载规范

读取 .cursor/rules/013-backend.mdc、016-swoole.mdc，提取 Job 命名、DI、协程安全、连接池。

Phase 1: 队列配置

config/autoload/async_queue.php：Redis 驱动、channel、retry_seconds 指数退避、handle_timeout、processes、concurrent。可配置 default 与 notification 等多队列。

Phase 2: Job 类

继承 Hyperf\AsyncQueue\Job，maxAttempts、幂等检查、handle() 内 try-catch 记录日志后 re-throw 触发重试。

Phase 3: 投递任务

QueueService 封装 dispatch、dispatchNotification、dispatchDelayed。从 DriverFactory 获取 driver 后 push。

Phase 4: 使用场景

通知发送、超时检测（延迟 30 分钟）、批量处理（chunk 后逐批 dispatch）。

Phase 5: 事件驱动

Event → Listener → QueueService.dispatch。Service 更新数据后 event() 触发，Listener 内异步投递多个 Job。

Phase 6: 监控

队列 health check 命令：Redis 统计 waiting/delayed/failed/timeout，failed > 100 告警。

完整实现见 Tier 3。

验证

1. 配置使用环境变量
2. Job 幂等
3. maxAttempts、retry_seconds 合理
4. handle_timeout 大于 Job 最大执行时间
5. 关键 Job 有错误日志
6. 延迟队列用于超时检测
7. 消费进程在 supervisor 注册

Tier 3 深度参考

文件	内容
references/queue-implementation.md	配置、Job、投递、事件驱动、监控完整代码