🕌

来年の新卒に読んでほしいSpring Framework WebClientのコツ4選

に公開

この記事は Money Forward Kansai Advent Calendar 2025 20日目の記事になります。

はじめに

こんにちは。マネーフォワード大阪開発拠点にてバックエンドエンジニアをしている yuta.yamamoto です。
普段はKotlinを用いてバックエンド開発をしています。

この記事では、新卒の僕がKotlinで WebClient を触っていて、「へー、なるほど!」となったことを4つ挙げてみました。

もしかしたら他の言語のHTTPクライアント実装でも本記事の内容は当たり前かもしれませんが、最近はAIにコードを書かせることが増え、細かい仕様を見落としがちです。普段バックエンドエンジニアではない人や、Spring WebClient初心者の方の参考になれば幸いです。

なお、本記事で扱うWebClientは Spring Framework の org.springframework.web.reactive.function.client.WebClient になります。

WebClientはSpring WebFluxにおけるHTTPリクエストを実行するクライアントです。Spring Web MVCではRESTクライアントやRestTemplateといったものがあります。

Spring FrameworkのWebClientについて

WebClient - Spring Framework Documentation

チームではKotlinを使用しているため、この記事でのコード例は全てKotlinです。

val client = WebClient.create("https://example.org")

val result = client.get()
    .uri("/persons/{id}", id)
    .accept(MediaType.APPLICATION_JSON)
    .retrieve()
    .awaitBody<Person>()

WebClientはこのようにFluent APIで書くことができます。基本的な使い方は公式ドキュメントに譲るとして、早速ランキング形式で第4位から参りましょう。


第4位 WebClientのデフォルトのBuffer Limitは256KBである

みなさん、以下のエラーを見たことはありますか?

Exceeded limit on max bytes to buffer : 262144

リクエストのレスポンスサイズがデフォルトの上限を超えると、このエラーが発生します。

application.yaml で以下のように書くと一括で設定することも可能ですが、個別にも設定できます。

(Spring3.5から新しい書き方に変更になっています。)

  http:
    codecs:
      max-in-memory-size: 10MB

個別に大きめのレスポンス(CSVダウンロードや大きなJSONリストなど)が想定される場合は、WebClient作成時に設定しておく必要があります。

対策コード:

val webClient = WebClient.builder()
    .codecs { configurer -> 
        // 2MBに拡張する例
        configurer.defaultCodecs().maxInMemorySize(2 * 1024 * 1024) 
    }
    .build()

これを知らずに本番環境で大きなデータを扱った際にエラーを起こしてしまった……なんてことにならないよう、サイズ見積もりは重要です。


第3位 ConnectionProviderを設定しよう

WebClientを作る際、内部で使用する HttpClient の設定も重要です。
特に、コネクションプールの上限や待機時間などの設定は、HttpClient 単体ではなく ConnectionProvider を経由して設定する必要があります。

デフォルト設定のままだと、高負荷時にコネクションが足りなくなったり、予期せぬタイムアウトが発生したりすることがあります。

推奨する設定パターン:

// 1. ConnectionProviderで接続数や生存時間を管理
val provider = ConnectionProvider.builder("custom-provider")
    .maxConnections(500)       // 最大接続数
    .pendingAcquireMaxCount(1000) // プール枯渇時の待機キュー上限
    .maxIdleTime(Duration.ofSeconds(3)) // アイドル状態の維持時間
    .build()

// 2. HttpClientにProviderをセット
val httpClient = HttpClient.create(provider)
    .secure { spec -> spec.sslContext(...) } // 必要に応じてSSL設定など

// 3. WebClientにConnectorとして渡す
val webClient = WebClient.builder()
    .clientConnector(ReactorClientHttpConnector(httpClient))
    .build()

HttpClient にオリジナルの設定を入れる場合は、このように ConnectionProvider から組み立てていくのがベストプラクティスです。


第2位 WebClientをカスタマイズしたいときは ExchangeFilterFunction を活用しよう

これを知ったときは結構衝撃でした。
「全てのGETリクエストにリトライ処理を入れたい」「特定のエラー時にログを出したい」といった要件が出たとき、みなさんはどうされますか?

WebClientを継承して独自のラッパークラスを作る……ということができる人はできると思いますが、僕はできないので、ExchangeFilterFunction を使用すれば、その悩みはスマートに解決します。

例えば、GETリクエストだけリトライ処理を入れたい場合、WebClient作成時にフィルターとして挟み込むことができます。

フィルターの実装例:

val retryFilter = ExchangeFilterFunction { request, next ->
    next.exchange(request) // 次の処理(リクエスト送信)を実行
        .flatMap { response ->
            if (request.method() == HttpMethod.GET && response.statusCode().is5xxServerError) {
                // GETかつ500系エラーならリトライなどの処理
                // ※実際には .retryWhen() などを使用します
            }
            Mono.just(response)
        }
}

val webClient = WebClient.builder()
    .filter(retryFilter) // ここでフィルターを適用
    .build()

この方法なら、全てのWebClientインスタンスに共通の振る舞い(リトライ、認証ヘッダーの付与、ログ出力など)を簡単に適用できます。「継承より委譲(構成)」する感じですかね。


第1位 WebClientでUriをBuildするときはエンコードに気をつけよう

堂々の第1位です。なんならこれを言いたいためにこの記事を書きました。
正直、これを知らなくて多くの時間を要しました。

特に クエリパラメータに + (プラス記号) が含まれる場合 に発生する問題です。

失敗するパターンとデバッグ

例えば、Mockサーバーに対して param=value+value というクエリを送りたいとします。
最初は単純に以下のように書いていました。

// ダメな例:文字列結合や単純なqueryParamでの指定
val response = webClient.get()
    .uri { uriBuilder ->
        uriBuilder.path("/example")
            .queryParam("param", "value+value") // ← ここで事故が起きる
            .build()
    }
    .retrieve()
    .bodyToMono(Map::class.java)
    .block()

しかし、これだと期待したレスポンスが返ってきません。
そこで、MockServerの機能を使って実際に届いたリクエストの内容をログに出力してみました。

// MockServerに届いたリクエストを確認するデバッグコード
val recordedRequests = mockServer.retrieveRecordedRequests(null)
recordedRequests.forEach { request ->
    println(" ===== Recorded Request ===== ")
    println("path: ${request.path}")
    println("query parameters: ${request.queryStringParameters}")
    println(" ==============================")
}

実行結果のログ:

 ===== Recorded Request ===== 
path: /example
query parameters: {
  "param" : [ "value value" ]
}
 ==============================

ご覧ください。value+value を送ったつもりが、+ が消えて(スペースに変換されて) value value になっています。
これは UriComponentsBuilder のエンコード仕様によるもので、意図せずデコードされてしまうケースがあるためです。

成功するパターン

結論、URIテンプレート変数({})を使用し、build(map) で値を渡す のが最も安全で確実です。

// 良い例:テンプレート変数を使って値を埋め込む
val response = webClient.get()
    .uri { uriBuilder ->
        uriBuilder.path("/example")
            .queryParam("param", "{value}") // プレースホルダーを置く
            .build(mapOf("value" to "value+value")) // Mapで値を渡して展開・エンコードさせる
    }
    .retrieve()
    .bodyToMono(Map::class.java)
    .block()

これを実行して再度ログを確認すると、ちゃんと + が届いていることが確認できました。

 ===== Recorded Request ===== 
path: /example
query parameters: {
  "param" : [ "value+value" ]
}
 ==============================

ログを見て「あれ、プラス記号が消えてる……?」となったときは、ぜひこの書き方を思い出してください。


まとめ

本記事では、Spring Framework WebClientを使用する際に知っておくべき4つの重要なポイントを紹介しました。

  • 第4位: デフォルトのBufferサイズに注意
    • デフォルトは256KBです。大きなレスポンスを扱う場合は maxInMemorySize を設定しましょう。
  • 第3位: ConnectionProviderを設定しよう
    • パフォーマンスやタイムアウト制御のために、HttpClientだけでなくConnectionProviderの設定も重要です。
  • 第2位: ExchangeFilterFunctionでカスタマイズ
    • 継承ではなくFilterを使うことで、リトライやログ出力などの共通処理をきれいに実装できます。
  • 第1位: URIエンコードに注意
    • + などの特殊文字は、単純な指定ではなく .build(mapOf(...)) 形式のテンプレート変数を使うことで正しく処理されます。

特に第1位のエンコード問題は、知らないと多くの時間を無駄にしてしまう可能性があるため、WebClientを使用する際は必ず意識しておきましょう。これらのコツを活用することで、より安全で効率的なバックエンド開発が可能になります。

次回の Money Forward Kansai Advent Calendar もお楽しみに!

Money Forward Developers

Discussion