Spring Retry・Resilience4jで再試行｜@Retryable設定

Spring Boot 4（Spring Framework 7）では、再試行（リトライ）は Spring Framework 本体の @Retryable で書けます。 設定クラスに @EnableResilientMethods を付け、メソッドに @Retryable を付けます。これまで使われてきた Spring Retry は、GitHub の README で「Spring Framework 7 に置き換えられ、アーカイブされた」と案内されています。 再試行に加えてサーキットブレーカー（失敗が続いたら呼び出しを止めるしくみ）も使うなら、Resilience4j を使います。

@Configuration
@EnableResilientMethods            // これが無いと @Retryable は効かない
public class ResilienceConfig {
}

@Service
public class NotificationService {

    @Retryable(includes = RestClientException.class,
               maxRetries = 4, delay = 100, multiplier = 2, maxDelay = 1000)
    public void send(Notification n) {
        restClient.post().uri("/notify").body(n).retrieve().toBodilessEntity();
    }
}

同じ「3」でも、呼ぶ回数が違います。 Spring Framework 7 は「最初の1回＋再試行3回」、Spring Retry と Resilience4j は「最初の1回を含めて3回」です。移行のときに回数が1回増えるので気をつけます。

確認環境：Spring Boot 4.1.1・Spring Framework 7.0.9・Resilience4j 2.4.0・Spring Retry 2.0.13 の各ソース（GitHub のタグ）で、注釈の属性と既定値を確かめました。Spring Framework 7.0.9 の RetryTemplate・RetryPolicy・ExponentialBackOff と、Resilience4j 2.4.0 の core・retry・circuitbreaker はソースからビルドし、OpenJDK 21.0.10（Linux）で動かして、再試行の間隔・例外・状態の遷移を記録しました。@EnableResilientMethods とプロキシの動きは Spring Framework のリファレンスとソースで確かめています（確認日 2026年10月13日）。

どれを使うか

Spring Boot 4.1.1 の spring-boot-dependencies（依存の版をまとめて決めるファイル）には、Spring Retry と Resilience4j の版の指定がありません。 どちらも、使うときは build.gradle や pom.xml に版を書きます。Framework 7 の @Retryable は spring-context に入っているので、依存を足さずに使えます。

Spring Framework 7 の @Retryable

有効にする：@EnableResilientMethods

リファレンスでは、@Retryable と @ConcurrencyLimit は「付けただけでは意味を持たないメタデータ」で、@Configuration クラスに @EnableResilientMethods を付けて処理を有効にすると説明されています。Spring Boot 4.1.1 のソースには、これを自動で有効にする設定はありませんでした。付け忘れると、エラーも出ずに再試行されません。

@EnableResilientMethods の属性（v7.0.9 のソース）です。

@EnableResilientMethods のかわりに、RetryAnnotationBeanPostProcessor の Bean を定義しても有効になります。

@Retryable の属性と既定値（v7.0.9 のソース）

maxRetriesString・delayString・timeoutString などの String 版の属性もあり、${...} で設定ファイルの値を使えます。

@Retryable(includes = RestClientException.class,
           maxRetriesString = "${app.notify.max-retries:3}",
           delayString = "${app.notify.delay:500ms}")
public void send(Notification n) { … }

すべての再試行に失敗すると、最後に出た元の例外がそのまま呼び出し側に投げられます（リファレンスとソースの AbstractRetryInterceptor で確認）。Spring Retry の @Recover に当たる機能は無いので、代わりの処理は呼び出し側の try〜catch で書きます。

失敗した例外を記録する：MethodRetryEvent

リファレンスでは、@Retryable の処理中に、メソッドから出た例外ごとに MethodRetryEvent が発行されると説明されています。呼び出し側には最後の例外しか届かないので、途中の失敗はイベントで記録します。

@Component
public class RetryLogger {
    private static final Logger log = LoggerFactory.getLogger(RetryLogger.class);

    @EventListener
    public void onRetry(MethodRetryEvent event) {
        log.warn("retry: {} -> {}", event.getMethod().getName(), event.getFailure().toString());
    }
}

コードの一部だけ再試行する：RetryTemplate

RetryTemplate は、ラムダで渡した処理を再試行します。Spring Framework 7.0.9 のソースからビルドして動かした結果です。

var policy = RetryPolicy.builder()
        .maxRetries(4)
        .delay(Duration.ofMillis(100))
        .multiplier(2)
        .maxDelay(Duration.ofMillis(500))
        .build();

new RetryTemplate(policy).invoke(() -> callApi());

指数バックオフ（待ち時間を倍々に伸ばす方法）の間隔は 100 → 200 → 400 → 500（上限）ms になりました。jitter を付けると、間隔が毎回少しずつずれます。多くのクライアントが同じ時刻に一斉に再試行するのを避けるためです。間隔の決め方は、関連記事「指数バックオフとは？リトライ間隔の決め方とジッターの実装」で扱っています。

invoke と execute は、失敗したときの例外が違います。

execute の RetryException の中身です。

org.springframework.core.retry.RetryException: Retry policy for operation 'Rt$$Lambda/0x00007f5e6000c230' exhausted; aborting execution
   cause=java.io.IOException: io 3 exceptions=3 retryCount=2

getExceptions() で3回分の例外、getCause() で最後の例外を取れます。

includes は原因の例外も見る

includes(IOException.class) にして、3種類の例外で試しました。

ライブラリが IOException を別の例外で包んで投げる場合でも、includes に元の例外を書けば再試行されます。

timeout は「次の待ちで超えるなら、待たずにやめる」

maxRetries 10・delay 200ms・timeout 500ms で動かすと、3回呼んだところで止まりました。

Retry policy for operation '…' would exceed timeout (500ms) due to pending sleep time (200ms); preemptively aborting execution

次の待ち時間を足すと上限を超える時点で、待たずに打ち切ります。 画面の応答時間に上限がある処理では、回数より timeout で決めるほうが、利用者を待たせる時間を読みやすくなります。

不正な値のメッセージ

Invalid multiplier '0.5': must be greater than or equal to 1. A multiplier of 1 is equivalent to a fixed delay.
Invalid maxRetries (-1): must be positive or zero for no retry.

Spring Retry の現状と移行

Spring Retry の GitHub リポジトリ（spring-attic/spring-retry）の README には、次のように書かれています。

• Spring Retry は、オープンソースのプロジェクトとしては保守されていない
• Spring Framework 7 に置き換えられ、アーカイブされた
• Spring Framework の resilience 機能へ移行するよう案内している

タグの最新は v2.0.13 です。Boot 3 の既存コードで使っているなら動きますが、Boot 4 へ上げるときに移すのが自然です。

Spring Retry の @Backoff の multiplier の既定は 0（使わない）、maxDelay の既定も 0（使わない）です（v2.0.13 のソース）。Boot 4 への移行全体は、関連記事「Spring Boot 4移行の手順｜3から4の変更点一覧とチェックリスト」で扱っています。

Resilience4j の Retry と CircuitBreaker

依存（Boot 4）

Resilience4j 2.4.0 には、Boot 4 用の resilience4j-spring-boot4 があります。注釈（@Retry など）は AOP で動くので、Boot 4 の AOP スターター（spring-boot-starter-aspectj）も入れます。

// build.gradle.kts
dependencies {
    implementation("io.github.resilience4j:resilience4j-spring-boot4:2.4.0")
    implementation("org.springframework.boot:spring-boot-starter-aspectj")
    implementation("org.springframework.boot:spring-boot-starter-actuator") // 状態を見るなら
}

設定（application.yml）

resilience4j:
  retry:
    instances:
      payment:
        max-attempts: 4                    # 最初の1回を含む
        wait-duration: 200ms
        enable-exponential-backoff: true
        exponential-backoff-multiplier: 2
        exponential-max-wait-duration: 2s
        retry-exceptions:
          - java.io.IOException
          - org.springframework.web.client.ResourceAccessException
        ignore-exceptions:
          - com.example.payment.CardDeclinedException
  circuitbreaker:
    instances:
      payment:
        sliding-window-size: 20
        minimum-number-of-calls: 10
        failure-rate-threshold: 50
        wait-duration-in-open-state: 30s
        permitted-number-of-calls-in-half-open-state: 3
        automatic-transition-from-open-to-half-open-enabled: true

@Service
public class PaymentClient {

    @Retry(name = "payment")
    @CircuitBreaker(name = "payment", fallbackMethod = "fallback")
    public PaymentResult pay(PaymentRequest req) {
        return restClient.post().uri("/pay").body(req).retrieve().body(PaymentResult.class);
    }

    // 引数は元のメソッドと同じ＋最後に例外
    private PaymentResult fallback(PaymentRequest req, Throwable t) {
        return PaymentResult.pending(req.orderId());
    }
}

注釈の順番は、書いた順ではなく設定の値で決まります。 v2.4.0 のソースでは、既定の順番は Retry（LOWEST_PRECEDENCE - 5）が一番外、次に CircuitBreaker（- 4）、RateLimiter（- 3）、TimeLimiter（- 2）、Bulkhead（- 1）の順です。つまり Retry が CircuitBreaker を包み、CircuitBreaker の失敗ごとに再試行されます。

Retry の設定項目と既定値（v2.4.0 のソース）

動かした結果です。

CircuitBreaker の設定項目と既定値（v2.4.0 のソース）

既定のままでは、100回呼ぶまで OPEN になりません。 呼び出しの少ない API では、minimum-number-of-calls と sliding-window-size を小さくしないと、障害中もずっと呼び続けます。

slidingWindowSize 4・minimumNumberOfCalls 4・failureRateThreshold 50・waitDurationInOpenState 500ms・permittedNumberOfCallsInHalfOpenState 2 で、失敗・失敗・成功・失敗と呼んだ結果です。

call1 java.lang.IllegalStateException: down state=CLOSED rate=-1.0
call2 java.lang.IllegalStateException: down state=CLOSED rate=-1.0
call3 ok state=CLOSED
  遷移: State transition from CLOSED to OPEN
call4 java.lang.IllegalStateException: down state=OPEN rate=75.0
call5 io.github.resilience4j.circuitbreaker.CallNotPermittedException: CircuitBreaker 'backend' is OPEN and does not permit further calls state=OPEN rate=75.0
  （500ms 待つ）
  遷移: State transition from OPEN to HALF_OPEN
half-open call ok state=HALF_OPEN
  遷移: State transition from HALF_OPEN to CLOSED
half-open call ok state=CLOSED

4回そろうまで失敗率は -1.0（まだ計算しない）でした。4回目で失敗率 75% になり OPEN に移り、5回目は本体を呼ばずに CallNotPermittedException になりました。HALF_OPEN で2回成功して CLOSED に戻りました。3つの状態のしくみは、関連記事「サーキットブレーカーとは｜3状態の実装とリトライ可否の一覧表」で扱っています。

Retry と CircuitBreaker を重ねるときの注意

CircuitBreaker が OPEN のとき、外側の Retry は CallNotPermittedException も再試行します。OPEN にしたうえで、Retry（既定3回、待ち 10ms に変更）で包んで呼んだ結果です。

OPEN は「今は呼んでも無駄」という合図です。 再試行しても待ち時間が増えるだけなので、ignore-exceptions に io.github.resilience4j.circuitbreaker.CallNotPermittedException を入れておきます。

再試行してよい処理・よくない処理

includes を書かない @Retryable は、すべての例外を再試行します。上の × の例外まで3回呼び直すので、includes で再試行する例外をしぼります。時間切れの見分け方は、関連記事「SocketTimeoutExceptionの直し方｜Read/connectの違い」で扱っています。

@Transactional と重ねるとき

@Retryable のメソッドの中で @Transactional のメソッドを呼ぶ形にすると、失敗のたびにトランザクションが巻き戻ってから、新しいトランザクションでやり直されます。同じメソッドに両方を付けると、どちらが外側になるかは AOP の順番しだいです。@EnableResilientMethods の order の既定は LOWEST_PRECEDENCE - 1 です。トランザクションの順番の考え方は、関連記事「Spring @Transactionalが効かない原因8選｜ロールバックの直し方」で扱っています。

@Retryable が効かない原因

同じクラスの中からの呼び出しは、AOP を使う機能に共通の落とし穴です。this.send() はプロキシを通らずに本体を直接呼ぶので、@Retryable が働きません。

@Service
public class NotificationService {

    public void sendAll(List<Notification> list) {
        list.forEach(this::send);      // ← 同じクラスの中なので再試行されない
    }

    @Retryable(includes = RestClientException.class)
    public void send(Notification n) { … }
}

send を別の @Service に移し、そちらを DI で受け取って呼ぶと、プロキシを通ります。プロキシのしくみは、関連記事「Spring AOPの使い方｜@Aspectのコード全文と指示子一覧」で扱っています。

同時実行数をしぼる：@ConcurrencyLimit

Spring Framework 7 には、同じメソッドを同時に動かせる数を制限する @ConcurrencyLimit もあります。@EnableResilientMethods で一緒に有効になります。

@ConcurrencyLimit(10)
public Report build(Long id) { … }

リファレンスでは、スレッドプールの大きさの制限と同じ効果を持ち、数の制限が無い仮想スレッドと組み合わせるときに役立つと説明されています。

よくある質問

Q. Boot 3 でも Spring Framework 7 の @Retryable は使えますか。 A. 使えません。Boot 3 は Spring Framework 6 系で、org.springframework.resilience パッケージは 7.0 からです。Boot 3 では Spring Retry か Resilience4j を使います。

Q. Spring Framework 7 の @Retryable はリアクティブ（Mono・Flux）でも使えますか。 A. リファレンスでは、戻り値が Mono などのメソッドにも使え、Reactor の再試行で包まれると説明されています。

Q. 設定ファイルで回数を変えたいです。 A. Framework 7 では maxRetriesString = "${app.retry.max:3}" のように String 版の属性を使います。Resilience4j は resilience4j.retry.instances.<name>.max-attempts で変えられます。

Q. 再試行の回数はどれくらいが目安ですか。 A. 画面からの呼び出しなら、利用者が待てる時間（数秒）に収まる回数にします。Framework 7 の timeout で全体の上限を決めておくと、回数と待ち時間をあとで変えても上限は守られます。

まとめ

• Boot 4 では Spring Framework 7 の @Retryable ＋ @EnableResilientMethods。追加の依存なし
• Spring Retry はアーカイブ済み。Boot 4.1.1 の依存管理にも版の指定は無い
• maxRetries = 3 は最大4回、Spring Retry と Resilience4j の maxAttempts = 3 は最大3回
• includes は原因の例外も見る。書かないとすべての例外を再試行する
• timeout は次の待ちで上限を超えるなら待たずにやめる
• サーキットブレーカーは Resilience4j。既定では100回呼ぶまで OPEN にならない
• Retry で CircuitBreaker を包むなら、CallNotPermittedException は再試行しない
• 効かない原因の多くは、有効化の付け忘れと同じクラスの中からの呼び出し

参考・出典

確認日はいずれも 2026年10月13日です。

• Spring Framework Reference「Resilience Features」：https://docs.spring.io/spring-framework/reference/core/resilience.html
• Spring Framework v7.0.9 ソース（Retryable・EnableResilientMethods・AbstractRetryInterceptor・RetryTemplate・RetryPolicy）：https://github.com/spring-projects/spring-framework/tree/v7.0.9
• Spring Boot v4.1.1 ソース（spring-boot-dependencies）：https://github.com/spring-projects/spring-boot/tree/v4.1.1
• Spring Retry（README・v2.0.13 のソース）：https://github.com/spring-attic/spring-retry
• Resilience4j v2.4.0 ソース（RetryConfig・CircuitBreakerConfig・IntervalFunction・resilience4j-spring-boot4）：https://github.com/resilience4j/resilience4j/tree/v2.4.0
• Resilience4j Documentation「Getting Started with Spring Boot」：https://resilience4j.readme.io/docs/getting-started-3

株式会社RJC ― SI事業・SES事業・AI駆動開発。RJCは一緒に成長を楽しめる会社です。