本文介绍如何在 laravel 中利用原生的唯一性约束机制，确保同一类任务（含相同参数）在队列中仅实际执行一次，避免重复处理，适用于如缓存更新、统计刷新等幂等性敏感场景。
本文介绍如何在 laravel 中利用原生的唯一性约束机制，确保同一类任务（含相同参数）在队列中仅实际执行一次，避免重复处理，适用于如缓存更新、统计刷新等幂等性敏感场景。
Laravel 自 8.12 版本起正式引入了 Unique Jobs（唯一任务） 功能，通过 ShouldBeUnique 接口与底层队列驱动（如 Redis、Database、DynamoDB）协同工作，可精准控制任务的去重逻辑——不仅支持“同类型任务全局唯一”，还可按队列名、任务参数、时间窗口等维度精细化定义唯一性范围。
✅ 基础用法：让任务自动去重
只需在 Job 类中实现 ShouldBeUnique 接口，并可选配置 uniqueId() 和 uniqueFor() 方法：
<?php namespace App\Jobs;
use Illuminate\Bus\Queueable;
use Illuminate\Contracts\Queue\ShouldBeUnique;
use Illuminate\Foundation\Bus\Dispatchable;
use Illuminate\Queue\InteractsWithQueue;
use Illuminate\Queue\SerializesModels;
class UpdateNumClients implements ShouldBeUnique
{
use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
public function __construct(public int $tenantId)
{
// 参数将参与唯一性哈希计算
}
public function handle(): void
{
// 执行客户端数量更新逻辑
\App\Models\Tenant::findOrFail($this->tenantId)
->updateClientCount();
}
}
当该任务被多次调度（如 UpdateNumClients::dispatch(123) 被调用 5 次），Laravel 会在入队前检查 Redis（默认）中是否存在相同 uniqueId 的未完成记录；若存在，则跳过本次入队，后续新调度会自动覆盖旧的待执行任务（即“延迟执行至最后一次调度”），完美契合需求。
? 进阶控制：自定义唯一作用域
可通过重写以下方法进一步细化行为：
| 方法 | 说明 | 示例 |
|---|---|---|
| uniqueId() | 定义唯一标识符（默认为类名+序列化参数的 SHA256） | return 'update_clients_'.$this->tenantId; |
| uniqueFor() | 设置唯一性有效期（秒），超时后允许新任务入队 | return 300; // 5 分钟内只执行一次 |
| uniqueVia() | 指定唯一性存储驱动（需队列驱动支持） | return new \Illuminate\Queue\UniqueLock(); |
例如，限制每租户每小时最多执行一次：
public function uniqueFor(): int
{
return 3600; // 1 小时
}
public function uniqueId(): string
{
return 'update_clients_tenant_'.$this->tenantId;
}
⚠️ 注意事项与最佳实践
- 依赖 Redis 或支持原子锁的驱动：ShouldBeUnique 默认依赖 Redis 的 SETNX 实现，若使用 database 驱动，请确保 jobs 表具备唯一索引支持（Laravel 9.24+ 已优化兼容性）；
- 参数变更即视为不同任务：$tenantId = 123 与 $tenantId = 456 视为两个独立唯一键，互不影响；
- 避免在 handle() 中修改影响 uniqueId() 的属性：否则可能导致去重失效；
- 失败任务仍占用唯一锁：建议配合 tries 和 backoff 策略，并考虑使用 failed() 方法清理异常状态；
- 测试时启用 sync 队列需注意：同步模式下不触发唯一性检查，务必在 redis 或 database 驱动下验证逻辑。
✅ 总结
Laravel 原生的 ShouldBeUnique 是解决“多次调度、一次执行”问题的标准方案，无需第三方包或手动维护去重表。它轻量、可靠、可扩展，结合参数化唯一 ID 与 TTL 控制，能优雅支撑高并发下的幂等任务调度。对于 UpdateNumClients 这类状态刷新型任务，推荐直接采用该机制，并根据业务 SLA 合理设置 uniqueFor 时长，兼顾实时性与资源效率。
