はじめに
外部APIを呼び出すとき、RestClientを既定値のまま使っていませんか。普段は問題なく動いていても、相手のAPIが遅くなったり、アクセスが増えたりしたときに、アプリ全体が詰まる原因になります。
この記事では、Spring Boot 4でHTTPクライアントのタイムアウトとコネクションプールを設定する方法を整理します。
- 対象読者:Spring MVCのアプリから、RestClientやHTTP Service Clientで外部APIを呼んでいる方
- 前提バージョン:Spring Boot 4.0 / Java 25
- この記事で分かること:どの通信ライブラリが使われるか、タイムアウトの設定、コネクションプールの設定と大きさの決め方
結論
- タイムアウトは、
spring.http.clients.*のプロパティで全体に、spring.http.serviceclient.<グループ>.*で接続先ごとに設定できる - コネクションプールは、通信ライブラリごとにコードで設定する。Apache HttpClient 5の既定値は「全体25、接続先ごとに5」と小さい
- 使われていない接続は、ロードバランサーのアイドルタイムアウトより短い間隔で、こちらから閉じておく
仕組みの全体像
RestClientは、自分では通信をしません。実際の通信は、裏側の通信ライブラリが行います。
- RestClient / WebClient:Springの部品(使う側のAPI)
- 通信ライブラリ:Apache HttpClient、Jetty、Reactor Netty、JDKのHttpClientなど
タイムアウトはSpring Bootのプロパティで共通に設定できますが、コネクションプールの設定は通信ライブラリごとに違うので、コードで設定します。
どの通信ライブラリが使われるか
Spring Bootは、クラスパスにあるライブラリから、次の優先順位で自動的に選びます。
| 順位 | RestClient | WebClient |
|---|---|---|
| 1 | Apache HttpClient | Reactor Netty |
| 2 | Jetty HttpClient | Jetty |
| 3 | Reactor Netty | Apache HttpClient |
| 4 | JDKのHttpClient | JDKのHttpClient |
| 5 | HttpURLConnection | なし |
RestClientを使うなら、Apache HttpClient 5を明示的に追加するのがおすすめです。何も追加しないとJDKのHttpClientが使われますが、こちらはプールの上限などを細かく設定できません。
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-restclient'
implementation 'org.apache.httpcomponents.client5:httpclient5' // バージョンはBOMで管理される
}
タイムアウト
3種類のタイムアウト
| 種類 | 意味 | 設定しないと |
|---|---|---|
| 接続タイムアウト | TCP接続ができるまでの待ち時間 | 相手のサーバーが落ちているとき長く待つ |
| 読み取りタイムアウト | 応答のデータが届くまでの待ち時間 | 相手の処理が詰まると、こちらも止まり続ける |
| プールからの取得待ち | 空いている接続を待つ時間 | 接続を使い切ると、リクエストが行列になる |
プロパティで設定する
spring:
http:
clients: # すべてのHTTPクライアントに共通
connect-timeout: 3s
read-timeout: 5s
serviceclient:
payment: # HTTP Service Clientのグループごとに上書き
base-url: https://api.payment.example.com
read-timeout: 10s # 処理が重いAPIだけ長めにする
値の決め方の目安
- 接続タイムアウトは短め(1〜3秒)にする。接続できない相手は、待っても接続できないことが多い
- 読み取りタイムアウトは、相手のAPIの応答時間に余裕を持たせた値にする
- 外部APIの待ち時間とリトライの合計は、呼び出し元(ALBなど)のタイムアウトより短くする
コネクションプール(Apache HttpClient 5)
既定値に注意
Apache HttpClient 5のコネクションプールの既定値は、次のとおりです。
- 全体の上限(maxConnTotal):25
- 接続先ごとの上限(maxConnPerRoute):5
接続先ごとの上限が5なので、同じ外部APIに同時に6件以上のリクエストを送ると、6件目以降は空きを待つことになります。負荷が上がった途端に遅くなる、典型的な原因です。
設定のしかた
プールの大きさを設定するプロパティはないので、Customizerで設定します。Customizerを使うと、Spring Bootの自動設定を残したまま、一部だけを変えられます。プロパティで設定したタイムアウトもそのまま効きます。
@Configuration(proxyBeanMethods = false)
public class HttpClientPoolConfig {
@Bean
ClientHttpRequestFactoryBuilderCustomizer<HttpComponentsClientHttpRequestFactoryBuilder> poolCustomizer() {
return builder -> builder
// プールの大きさ
.withConnectionManagerCustomizer(pool -> pool
.setMaxConnTotal(200)
.setMaxConnPerRoute(50))
// 接続ごとの設定
.withConnectionConfigCustomizer(conn -> conn
.setTimeToLive(TimeValue.ofMinutes(5)) // 接続の寿命
.setValidateAfterInactivity(TimeValue.ofSeconds(10))) // しばらく使っていない接続は使う前に確認
// 使っていない接続を定期的に閉じる
.withHttpClientCustomizer(client -> client
.evictIdleConnections(TimeValue.ofSeconds(30)));
}
}
数値は例です。実際の値は、次の「プールの大きさの決め方」を参考に決めてください。
アイドル接続を閉じる理由
AWSのALBやNATゲートウェイは、一定時間使われていない接続を、通知せずに切ります(ALBの既定は60秒)。プールに残った「すでに切られた接続」を使うと、Connection reset や NoHttpResponseException が発生します。
相手側が切るより短い間隔で、こちらから閉じておくのが対策です。上の例の evictIdleConnections と setTimeToLive がその設定です。
WebClientの場合(Reactor Netty)
WebClientは、既定ではReactor Nettyで通信します。細かく制御したいときは、プール(ConnectionProvider)を自分で作ります。
@Bean(destroyMethod = "dispose")
ConnectionProvider paymentConnectionProvider() {
return ConnectionProvider.builder("payment-pool")
.maxConnections(100) // 同時接続数の上限
.pendingAcquireTimeout(Duration.ofSeconds(2)) // 空きを待つ最大時間
.maxIdleTime(Duration.ofSeconds(30)) // 使っていない接続を閉じるまでの時間
.maxLifeTime(Duration.ofMinutes(5)) // 接続の寿命
.evictInBackground(Duration.ofSeconds(30)) // 定期的に古い接続を掃除する
.build();
}
空きを待つ時間(pendingAcquireTimeout)は短めにするのが大切です。長いままだと、プールを使い切ったときにリクエストがたまり続け、障害が広がります。早めにエラーにして、リトライや呼び出し元のエラー処理に任せるほうが安全です。
プールの大きさの決め方
必要な接続数の目安は、次の式で求められます。
必要な接続数 ≒ 1秒あたりのリクエスト数 × 1件の応答時間(秒)
例:50件/秒 × 0.2秒 = 10接続 → 余裕を見て20〜30
仮想スレッドを使う場合
仮想スレッドを有効にすると、スレッド数の上限が事実上なくなります。以前は「Tomcatのスレッド数(既定200)」が自然な歯止めになっていましたが、仮想スレッドではHTTPクライアントのプールが実質的な上限になります。
- プールが小さすぎる:空き待ちの行列ができて遅くなる
- プールが大きすぎる:外部APIに一度に大量のリクエストが届き、相手を落とすことがある
相手側に同時実行数の制限があるなら、Spring Framework 7の @ConcurrencyLimit で呼び出し数を絞るのも有効です(設定クラスに @EnableResilientMethods を付けると有効になります)。
@ConcurrencyLimit(20) // 同時に20件まで
public PaymentResult pay(PaymentRequest request) {
return paymentClient.pay(request);
}
トランザクションの外で呼ぶ
@Transactional のメソッドの中で外部APIを呼ぶと、その間DBの接続も握ったままになります。外部APIが遅くなると、DBのコネクションプールまで使い切ってしまうので、外部APIの呼び出しはトランザクションの外で行うのが原則です。
まとめ
- RestClientでは、Apache HttpClient 5を明示的に追加して使う
- タイムアウトは
spring.http.clients.*で全体に、spring.http.serviceclient.<グループ>.*で接続先ごとに設定する - Apache HttpClient 5のプールは「全体25、接続先ごとに5」なので、必ず広げる
- 使われていない接続は、ALBなどのアイドルタイムアウトより短い間隔で閉じる
- 仮想スレッドではプールが実質的な上限になる。必要なら
@ConcurrencyLimitも使う - 外部APIの呼び出しはトランザクションの外で行う
関連記事
タイムアウトとプールは、問題が起きるまで意識しにくい設定です。外部APIを呼んでいるアプリでは、一度見直してみてください。