本頁以 Laravel 13 與 Framework
v13.42.0 為對象。內容不是佇列的基本用法,而是重試設定的組合方式與優先順序。區分嘗試次數與重試期限
Laravel 的「嘗試」不只是handle() 被正常呼叫的次數。未處理例外、release()、WithoutOverlapping 或 RateLimited 等 middleware 造成的釋放,以及逾時,也都會消耗嘗試次數。如果什麼都不指定,worker 只會嘗試 Job 一次。
Tries:為次數設定上限
可以用 Tries Attribute 宣告每個 Job 的上限。Job 上的指定優先於 worker 的 --tries。
tries() 方法。此方法優先於 Tries Attribute。
RetryFor:指定時間範圍
若不以次數,而是以投入佇列後可重試的時間來限制,請使用 RetryFor。不帶名稱的位置引數代表秒數,也可以用具名引數指定 minutes 與 hours。
RetryFor 會把重試期限記錄在 Job 的 payload 中。worker 不會再啟動已超過期限的 Job。若 Job 有 retryUntil() 方法或 retryUntil 屬性,則它們優先於 RetryFor。此外,對於 retryUntil 生效的 Job,以時間為準的期限優先於 Tries。
retryUntil() 適合依 Job 內容動態決定期限的情況,例如外部服務的復原時間或業務上的截止時間。
決定未處理例外的上限
有時你希望繼續允許手動release() 或等待取得鎖時的釋放,但在未處理例外持續發生時盡早失敗。這種情況下,請分別指定 Tries 與 MaxExceptions。
MaxExceptions 並不是用來計算 release() 造成的重試次數的設定。
預設情況下,行程因記憶體不足等原因當機的嘗試,不計入 MaxExceptions 的例外數。若當機也需要算作例外,請加上 CountCrashesAsExceptions。
設定重試間隔
發生例外的 Job 通常會被重新釋放回佇列。到下一次嘗試的等待時間可以用Backoff Attribute 或 backoff() 方法設定。
固定間隔
backoff()。backoff() 優先於 Backoff Attribute。
--backoff。
以相同的退避釋放等待中的 Job
當外部 API 回傳「處理中」等情況,若想不擲出例外而稍後再次執行 Job,請使用releaseUsingBackoff()。它會使用 Job 所設定的退避陣列中對應目前嘗試的值來釋放。值用完後使用最後一個值,沒有退避時立即釋放。
releaseUsingBackoff() 的手動釋放,目的不同。
- 例外時:Job 無法處理,因此 Laravel 使用退避來釋放。
- 手動釋放:處理本身正常,但要等外部狀態改變後再稍後執行。
releaseUsingBackoff() 的等待時間參照 Job 的 Backoff 或 backoff()。若想在手動釋放時明確指定其他等待時間,請使用 release(秒數)。
組合範例
下面的 Job 最多重試 1 小時,最多允許 3 次未處理例外。在例外時或等待付款的手動釋放中,使用 10 秒、30 秒、60 秒的間隔。RetryFor 時,worker 會以期限而非 Tries(25) 作為一般的嘗試上限。若兩者都指定,請決定以時間期限為主軸,還是以次數上限為主軸,並用測試固定這個意圖。MaxExceptions 獨立於兩者套用。
設定的優先順序
混用 Job 與 worker 的設定時,依下列優先順序思考會比較容易判斷。
存在由
retryUntil 或 RetryFor 設定的期限時,worker 會優先於 tries 的次數考慮期限。同時使用 RetryFor 與 retryUntil() 時,動態的 retryUntil() 優先。
如何選擇
- 等待外部服務復原的期限明確時用
RetryFor,期限在執行時才決定時用retryUntil()。 - API 的速率限制或付款狀態的確認,使用
Backoff與releaseUsingBackoff()。 - 想大量允許暫時性的鎖等待、同時減少實際例外時,組合使用
Tries與MaxExceptions。 - 對於重試會疊加副作用的處理,不只要設計嘗試次數,也要設計冪等性與外部 API 端的重複控制。
Tries 與 RetryFor 也可以指定在進入佇列的事件監聽器與通知上。請確認所使用對象的 payload 具有相同的重試約定。