Queue Job 的執行控制

概觀

Laravel 的 Queue 功能提供了 Unique（去重） 與 Debounce 兩種 Job 執行控制。皆是為了「當同一 Job 被多次 dispatch 時，省去無謂執行」的機制，但運作有所不同。

功能	介面 / Attribute	目的
Unique Jobs	`ShouldBeUnique`	保持 Queue 中同一 Job 僅存在 1 個的狀態
Unique Until Processing	`ShouldBeUniqueUntilProcessing`	僅在處理開始前保持唯一性約束
Debounced Jobs	`#[DebounceFor]`	若短時間內連續 dispatch，只執行最新 1 件

Unique Jobs 與 Debounced Jobs 為互斥。請勿於使用 DebounceFor attribute 的 Job 中實作 ShouldBeUnique。

Unique Jobs — `ShouldBeUnique`

當同一 Job 存在於 Queue 期間，將忽略追加的 dispatch。

<?php

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Contracts\Queue\ShouldBeUnique;

class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
{
    // 無需額外方法
}

當 UpdateSearchIndex 已在 Queue 中（或正在處理），再次 dispatch 同一 Job 會被忽略。

以 key 限縮唯一性約束 — `UniqueFor` + `uniqueId()`

若相同 Job 類別下希望將「商品 A 的更新」與「商品 B 的更新」視為不同 Job，可使用 uniqueId() 方法定義 key。

<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Contracts\Queue\ShouldBeUnique;
use Illuminate\Queue\Attributes\UniqueFor;

#[UniqueFor(3600)] // 1 小時後自動釋放 lock
class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
{
    public function __construct(public readonly int $productId)
    {
    }

    public function uniqueId(): string
    {
        return (string) $this->productId;
    }
}

uniqueId() 回傳的值成為 cache lock 的 key。
若指定 #[UniqueFor(秒數)]，經過該秒數後 lock 會自動釋放（作為 Job 未被處理時的 fail-safe）。

指定 Cache Driver — `uniqueVia()`

若希望使用預設 cache driver 以外者，可實作 uniqueVia()。

use Illuminate\Contracts\Cache\Repository;
use Illuminate\Support\Facades\Cache;

public function uniqueVia(): Repository
{
    return Cache::driver('redis');
}

Unique Jobs 需要支援 atomic lock 的 cache driver（redis、database、memcached、dynamodb、file、array）。

`ShouldBeUnique` vs `ShouldBeUniqueUntilProcessing`

ShouldBeUnique 的 lock 會保持至 Job 完成或達到重試上限。這在某些情境下會有問題。例： Queue 中有 1 件 UpdateSearchIndex(product_id: 42)，Worker 開始處理後想立即重新 dispatch 相同 Job。ShouldBeUnique 於處理完成前不會讓第 2 件進入 Queue。此時可使用 ShouldBeUniqueUntilProcessing。因為 lock 於處理開始前釋放，故當 Worker 取出 Job 的瞬間即可進行下次 dispatch。

<?php

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Contracts\Queue\ShouldBeUniqueUntilProcessing;

class UpdateSearchIndex implements ShouldQueue, ShouldBeUniqueUntilProcessing
{
    // ...
}

比較彙整

	`ShouldBeUnique`	`ShouldBeUniqueUntilProcessing`
lock 釋放時機	處理完成 / 失敗後	處理開始前
處理中的重複 dispatch	忽略	可進入 Queue
使用情境	希望完全防止併行執行	希望處理後立即放入下一個 Job

Debounced Jobs — `#[DebounceFor]`

DebounceFor attribute 為 Laravel 13 新增的功能。

當短時間內大量 dispatch 同一 Job 時，只執行最後 dispatch 的 1 件。與 Web 前端的 debounce 為同樣思路。

<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\DebounceFor;

#[DebounceFor(30)] // 忽略 30 秒內的再次 dispatch（僅執行最新 1 件）
class UpdateSearchIndex implements ShouldQueue
{
    use Queueable;

    public function __construct(public readonly int $productId)
    {
    }

    public function debounceId(): string
    {
        return (string) $this->productId;
    }
}

以 debounceId() 回傳的值辨識 Job（每個 product ID 有獨立的 debounce）。
即便 30 秒內以相同 productId dispatch 10 次，也只執行最後 1 件。

`maxWait` — 最大等待時間上限

於頻繁更新的資料，debounce 可能持續而使 Job 永遠不執行。可透過 maxWait 設定最大延遲時間。

#[DebounceFor(30, maxWait: 120)]
class UpdateSearchIndex implements ShouldQueue
{
    use Queueable;
    // ...
}

此例中，自初次 dispatch 起最多 120 秒後必定會執行（即便 30 秒 debounce 持續，也會於 120 秒 timeout）。

指定 Cache Driver — `debounceVia()`

use Illuminate\Contracts\Cache\Repository;
use Illuminate\Support\Facades\Cache;

public function debounceVia(): Repository
{
    return Cache::driver('redis');
}

`JobDebounced` 事件

被後續 dispatch 覆蓋的 Job 會發出 Illuminate\Queue\Events\JobDebounced 事件後從 Queue 中被刪除。透過監聽此事件可以追蹤及監視被 debounce 的 Job。

應該使用哪一個

使用情境	建議
Queue 中同一處理即便存在 2 件以上也無意義	`ShouldBeUnique`
連處理中也希望防止並行執行	`ShouldBeUnique`
Worker 取出後想立即放入下一個	`ShouldBeUniqueUntilProcessing`
即便使用者連按儲存按鈕也希望只執行 1 次	`#[DebounceFor]`
每次模型更新都重建搜尋索引（大量更新時）	`#[DebounceFor]` + `maxWait`

內部實作

Unique Jobs 的 lock 機制

當 ShouldBeUnique Job 被 dispatch 時，Laravel 內部會取得 cache 的 Atomic Lock。lock key 格式如下：

laravel_unique_job:{Job 類別名}:{uniqueId()}

若未能取得 lock（已被其他 Job 持有），Job 便不會加入 Queue。

Debounced Jobs 的實作

DebounceFor 內部使用管理「Debounce 視窗」的 cache 項目。每次有新的 dispatch 進來時：

從 Queue 移除既有 Job（發出 JobDebounced 事件）
將新 Job 加入 Queue（附帶 Debounce 秒數的延遲）
重置 cache 的計時器

若有指定 maxWait，也會記錄初次 dispatch 的時間戳記，防止超過該時刻起 maxWait 秒的 Debounce。

AI 開發

設計模式

套件開發

應用程式結構

Laravel 13 新功能

Eloquent 深入探索

驗證擴充

認證擴充

安全性

佇列

測試

概觀

Unique Jobs — `ShouldBeUnique`

以 key 限縮唯一性約束 — `UniqueFor` + `uniqueId()`

指定 Cache Driver — `uniqueVia()`

`ShouldBeUnique` vs `ShouldBeUniqueUntilProcessing`

比較彙整

Debounced Jobs — `#[DebounceFor]`

`maxWait` — 最大等待時間上限

指定 Cache Driver — `debounceVia()`

`JobDebounced` 事件

應該使用哪一個

內部實作

Unique Jobs 的 lock 機制

Debounced Jobs 的實作

參考連結

​概觀

​Unique Jobs — ShouldBeUnique

​以 key 限縮唯一性約束 — UniqueFor + uniqueId()

​指定 Cache Driver — uniqueVia()

​ShouldBeUnique vs ShouldBeUniqueUntilProcessing

​比較彙整

​Debounced Jobs — #[DebounceFor]

​maxWait — 最大等待時間上限

​指定 Cache Driver — debounceVia()

​JobDebounced 事件

​應該使用哪一個

​內部實作

​Unique Jobs 的 lock 機制

​Debounced Jobs 的實作

​參考連結

概觀

Unique Jobs — `ShouldBeUnique`

以 key 限縮唯一性約束 — `UniqueFor` + `uniqueId()`

指定 Cache Driver — `uniqueVia()`

`ShouldBeUnique` vs `ShouldBeUniqueUntilProcessing`

比較彙整

Debounced Jobs — `#[DebounceFor]`

`maxWait` — 最大等待時間上限

指定 Cache Driver — `debounceVia()`

`JobDebounced` 事件

應該使用哪一個

內部實作

Unique Jobs 的 lock 機制

Debounced Jobs 的實作

參考連結