> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# キュージョブの再試行ポリシー

> Tries・RetryFor・MaxExceptions・Backoffを組み合わせ、Laravel 13のキュージョブがいつ、どのくらい、どの間隔で再試行されるかを設計します。

キュージョブの再試行を設計するときは、「何回試すか」「いつまで試すか」「例外を何回許容するか」「次の試行まで何秒待つか」を分けて考えます。Laravel 13では、これらをジョブの Attribute とメソッドで宣言できます。

> [!NOTE]
>
> このページはLaravel 13とFramework `v13.42.0`を対象にしています。基本的なキューの使い方ではなく、再試行設定の組み合わせと優先順位を扱います。

| 決めること | Attribute / メソッド | 主な用途 |
| - | - | - |
| 最大試行回数 | `#[Tries]` / `tries()` | 試行回数を上限にする |
| 再試行の期限 | `#[RetryFor]` / `retryUntil()` | 投入後の時間枠内だけ試す |
| 未処理例外の上限 | `#[MaxExceptions]` | 例外が一定回数発生したら失敗させる |
| 再試行間隔 | `#[Backoff]` / `backoff()` | 例外後や手動解放後の待ち時間を決める |

## 試行回数と再試行期限を分ける

Laravelの「試行」は `handle()` が正常に呼び出された回数だけではありません。未処理例外、`release()`、`WithoutOverlapping` や `RateLimited` などのミドルウェアによる解放、タイムアウトも試行を消費します。何も指定しなければ、ワーカーはジョブを1回だけ試します。

### `Tries` — 回数を上限にする

ジョブごとの上限を `Tries` Attribute で宣言できます。ワーカーの `--tries` よりジョブ側の指定が優先されます。

```php theme={null}
<?php

namespace App\Jobs;

use Illuminate\Queue\Attributes\Tries;

#[Tries(5)]
class ProcessInvoice implements ShouldQueue
{
    // ...
}
```

実行時の条件から上限を決める場合は `tries()` メソッドを使います。このメソッドは `Tries` Attribute より優先されます。

```php theme={null}
public function tries(): int
{
    return $this->invoice->isLarge() ? 10 : 3;
}
```

### `RetryFor` — 時間枠を指定する

回数ではなく、キューへ投入されてから再試行できる時間を指定するには `RetryFor` を使います。引数なしの位置引数は秒数で、`minutes` と `hours` を名前付き引数で指定することもできます。

```php theme={null}
use Illuminate\Queue\Attributes\RetryFor;

#[RetryFor(hours: 1)]
class ProcessInvoice implements ShouldQueue
{
    // ...
}
```

次の指定はそれぞれ秒・分・時間を表します。

```php theme={null}
#[RetryFor(90)]
#[RetryFor(minutes: 10)]
#[RetryFor(hours: 4)]
#[RetryFor(hours: 1, minutes: 30)]
```

`RetryFor` はジョブのペイロードに再試行期限を記録します。ワーカーはその期限を過ぎたジョブを新たに実行しません。`retryUntil()` メソッド、または `retryUntil` プロパティがある場合は、そちらが `RetryFor` より優先されます。また、`retryUntil` が有効なジョブでは `Tries` より時間による期限が優先されます。

```php theme={null}
use DateTime;

public function retryUntil(): DateTime
{
    return now()->plus(minutes: 30);
}
```

`retryUntil()` は、外部サービスの復旧時刻や業務上の締め切りなど、ジョブの内容から期限を動的に決める場合に向いています。

## 未処理例外の上限を決める

手動の `release()` やロック取得待ちの解放は続けたい一方で、未処理例外が続いた場合は早く失敗させたいことがあります。その場合は `Tries` と `MaxExceptions` を分けて指定します。

```php theme={null}
use Illuminate\Queue\Attributes\MaxExceptions;
use Illuminate\Queue\Attributes\Tries;

#[Tries(25)]
#[MaxExceptions(3)]
class ProcessInvoice implements ShouldQueue
{
    public function handle(): void
    {
        // release() による再試行は許容し、
        // 未処理例外が3回発生したら失敗する。
    }
}
```

この例では、ジョブは最大25回まで試行できます。ただし、未処理例外が3回発生すると、試行回数の上限に達していなくても失敗します。`MaxExceptions` は、`release()` による再試行の回数を数えるための設定ではありません。

プロセスがメモリ不足などでクラッシュした試行は、デフォルトでは `MaxExceptions` の例外数に含まれません。クラッシュも例外として数える必要がある場合は、`CountCrashesAsExceptions` を追加します。

```php theme={null}
use Illuminate\Queue\Attributes\CountCrashesAsExceptions;
use Illuminate\Queue\Attributes\MaxExceptions;

#[CountCrashesAsExceptions]
#[MaxExceptions(3)]
class ProcessInvoice implements ShouldQueue
{
    // ...
}
```

## 再試行間隔を設定する

例外が発生したジョブは、通常、再びキューへ解放されます。次の試行までの待ち時間は `Backoff` Attribute または `backoff()` メソッドで設定できます。

### 固定の間隔

```php theme={null}
use Illuminate\Queue\Attributes\Backoff;

#[Backoff(10)]
class ProcessInvoice implements ShouldQueue
{
    // 未処理例外の後、10秒待って再試行する。
}
```

配列を指定すると、試行ごとに異なる間隔を設定できます。配列の要素を使い切った後は最後の値が使われます。

```php theme={null}
#[Backoff([10, 30, 60])]
class ProcessInvoice implements ShouldQueue
{
    // 1回目の再試行まで10秒、2回目まで30秒、
    // 3回目以降は60秒待つ。
}
```

条件に応じて間隔を変える場合は `backoff()` を使います。`backoff()` は `Backoff` Attribute より優先されます。

```php theme={null}
public function backoff(): int|array
{
    return $this->invoice->isFromExternalProvider()
        ? [30, 60, 300]
        : [5, 15, 30];
}
```

ジョブごとの指定がない場合は、ワーカーの `--backoff` が使われます。

```shell theme={null}
php artisan queue:work redis --tries=3 --backoff=10
```

## 待機中のジョブを同じバックオフで解放する

外部APIが「処理中」を返したときなど、例外を投げずにジョブを後で再実行したい場合は `releaseUsingBackoff()` を使います。ジョブに設定したバックオフ配列のうち、現在の試行に対応する値で解放します。値を使い切った場合は最後の値が使われ、バックオフがなければ即時解放されます。

```php theme={null}
<?php

namespace App\Jobs;

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

#[Backoff([10, 30, 60])]
class CheckPaymentStatus implements ShouldQueue
{
    use Queueable;

    public function handle(): void
    {
        if ($this->paymentIsPending()) {
            $this->releaseUsingBackoff();

            return;
        }

        // 決済完了後の処理
    }

    private function paymentIsPending(): bool
    {
        // 決済サービスの状態を確認する。
        return true;
    }
}
```

例外時の自動解放と、`releaseUsingBackoff()` による手動解放は目的が異なります。

* **例外時**：ジョブが処理できなかったため、Laravelがバックオフを使って解放する。
* **手動解放**：処理自体は正常だが、外部状態が変わるまで後で再実行する。

`releaseUsingBackoff()` の待ち時間はジョブの `Backoff` または `backoff()` を参照します。手動解放で別の待ち時間を明示したい場合は、`release(秒数)` を使います。

## 組み合わせの例

次のジョブは、最大1時間だけ再試行し、未処理例外は3回まで許容します。例外時または決済待ちの手動解放では、10秒・30秒・60秒の間隔を使います。

```php theme={null}
<?php

namespace App\Jobs;

use Illuminate\Contracts\Queue\ShouldQueue;
use Illuminate\Foundation\Queue\Queueable;
use Illuminate\Queue\Attributes\Backoff;
use Illuminate\Queue\Attributes\MaxExceptions;
use Illuminate\Queue\Attributes\RetryFor;
use Illuminate\Queue\Attributes\Tries;

#[Tries(25)]
#[RetryFor(hours: 1)]
#[MaxExceptions(3)]
#[Backoff([10, 30, 60])]
class ProcessInvoice implements ShouldQueue
{
    use Queueable;

    public function handle(): void
    {
        // 外部サービスを呼び出して請求書を処理する。
    }
}
```

`RetryFor` がある場合、ワーカーは `Tries(25)` ではなく期限を基準に通常の試行上限を判断します。両方を指定するなら、**時間による期限を主軸にするのか、回数による上限を主軸にするのか**を決め、意図をテストで固定します。`MaxExceptions` はそのどちらとも別に適用されます。

## 設定の優先順位

ジョブとワーカーの設定を混在させるときは、次の優先順位で考えると判断しやすくなります。

| 対象 | 優先される設定 | フォールバック |
| - | - | - |
| 最大試行回数 | `tries()` | `#[Tries]`、`queue:work --tries` |
| 再試行期限 | `retryUntil` メソッド / プロパティ | `#[RetryFor]` |
| 未処理例外の上限 | `#[MaxExceptions]` | 指定なしなら上限なし |
| 例外後のバックオフ | `backoff()` | `#[Backoff]`、`queue:work --backoff` |
| 手動解放の待ち時間 | `releaseUsingBackoff()` のジョブ設定 | `release(秒数)` |

`retryUntil` または `RetryFor` による期限がある場合、ワーカーは `tries` の回数より期限を優先します。`RetryFor` と `retryUntil()` を同時に使う場合は、動的な `retryUntil()` が優先されます。

## 選び方

```mermaid theme={null}
flowchart TD
    A["再試行の条件を決める"] --> B{"回数で止める？"}
    B -->|はい| C["#[Tries]"]
    B -->|いいえ| D["#[RetryFor] または retryUntil()"]
    C --> E{"未処理例外だけ早く失敗？"}
    D --> E
    E -->|はい| F["#[MaxExceptions]"]
    E -->|いいえ| G["不要"]
    F --> H{"待機時間を変える？"}
    G --> H
    H -->|はい| I["#[Backoff] / backoff()"]
    H -->|状態待ち| J["releaseUsingBackoff()"]
    H -->|いいえ| K["ワーカーの既定値"]
```

* 外部サービスの復旧を待つ期限が明確なら `RetryFor`、期限が実行時に決まるなら `retryUntil()`。
* APIのレート制限や決済状態の確認には `Backoff` と `releaseUsingBackoff()`。
* 一時的なロック待ちを多く許容し、実際の例外は少なくしたいなら `Tries` と `MaxExceptions` を組み合わせる。
* 再試行が副作用を重ねる処理では、試行回数だけでなく冪等性と外部API側の重複制御も設計する。

> [!NOTE]
>
> `Tries` と `RetryFor` は、キューに入るイベントリスナーや通知にも指定できます。利用する対象のペイロードが同じ再試行契約を持つことを確認してください。

## 参考リンク

* [Laravel公式ドキュメント — 最大試行回数とタイムアウト](https://github.com/laravel/docs/blob/13.x/queues.md#max-job-attempts-and-timeout)
* [Laravel公式ドキュメント — 時間ベースの試行](https://github.com/laravel/docs/blob/13.x/queues.md#time-based-attempts)
* [Laravel公式ドキュメント — 手動解放と `releaseUsingBackoff`](https://github.com/laravel/docs/blob/13.x/queues.md#manually-releasing-a-job)
* [Laravel公式ドキュメント — 失敗ジョブのバックオフ](https://github.com/laravel/docs/blob/13.x/queues.md#dealing-with-failed-jobs)
* [`RetryFor` Attribute](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/Attributes/RetryFor.php)
* [`Backoff`・`Tries`・`MaxExceptions` Attribute](https://github.com/laravel/framework/tree/v13.42.0/src/Illuminate/Queue/Attributes)
* [`Queue::getJobExpiration`](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/Queue.php)
* [`InteractsWithQueue::releaseUsingBackoff`](https://github.com/laravel/framework/blob/v13.42.0/src/Illuminate/Queue/InteractsWithQueue.php)


## Related topics

- [Laravel 13 新機能まとめ](https://kawax.biz/jp/blog/laravel-13-new-features.md)
- [パッケージのキュージョブと更新時の互換性](https://kawax.biz/jp/advanced/package-queue-jobs.md)
- [キューとジョブ](https://kawax.biz/jp/queues.md)
- [キュージョブの実行制御](https://kawax.biz/jp/advanced/queue-job-control.md)
- [バージョニング方針](https://kawax.biz/jp/versioning.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.