Laravel12队列任务中间件该怎么编写限制任务执行-php教程-PHP中文网

laravel 12 的队列中间件与 http 中间件完全独立，必须实现 illuminate\queue\middleware 接口或 handle($job, $next) 方法，仅作用于队列任务执行过程，不参与请求生命周期，且不可复用 http/middleware 下的类。

laravel12队列任务中间件该怎么编写限制任务执行

直接说结论：Laravel 12 的队列任务中间件（Queue Middleware）和 HTTP 中间件不是一回事，不能复用 app/Http/Middleware 下的类；必须用 Illuminate\Queue\Middleware 接口或实现 handle() 方法的独立类，且只对队列任务生效，不参与请求生命周期。

队列中间件和 HTTP 中间件是两套系统

很多人一看到“中间件”就下意识去 app/Http/Middleware 目录写逻辑，结果发现加了 ->through(YourMiddleware::class) 没反应——因为队列任务根本不会经过 HTTP 中间件栈。Laravel 的队列中间件运行在 php artisan queue:work 进程内，作用域仅限于单个任务的执行前后。

HTTP 中间件处理的是 Request → Response 流程，依赖 Pipeline 和 Closure $next
队列中间件处理的是 Job → handle() 执行过程，签名是 public function handle($job, $next)，其中 $job 是任务实例，$next 是继续执行任务的闭包
队列中间件类**必须放在 app/Jobs/Middleware 或任意可自动加载的命名空间下**，不能混在 Http 目录里

怎么写一个限制并发执行次数的队列中间件

比如你有个发送通知的任务，不想让它每秒跑 10 次压垮第三方 API，就得靠队列中间件 + Redis 做节流。关键点不是“拦截”，而是“让任务跳过执行并释放 worker”。

Laravel

避免常见的Laravel错误：N+1查询、批量赋值、缓存陷阱及队列序列化陷阱。

下载

示例：防止同一用户 ID 的通知任务在 60 秒内重复执行超过 3 次

namespace App\Jobs\Middleware;

use Illuminate\Support\Facades\Redis;
use Illuminate\Queue\Middleware\ShouldQueueAfterResponse;

class ThrottleUserNotifications
{
    public function handle($job, $next)
    {
        $userId = $job->userId ?? null;
        if (! $userId) {
            return $next($job);
        }

        $key = "throttle:notify:{$userId}";
        $count = (int) Redis::incr($key);

        if ($count === 1) {
            Redis::expire($key, 60); // TTL 60 秒
        }

        if ($count release(60); // 60 秒后再试
    }
}

必须用 Redis::incr() 而不是 PHP 变量计数——队列 worker 是多进程的，内存不共享
$job->release(60) 是安全退出方式；别用 return 空值或抛异常，否则会进 failed_jobs 表
这个中间件不返回响应，也不影响 HTTP 流程，只控制当前 job 是否往下走

如何绑定到具体队列任务上

队列中间件不是注册到 Kernel.php，而是在 Job 类里通过 $middleware 属性声明：

namespace App\Jobs;

use App\Jobs\Middleware\ThrottleUserNotifications;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;

class SendNotification implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public $middleware = [
        ThrottleUserNotifications::class,
    ];

    public $userId;

    public function __construct($userId)
    {
        $this->userId = $userId;
    }

    public function handle()
    {
        // 实际发送逻辑
    }
}