队列任务开发文档

队列基于 Laravel Queue，默认驱动 Redis（可选 RabbitMQ）。Job 文件分布于各 Bundle 的 Jobs/ 目录。

---

1. 驱动与配置

驱动	说明	配置
redis	默认，生产常用	QUEUE_DRIVER=redis，config/queue.php
rabbitmq	高吞吐、持久化	QUEUE_DRIVER=rabbitmq，RABBITMQ_*
sync	同步执行，仅调试	QUEUE_DRIVER=sync
database	数据库队列	较少使用

失败任务：可配置 QUEUE_FAILED_TABLE（见 config/queue.php）。

QUEUE_DRIVER=redis    # 或 rabbitmq、sync
REDIS_HOST=127.0.0.1
# RABBITMQ_* 见 config/queue.php

---

2. 基础设施

路径	说明
src/EspierBundle/Jobs/Job.php	抽象基类（ShouldQueue + Doctrine 清理）
config/queue.php	redis / rabbitmq / sync / database
bootstrap/app.php	DoctrineQueueProvider、RabbitMQ Provider

---

3. 运行消费进程

生产环境需常驻 worker，例如：

php artisan queue:work redis --sleep=3 --tries=3

Docker 环境可通过 supervisor 管理。本地调试可用 sync 同步执行；生产建议 redis 或 rabbitmq + supervisor 消费。

---

4. 编写 Job

4.1 创建类

src/{YourBundle}/Jobs/YourJob.php

namespace YourBundle\Jobs;

use EspierBundle\Jobs\Job;

class YourJob extends Job
{
    public function __construct(private array $payload) {}

    public function handle(): void
    {
        // 异步业务逻辑
    }
}

4.2 派发

在 Service、Listener 或 Action 中：

dispatch(new \YourBundle\Jobs\YourJob($data));
// 或
\App::dispatch(new \YourBundle\Jobs\YourJob($data));

---

5. 典型场景与各域示例

场景	典型 Job	Bundle
大文件导出	ExportFileJob	EspierBundle
大文件导入	ImportDataJob	EspierBundle
批量会员操作	BatchActionMembers	MembersBundle
群发短信	GroupSendSms	MembersBundle
短信批量发送	AddSmsBatchRecord	AliyunsmsBundle
发票创建	InvoiceCreateJob	OrdersBundle
营销定时触发	FirePromotionsActivity	PromotionsBundle
数据统计	StatisticJob	DataCubeBundle
第三方 ERP 同步	UploadItemsToJushuitanJob	SystemLinkBundle
微信模板消息	SendTemplateMessageJob	WechatBundle
预约过期取消	ReservationExpireCancel	ReservationBundle

---

6. 与事件的关系

• Event/Listener：同步链路上解耦模块。
• Job：耗时、可重试、可削峰的逻辑应入队。
• 常见模式：event() → Listener → dispatch(new XxxJob())。

---

7. 排查

1. 确认 QUEUE_DRIVER 与 Redis/RabbitMQ 连通。
2. 查看 storage/logs/ 与 failed_jobs 表（若启用）。
3. 本地可临时改 sync 复现 handle 逻辑。