laravel-queues

涵盖 Laravel 13 队列，并以 PHP Attributes 作为 Jobs、Listeners、Notifications、Mailables 和 Broadcast Events 的主要配置机制（#[Connection]、#[Queue]、#[Tries]、#[Timeout]、#[Backoff]、#[MaxExceptions]、#[FailOnTimeout]、#[UniqueFor]、#[Delay]、#[DebounceFor]），同时介绍对应的旧版属性。内容包括 Job 生命周期、分发、Worker、批处理、链式调用、自定义中间件、失败 Job 处理、Horizon 监控、测试、故障排查，以及在 AppServiceProvider::boot() 中通过 Queue::route() 集中配置队列路由。

Laravel 队列（L13 — Attributes 优先）

Agent 工作流（MANDATORY）

在进行任何实现之前，并行启动 3 个 Agent，每个 Agent 调用一次，并指定一个 name：

1. fuse-ai-pilot:explore-codebase - 审查 Job 类、连接和队列路由
2. fuse-ai-pilot:research-expert - 通过 Context7 验证 L13 Queue 和 Queue::route()
3. mcp__context7__query-docs - 检查队列 Attribute 模式

实现后，运行 fuse-ai-pilot:sniper 进行验证。

---

概述

Laravel 13 在 Queueable（Jobs、Listeners、Notifications、Mailables、Broadcast Events）上引入 PHP Attributes，作为主要配置机制。通过在 AppServiceProvider::boot() 中使用 Queue::route() 集中配置路由。

Attribute（L13 主要方式）	旧版属性
#[Connection('redis')] · #[Queue('podcasts')]	public $connection · public $queue
#[Tries(5)] · #[Timeout(120)] · #[MaxExceptions(3)]	public int $tries / $timeout / $maxExceptions
#[Backoff([10, 30, 60])] · #[FailOnTimeout]	public $backoff · public bool $failOnTimeout
#[UniqueFor(3600)] · #[DeleteWhenMissingModels] · #[Delay(60)]	public $uniqueFor / $deleteWhenMissingModels / $delay
#[DebounceFor(30, maxWait: 120)]（13.6+，搭配 debounceId()）	—
无 Attribute — ->afterCommit() / ShouldQueueAfterCommit	public $afterCommit

适用于 Jobs、Listeners、Notifications、Mailables 和 Broadcast Events。

---

关键规则

1. 使用 Attributes 声明队列元数据 - #[Queue]、#[Tries]、#[Backoff]
2. 使用 Queue::route() 集中配置路由，位置在 AppServiceProvider::boot()
3. 为每个生产环境 Job 实现 failed(Throwable $e)
4. 在数据库事务中分发时使用 ->afterCommit()（或连接配置中的 after_commit）
5. 在生产环境使用 Horizon 监控 Redis 队列

---

架构

app/
├── Jobs/
│   └── ProcessPodcast.php       # #[Connection, Queue, Tries, Backoff]
├── Providers/
│   └── AppServiceProvider.php   # Queue::route(ProcessPodcast::class, 'redis')
└── Listeners/
    └── SendShipmentNotification.php  # #[Queue('mail')]

→ 参见 templates/QueueableJob.php.md

---

参考指南

概念

• L12→L13 迁移： legacy-properties.md
• Jobs 生命周期： jobs.md · dispatching.md · workers.md
• 组合： batching.md · chaining.md · middleware.md
• 可靠性： failed-jobs.md · horizon.md · testing.md · troubleshooting.md

模板

模板	使用场景
QueueableJob.php.md	基于 Attribute 的 Job
BatchJob.php.md	可批处理的 Job
ChainedJobs.php.md	Job 链
JobMiddleware.php.md	自定义中间件
JobTest.php.md	Job 测试

---

快速参考

基于 Attribute 的 Job（L13 主要方式）

use Illuminate\Queue\Attributes\{Connection, Queue, Tries, Timeout, Backoff, MaxExceptions, FailOnTimeout, UniqueFor};
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;

#[Connection('redis')]
#[Queue('podcasts')]
#[Tries(5)]
#[Timeout(120)]
#[Backoff([10, 30, 60])]
#[MaxExceptions(3)]
#[FailOnTimeout]
#[UniqueFor(3600)]
final class ProcessPodcast implements ShouldQueue
{
    use Queueable;

    public function __construct(public readonly Podcast $podcast) {}

    public function handle(PodcastService $service): void { $service->process($this->podcast); }

    public function failed(\Throwable $e): void { Log::error('Podcast failed', ['id' => $this->podcast->id, 'e' => $e]); }
}

队列路由（集中配置）

// app/Providers/AppServiceProvider.php
use Illuminate\Support\Facades\Queue;

public function boot(): void
{
    // First argument = job class, or an interface / trait / parent class
    Queue::route(ProcessPodcast::class, connection: 'redis', queue: 'media');
    Queue::route(ShouldBroadcast::class, queue: 'events');
    Queue::route([ProcessVideo::class => ['redis', 'videos']]);

    // Forward a queue to another queue / connection (13.26+)
    Queue::forward('reports', 'reports.fifo', 'sqs');
}

其他 13.x 新增内容

• Bus::bulk($jobs)（13.13+）——按连接/队列分组推送多个互相独立的任务，不跟踪批次
• PreparesForDispatch 接口（13.9+）——prepareForDispatch() 返回 false 时会跳过分发
• Illuminate\Queue\Middleware\Release 任务中间件（13.18+）——Release::when($condition, releaseAfter: 60)

→ 旧版 public int $tries = 5 风格——参见 legacy-properties.md

---

最佳实践

应该

• 在任务、监听器、通知、可邮寄对象和广播事件上使用 Attributes
• 在 AppServiceProvider::boot() 中通过 Queue::route() 集中管理路由
• 在事务中分发任务时使用 ->afterCommit()
• 将任务类声明为 final，实现 failed()，并使用 Horizon 监控 Redis

不应该

• 混用 #[Tries] 和 public int $tries（应保持唯一事实来源）
• 在事务中分发任务却不使用 ->afterCommit()（或 after_commit => true）
• 在任务构造函数属性中存储大型对象/闭包
• 在生产环境中使用 sync 驱动