Diese Seite bezieht sich auf Laravel 13 und Framework
v13.42.0. Sie behandelt nicht die grundlegende Verwendung von Queues, sondern wie sich Retry-Einstellungen kombinieren und welche Vorrang hat.Anzahl der Versuche und Frist trennen
Ein „Versuch“ in Laravel ist nicht nur ein erfolgreicher Aufruf vonhandle(). Auch unbehandelte Exceptions, release(), Freigaben durch Middleware wie WithoutOverlapping oder RateLimited sowie Timeouts verbrauchen Versuche. Ohne Angabe versucht der Worker den Job nur einmal.
Tries: Anzahl der Versuche begrenzen
Eine Obergrenze pro Job deklarieren Sie mit dem Attribut Tries. Die Angabe am Job hat Vorrang vor --tries des Workers.
tries(). Diese Methode hat Vorrang vor dem Attribut Tries.
RetryFor: ein Zeitfenster festlegen
Um Wiederholungen nicht nach Anzahl, sondern nach der Zeit seit dem Einreihen in die Queue zu begrenzen, verwenden Sie RetryFor. Ein einfaches Positionsargument ist eine Anzahl Sekunden. Sie können minutes und hours auch als benannte Argumente angeben.
RetryFor speichert die Frist im Payload des Jobs. Der Worker startet keine neuen Versuche eines Jobs, dessen Frist abgelaufen ist. Hat der Job eine Methode retryUntil() oder eine Eigenschaft retryUntil, hat diese Vorrang vor RetryFor. Bei Jobs mit wirksamem retryUntil hat die zeitbasierte Frist außerdem Vorrang vor Tries.
retryUntil() eignet sich, wenn sich die Frist aus dem Inhalt des Jobs ergibt, etwa aus der erwarteten Wiederherstellung eines externen Dienstes oder einem geschäftlichen Stichtag.
Obergrenze für unbehandelte Exceptions festlegen
Manchmal möchten Sie manuellerelease()-Aufrufe und Freigaben beim Warten auf einen Lock weiter zulassen, bei wiederholten unbehandelten Exceptions aber schnell fehlschlagen. Geben Sie dann Tries und MaxExceptions getrennt an.
MaxExceptions zählt keine Wiederholungen durch release().
Versuche, bei denen der Prozess abgestürzt ist (etwa wegen Speichermangels), zählen standardmäßig nicht zu den Exceptions für MaxExceptions. Wenn auch Abstürze als Exceptions zählen sollen, fügen Sie CountCrashesAsExceptions hinzu.
Abstand zwischen Versuchen festlegen
Ein Job, der eine Exception wirft, wird normalerweise wieder in die Queue freigegeben. Die Wartezeit bis zum nächsten Versuch legen Sie mit dem AttributBackoff oder der Methode backoff() fest.
Fester Abstand
backoff(). backoff() hat Vorrang vor dem Attribut Backoff.
--backoff des Workers verwendet.
Wartende Jobs mit demselben Backoff freigeben
Wenn Sie einen Job später erneut ausführen möchten, ohne eine Exception zu werfen, etwa weil eine externe API „in Bearbeitung“ meldet, verwenden SiereleaseUsingBackoff(). Der Job wird mit dem Wert aus seinem Backoff-Array freigegeben, der zum aktuellen Versuch gehört. Sind die Werte verbraucht, wird der letzte verwendet. Ohne Backoff wird der Job sofort freigegeben.
releaseUsingBackoff() verfolgen unterschiedliche Zwecke.
- Bei einer Exception: Der Job konnte nicht verarbeitet werden, daher gibt Laravel ihn mit dem Backoff frei.
- Manuelle Freigabe: Die Verarbeitung selbst ist in Ordnung, der Job läuft aber erst später erneut, wenn sich der externe Zustand geändert hat.
releaseUsingBackoff() stammt aus Backoff oder backoff() des Jobs. Um für eine manuelle Freigabe explizit eine andere Wartezeit anzugeben, verwenden Sie release(Sekunden).
Kombiniertes Beispiel
Der folgende Job wird höchstens eine Stunde lang wiederholt und toleriert bis zu 3 unbehandelte Exceptions. Bei Exceptions und bei manuellen Freigaben während des Wartens auf die Zahlung verwendet er Abstände von 10, 30 und 60 Sekunden.RetryFor vorhanden, verwendet der Worker die Frist statt Tries(25) als normale Obergrenze der Versuche. Wenn Sie beides angeben, entscheiden Sie, ob die zeitbasierte Frist oder die anzahlbasierte Obergrenze die Hauptregel ist, und sichern Sie diese Absicht mit Tests ab. MaxExceptions gilt unabhängig von beiden.
Vorrang der Einstellungen
Wenn Sie Job- und Worker-Einstellungen mischen, erleichtert die folgende Rangfolge die Entscheidung.
Gibt es eine Frist durch
retryUntil oder RetryFor, hat sie für den Worker Vorrang vor der Anzahl aus tries. Wenn Sie RetryFor und retryUntil() zusammen verwenden, hat das dynamische retryUntil() Vorrang.
Auswahl
- Ist die Frist für das Warten auf die Wiederherstellung eines externen Dienstes klar, verwenden Sie
RetryFor. Ergibt sich die Frist erst zur Laufzeit, verwenden SieretryUntil(). - Für API-Rate-Limits und die Prüfung von Zahlungsstatus verwenden Sie
BackoffundreleaseUsingBackoff(). - Um viele vorübergehende Lock-Wartezeiten, aber nur wenige echte Exceptions zuzulassen, kombinieren Sie
TriesundMaxExceptions. - Bei Verarbeitungen, deren Wiederholung Nebenwirkungen vervielfacht, planen Sie neben der Anzahl der Versuche auch Idempotenz und die Duplikatkontrolle auf Seiten der externen API.
Tries und RetryFor können Sie auch für Event-Listener und Benachrichtigungen in der Queue angeben. Prüfen Sie, dass der Payload des jeweiligen Ziels denselben Retry-Vertrag trägt.Referenz-Links
- Offizielle Laravel-Dokumentation: Max job attempts and timeout
- Offizielle Laravel-Dokumentation: Time-based attempts
- Offizielle Laravel-Dokumentation: Manuelle Freigabe und
releaseUsingBackoff - Offizielle Laravel-Dokumentation: Backoff für fehlgeschlagene Jobs
- Attribut
RetryFor - Attribute
Backoff,TriesundMaxExceptions Queue::getJobExpirationInteractsWithQueue::releaseUsingBackoff