Questa pagina si riferisce a Laravel 13 e a Framework
v13.42.0. Non tratta l’uso di base delle code, ma come si combinano le impostazioni di retry e quale ha la precedenza.Separare il numero di tentativi dalla scadenza
In Laravel un “tentativo” non è solo una chiamata riuscita ahandle(). Anche le eccezioni non gestite, release(), i rilasci da parte di middleware come WithoutOverlapping o RateLimited e i timeout consumano tentativi. Se non specifichi nulla, il worker tenta il job una sola volta.
Tries: limitare il numero di tentativi
Puoi dichiarare un limite per singolo job con l’attributo Tries. L’impostazione del job ha la precedenza su --tries del worker.
tries(). Questo metodo ha la precedenza sull’attributo Tries.
RetryFor: definire una finestra temporale
Per limitare i retry in base al tempo trascorso dall’inserimento in coda anziché al numero, usa RetryFor. Un semplice argomento posizionale è un numero di secondi, e puoi anche passare minutes e hours come argomenti con nome.
RetryFor registra la scadenza dei retry nel payload del job. Il worker non avvia nuovi tentativi di un job oltre quella scadenza. Se il job ha un metodo retryUntil() o una proprietà retryUntil, questa ha la precedenza su RetryFor. Inoltre, nei job in cui retryUntil è attivo, la scadenza temporale ha la precedenza su Tries.
retryUntil() è adatto quando la scadenza dipende dal contenuto del job, come l’orario previsto di ripristino di un servizio esterno o una scadenza di business.
Limitare le eccezioni non gestite
A volte vuoi continuare a consentire le chiamate manuali arelease() e i rilasci durante l’attesa di un lock, ma fallire presto quando le eccezioni non gestite si ripetono. In questo caso specifica Tries e MaxExceptions separatamente.
MaxExceptions non conta i retry causati da release().
Per impostazione predefinita, i tentativi in cui il processo si è bloccato (ad esempio per memoria insufficiente) non contano come eccezioni per MaxExceptions. Se anche i crash devono contare come eccezioni, aggiungi CountCrashesAsExceptions.
Impostare l’intervallo tra i retry
Un job che lancia un’eccezione viene normalmente rilasciato di nuovo nella coda. Puoi impostare l’attesa prima del tentativo successivo con l’attributoBackoff o con il metodo backoff().
Intervallo fisso
backoff(). backoff() ha la precedenza sull’attributo Backoff.
--backoff del worker.
Rilasciare i job in attesa con lo stesso backoff
Per eseguire di nuovo un job più tardi senza lanciare un’eccezione, ad esempio quando un’API esterna risponde “in elaborazione”, usareleaseUsingBackoff(). Il job viene rilasciato con il valore dell’array di backoff del job che corrisponde al tentativo corrente. Esauriti i valori viene usato l’ultimo, e senza backoff il job viene rilasciato immediatamente.
releaseUsingBackoff() hanno scopi diversi.
- In caso di eccezione: il job non è stato elaborato, quindi Laravel lo rilascia usando il backoff.
- Rilascio manuale: l’elaborazione in sé è corretta, ma il job viene rieseguito più tardi, quando lo stato esterno cambia.
releaseUsingBackoff() deriva da Backoff o backoff() del job. Per indicare esplicitamente un’attesa diversa in un rilascio manuale, usa release(secondi).
Esempio combinato
Il job seguente viene ritentato al massimo per un’ora e tollera fino a 3 eccezioni non gestite. In caso di eccezione e nei rilasci manuali durante l’attesa del pagamento, usa intervalli di 10, 30 e 60 secondi.RetryFor, il worker usa la scadenza anziché Tries(25) come limite normale dei tentativi. Se specifichi entrambi, decidi se la regola principale è la scadenza temporale o il limite sul numero, e fissa questa intenzione con dei test. MaxExceptions si applica indipendentemente da entrambi.
Precedenza delle impostazioni
Quando mescoli impostazioni del job e del worker, il seguente ordine di precedenza facilita le decisioni.
Quando esiste una scadenza da
retryUntil o RetryFor, il worker la privilegia rispetto al numero di tries. Se usi insieme RetryFor e retryUntil(), prevale il retryUntil() dinamico.
Come scegliere
- Se la scadenza per attendere il ripristino di un servizio esterno è chiara, usa
RetryFor. Se la scadenza viene decisa a runtime, usaretryUntil(). - Per i rate limit delle API e il controllo dello stato dei pagamenti, usa
BackoffereleaseUsingBackoff(). - Per tollerare molte attese temporanee di lock ma poche eccezioni reali, combina
TrieseMaxExceptions. - Nelle elaborazioni in cui i retry accumulano effetti collaterali, progetta non solo il numero di tentativi ma anche l’idempotenza e il controllo dei duplicati lato API esterna.
Puoi specificare
Tries e RetryFor anche su listener di eventi e notifiche in coda. Verifica che il payload della destinazione che usi abbia lo stesso contratto di retry.Link di riferimento
- Documentazione ufficiale di Laravel: Max job attempts and timeout
- Documentazione ufficiale di Laravel: Time-based attempts
- Documentazione ufficiale di Laravel: Rilascio manuale e
releaseUsingBackoff - Documentazione ufficiale di Laravel: Backoff dei job falliti
- Attributo
RetryFor - Attributi
Backoff,TrieseMaxExceptions Queue::getJobExpirationInteractsWithQueue::releaseUsingBackoff