本文介绍如何在 Laravel 队列任务被创建并推入队列的瞬间（即 JobQueued 事件发生时）执行自定义逻辑，如记录日志、初始化上下文或预校验数据，避免误用 fire() 方法导致逻辑延迟。
本文介绍如何在 laravel 队列任务被创建并推入队列的瞬间（即 `jobqueued` 事件发生时）执行自定义逻辑，如记录日志、初始化上下文或预校验数据，避免误用 `fire()` 方法导致逻辑延迟。
在 Laravel 中，队列任务的生命周期包含两个关键阶段：创建/入队（queued） 和 执行（fired）。许多开发者误以为重写 DatabaseJob::fire() 或继承 ShouldQueue 类中的 handle() 方法即可捕获“任务创建”时机，但事实并非如此——fire() 仅在 Worker 拉取并开始执行该任务时调用，此时任务早已入队多时，甚至可能跨进程、跨服务器。
要真正实现在「任务创建完成、即将持久化到数据库（或其他队列驱动）的那一刻」执行逻辑，正确方式是监听 Laravel 内置的队列事件：Illuminate\Queue\Events\JobQueued。
该事件会在任务成功推入队列后立即分发，且携带完整的 $event->job 实例（类型为 Illuminate\Queue\Jobs\Job 或其子类，如 DatabaseJob），是执行前置操作（如审计日志、租户上下文快照、任务幂等性注册）的理想钩子。
✅ 正确实现方式：在 Service Provider 中监听 JobQueued
推荐在自定义服务提供者（如 App\Providers\QueueEventServiceProvider）中注册监听器：
<?php
namespace App\Providers;
use Illuminate\Queue\Events\JobQueued;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\ServiceProvider;
use App\Http\Helper;
class QueueEventServiceProvider extends ServiceProvider
{
public function boot()
{
Event::listen(JobQueued::class, function (JobQueued $event) {
// 可选：仅对 Database 驱动的任务生效（适配你的场景）
if (! $event->job instanceof \Illuminate\Queue\Jobs\DatabaseJob) {
return;
}
// ✅ 此处逻辑在 job 被 create() 并 insert 到 jobs 表后立即执行
// $event->job->getJobId() 返回数据库中生成的 ID（适用于 database 驱动）
Helper::createJobLog($event->job->getJobId());
// 其他操作示例：
// - 记录创建时间、队列名、尝试次数（默认为 0）
// - 关联当前请求上下文（如 request_id、tenant_id）
// - 初始化 Redis 锁或 DB 状态标记（防止重复入队）
});
}
}然后在 config/app.php 的 providers 数组中注册该服务提供者：
App\Providers\QueueEventServiceProvider::class,
? 提示：JobQueued 是「同步分发」和「异步分发」均会触发的事件，无论你使用 dispatch() 还是 dispatchSync()，只要任务进入队列流程，事件即被广播。
⚠️ 注意事项与最佳实践
- 不要依赖 job->id 在 __construct() 或 handle() 中获取：任务对象在构造时通常尚未分配队列 ID（尤其 database 驱动需 INSERT 后才获得自增 ID），$event->job->getJobId() 才是安全可靠的 ID 来源。
- 避免在监听器中阻塞主线程：若 createJobLog() 涉及耗时 I/O（如远程 HTTP 请求），建议改用 dispatch(new LogJobCreationJob(...)) 异步处理，确保队列入队性能不受影响。
- 驱动兼容性：JobQueued 是 Laravel 5.7+ 全局事件，支持 database、redis、sync、sqs 等所有驱动；但 getJobId() 行为因驱动而异（如 Redis 驱动返回 UUID 字符串，Database 驱动返回整数 ID），请根据实际驱动调整日志字段。
- 事件监听范围：若只需监听特定任务类，可在闭包内增加类型判断，例如 if ($event->job->resolveName() === 'App\Jobs\SendNotification')。
✅ 总结
| 时机 | 方法 | 是否推荐 | 说明 |
|---|---|---|---|
| 任务创建并入队后 | 监听 JobQueued 事件 | ✅ 强烈推荐 | 精确捕捉“已持久化”状态，ID 可用，逻辑前置 |
| 任务开始执行时 | 重写 fire() / handle() | ❌ 不适用本需求 | 属于运行时阶段，无法满足“创建即触发”要求 |
通过事件驱动的方式解耦关注点，不仅代码更健壮、可测试性强，也完全遵循 Laravel 的设计哲学——让每个生命周期钩子各司其职。
