本文介绍如何利用 laravel 原生的「唯一任务（unique jobs）」机制，确保同一类、相同参数的任务在队列中仅保留一个实例，避免重复调度导致的冗余执行。
本文介绍如何利用 laravel 原生的「唯一任务（unique jobs）」机制，确保同一类、相同参数的任务在队列中仅保留一个实例，避免重复调度导致的冗余执行。
在高并发或事件驱动场景中（如用户频繁触发统计更新、缓存刷新、状态同步等），同一个任务（如 UpdateNumClients）可能被短时间内多次调度并推入队列。若不做控制，队列中将堆积多个几乎相同的任务，最终依次执行，不仅浪费资源，还可能导致数据不一致或延迟加剧。
Laravel 自 8.0 起原生支持基于队列的唯一性约束（via ShouldBeUnique 接口），无需第三方包即可实现“同参数任务去重”——即：当新任务入队时，若队列中已存在未执行、且具有相同唯一标识（默认为类名 + 序列化参数）的待处理任务，则自动跳过本次调度。
✅ 实现步骤
-
让任务类实现 ShouldBeUnique 接口
并可选定义 uniqueId() 或 uniqueFor() 方法来自定义去重逻辑：
<?php namespace App\Jobs;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldBeUnique;
use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
class UpdateNumClients implements ShouldBeUnique, ShouldQueue
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public int $clientId;
public function __construct(int $clientId)
{
$this->clientId = $clientId;
}
public function handle(): void
{
// 执行客户端数量更新逻辑
\Log::info("Updating client count for ID: {$this->clientId}");
// ... 实际业务代码
}
// 可选：自定义唯一键（默认已基于类名+参数生成）
// public function uniqueId(): string
// {
// return 'update_num_clients_' . $this->clientId;
// }
// 可选：设置该唯一性在多少秒内有效（超时后允许新任务入队）
// public function uniqueFor(): int
// {
// return 3600; // 1小时
// }
}
-
正常分发任务（自动去重）
多次调用 dispatch()，Laravel 会自动检测并丢弃重复项：
// 这些调用中，只有第一个会真正进入队列；其余在入队时被拒绝 UpdateNumClients::dispatch(123); UpdateNumClients::dispatch(123); UpdateNumClients::dispatch(123);
⚠️ 注意：去重发生在任务入队阶段（即 dispatch() 时），而非消费阶段。因此需确保队列驱动支持原子操作（推荐使用 Redis；数据库驱动在高并发下可能存在竞态风险）。
? 去重原理简析
Laravel 在任务入队前，会序列化任务类名与构造参数，生成唯一哈希（如 App\Jobs\UpdateNumClients:{"clientId":123}），并以该哈希为 key 尝试在 Redis 中 SETNX（set if not exists）。若 key 已存在，则中止入队；否则写入并设置过期时间（默认 1 小时，可通过 uniqueFor() 覆盖）。
? 最佳实践建议
- 优先使用 Redis 队列驱动：unique 特性依赖原子操作，Redis 是官方推荐且最可靠的后端。
- 谨慎设计 uniqueId()：若需跨参数逻辑去重（例如忽略某些字段），应显式重写该方法。
- 监控被丢弃的任务：可通过监听 Illuminate\Queue\Events\JobFailed 或自定义 failed() 方法记录去重日志。
- 避免在 handle() 中做幂等兜底：虽然双重保障更安全，但应以队列层去重为主，业务层保持简洁。
通过 ShouldBeUnique，你无需维护外部锁表或自定义中间件，即可优雅解决“多触发、单执行”的典型队列问题——这是 Laravel 对任务治理能力的重要增强。
