Ausführungssteuerung von Queue-Jobs

Überblick

Die Queue-Funktionen von Laravel bieten zwei Arten der Ausführungssteuerung: Deduplizierung (Unique) und Debouncing. Beide dienen dazu, „bei mehrfachem Dispatchen desselben Jobs unnötige Ausführungen zu vermeiden”, verhalten sich jedoch unterschiedlich.

Funktion	Interface / Attribut	Zweck
Unique Jobs	`ShouldBeUnique`	Sicherstellen, dass in der Queue nur ein Exemplar desselben Jobs existiert
Unique Until Processing	`ShouldBeUniqueUntilProcessing`	Eindeutigkeitsbeschränkung nur bis zum Beginn der Verarbeitung
Debounced Jobs	`#[DebounceFor]`	Bei mehreren Dispatches in kurzer Zeit nur den zuletzt eingereihten ausführen

Unique Jobs und Debounced Jobs sind gegenseitig ausschließend. Implementieren Sie in Jobs, die das Attribut DebounceFor verwenden, nicht ShouldBeUnique.

Unique Jobs — `ShouldBeUnique`

Solange ein identischer Job in der Queue vorhanden ist, werden weitere Dispatches ignoriert.

<?php

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

class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
{
    // Zusätzliche Methoden sind nicht erforderlich
}

Solange UpdateSearchIndex in der Queue liegt (oder gerade verarbeitet wird), werden Versuche, denselben Job zu dispatchen, ignoriert.

Eindeutigkeitsbeschränkung mit einem Schlüssel einschränken — `UniqueFor` + `uniqueId()`

Wenn Sie in derselben Job-Klasse „Update von Produkt A” und „Update von Produkt B” als separate Jobs behandeln möchten, definieren Sie den Schlüssel über die Methode uniqueId().

<?php

namespace App\Jobs;

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

#[UniqueFor(3600)] // Sperre wird nach einer Stunde automatisch aufgehoben
class UpdateSearchIndex implements ShouldQueue, ShouldBeUnique
{
    public function __construct(public readonly int $productId)
    {
    }

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

Der von uniqueId() zurückgegebene Wert dient als Schlüssel für den Cache-Lock.
Wird #[UniqueFor(Sekunden)] angegeben, wird die Sperre nach Ablauf dieser Sekunden automatisch aufgehoben (Failsafe für Jobs, die nicht verarbeitet werden).

Cache-Treiber angeben — `uniqueVia()`

Wenn Sie einen anderen als den Standard-Cache-Treiber verwenden möchten, implementieren Sie uniqueVia().

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

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

Unique Jobs benötigen einen Cache-Treiber, der atomare Locks unterstützt (redis, database, memcached, dynamodb, file, array).

`ShouldBeUnique` vs. `ShouldBeUniqueUntilProcessing`

Der Lock von ShouldBeUnique bleibt bestehen, bis der Job abgeschlossen oder das Retry-Limit erreicht ist. Das kann in bestimmten Fällen zum Problem werden. Beispiel: In der Queue liegt ein UpdateSearchIndex(product_id: 42), und Sie möchten unmittelbar nach Beginn der Verarbeitung denselben Job erneut dispatchen. Mit ShouldBeUnique gelangt der zweite Job erst nach Abschluss der Verarbeitung in die Queue. In diesem Fall verwenden Sie ShouldBeUniqueUntilProcessing. Da der Lock unmittelbar vor Beginn der Verarbeitung freigegeben wird, ist ein erneuter Dispatch möglich, sobald der Worker den Job entnimmt.

<?php

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

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

Zusammenfassender Vergleich

	`ShouldBeUnique`	`ShouldBeUniqueUntilProcessing`
Zeitpunkt der Lock-Freigabe	Nach Abschluss / Fehlschlag	Unmittelbar vor Verarbeitungsbeginn
Doppelter Dispatch während der Verarbeitung	Ignoriert	Einreihbar
Anwendungsfall	Parallele Ausführung vollständig verhindern	Nach der Verarbeitung sofort den nächsten Job einreihen

Debounced Jobs — `#[DebounceFor]`

Das Attribut DebounceFor ist eine in Laravel 13 hinzugefügte Funktion.

Wird derselbe Job in kurzer Zeit viele Male dispatched, wird nur der zuletzt eingereihte Job ausgeführt. Es handelt sich um dasselbe Konzept wie das Debouncing im Web-Frontend.

<?php

namespace App\Jobs;

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

#[DebounceFor(30)] // Innerhalb von 30 Sekunden erneut dispatchen wird ignoriert (nur der zuletzt eingereihte Job wird ausgeführt)
class UpdateSearchIndex implements ShouldQueue
{
    use Queueable;

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

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

Der von debounceId() zurückgegebene Wert identifiziert den Job (das Debouncing wird pro Produkt-ID unabhängig angewendet).
Selbst wenn innerhalb von 30 Sekunden 10-mal mit derselben productId dispatched wird, wird nur der letzte Job ausgeführt.

`maxWait` — Obergrenze für die Wartezeit

Bei häufig aktualisierten Daten könnte das Debouncing endlos weitergehen und der Job nie ausgeführt werden. Mit maxWait legen Sie eine maximale Verzögerung fest.

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

In diesem Beispiel wird der Job spätestens 120 Sekunden nach dem ersten Dispatch garantiert ausgeführt (selbst wenn das 30-Sekunden-Debouncing andauert, kommt es nach 120 Sekunden zum Timeout).

Cache-Treiber angeben — `debounceVia()`

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

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

`JobDebounced`-Event

Ein Job, der von einem nachfolgenden Dispatch überschrieben wurde, wird aus der Queue entfernt und löst das Event Illuminate\Queue\Events\JobDebounced aus. Indem Sie dieses Event abonnieren, können Sie zurückgesetzte Jobs verfolgen und überwachen.

Welche Variante sollten Sie wählen?

Anwendungsfall	Empfehlung
Zwei oder mehr identische Verarbeitungen in der Queue ergeben keinen Sinn	`ShouldBeUnique`
Parallele Ausführung einschließlich der Verarbeitung verhindern	`ShouldBeUnique`
Sobald der Worker den Job entnimmt, den nächsten einreihen	`ShouldBeUniqueUntilProcessing`
Auch wenn Nutzer den Speichern-Button mehrfach drücken, nur einmal ausführen	`#[DebounceFor]`
Bei jeder Modelländerung Suchindex neu aufbauen (bei Massenupdates)	`#[DebounceFor]` + `maxWait`

Interne Implementierung

Lock-Mechanismus von Unique Jobs

Wenn ein ShouldBeUnique-Job dispatched wird, holt Laravel intern einen atomaren Lock über den Cache. Der Lock-Schlüssel hat folgendes Format:

laravel_unique_job:{Job-Klassenname}:{uniqueId()}

Kann der Lock nicht erworben werden (weil ein anderer Job ihn hält), wird der Job nicht in die Queue aufgenommen.

Implementierung von Debounced Jobs

DebounceFor verwendet intern einen Cache-Eintrag, der das „Debounce-Fenster” verwaltet. Bei jedem neuen Dispatch geschieht Folgendes:

Der bestehende Job wird aus der Queue entfernt (JobDebounced-Event wird ausgelöst).
Der neue Job wird in die Queue aufgenommen (mit der Verzögerung der Debounce-Sekunden).
Der Timer im Cache wird zurückgesetzt.

Ist maxWait angegeben, wird zusätzlich der Zeitstempel des ersten Dispatches erfasst, um zu verhindern, dass das Debouncing die maxWait-Sekunden ab diesem Zeitpunkt überschreitet.

KI-Entwicklung

Design Patterns

Paketentwicklung

Anwendungsstruktur

Neue Funktionen in Laravel 13

Eloquent im Detail

Validierungserweiterungen

Erweiterung der Authentifizierung

Sicherheit

Tests

テスト

Ausführungssteuerung von Queue-Jobs

Überblick

Unique Jobs — `ShouldBeUnique`

Eindeutigkeitsbeschränkung mit einem Schlüssel einschränken — `UniqueFor` + `uniqueId()`

Cache-Treiber angeben — `uniqueVia()`

`ShouldBeUnique` vs. `ShouldBeUniqueUntilProcessing`

Zusammenfassender Vergleich

Debounced Jobs — `#[DebounceFor]`

`maxWait` — Obergrenze für die Wartezeit

Cache-Treiber angeben — `debounceVia()`

`JobDebounced`-Event

Welche Variante sollten Sie wählen?

Interne Implementierung

Lock-Mechanismus von Unique Jobs

Implementierung von Debounced Jobs

Weiterführende Links

​Überblick

​Unique Jobs — ShouldBeUnique

​Eindeutigkeitsbeschränkung mit einem Schlüssel einschränken — UniqueFor + uniqueId()

​Cache-Treiber angeben — uniqueVia()

​ShouldBeUnique vs. ShouldBeUniqueUntilProcessing

​Zusammenfassender Vergleich

​Debounced Jobs — #[DebounceFor]

​maxWait — Obergrenze für die Wartezeit

​Cache-Treiber angeben — debounceVia()

​JobDebounced-Event

​Welche Variante sollten Sie wählen?

​Interne Implementierung

​Lock-Mechanismus von Unique Jobs

​Implementierung von Debounced Jobs

​Weiterführende Links

Überblick

Unique Jobs — `ShouldBeUnique`

Eindeutigkeitsbeschränkung mit einem Schlüssel einschränken — `UniqueFor` + `uniqueId()`

Cache-Treiber angeben — `uniqueVia()`

`ShouldBeUnique` vs. `ShouldBeUniqueUntilProcessing`

Zusammenfassender Vergleich

Debounced Jobs — `#[DebounceFor]`

`maxWait` — Obergrenze für die Wartezeit

Cache-Treiber angeben — `debounceVia()`

`JobDebounced`-Event

Welche Variante sollten Sie wählen?

Interne Implementierung

Lock-Mechanismus von Unique Jobs

Implementierung von Debounced Jobs

Weiterführende Links