【ITニュース解説】Mastering RestTemplate in Spring Boot

Spring Bootでアプリケーションを開発していると、多くの場合、自身のアプリケーションが他のWebサービスやマイクロサービスと情報をやり取りする必要が出てくる。たとえば、顧客情報を提供するサービスと、その顧客に紐づく口座情報を提供するサービスがある場合、口座情報サービスが顧客情報を取得するために顧客情報サービスに問い合わせる必要がある。このような、サービス間でのHTTP通信を行うためのツールとして、Spring Frameworkが提供しているのがRestTemplateである。

RestTemplateは、外部のRESTful Webサービスに対してHTTPリクエストを送信するための「同期型クライアント」だ。同期型とは、リクエストを送信したら、そのレスポンスが完全に返ってくるまで、アプリケーションのその部分の処理が一時停止するという意味だ。これは、伝統的で理解しやすい通信モデルであり、WebClientが登場するまで、多くの既存のSpring Bootアプリケーションでサービス間の連携に広く使われてきた。RestTemplateは内部的にJava標準のjava.net.HttpURLConnectionを利用してHTTP通信を行っているが、その複雑な部分を隠蔽し、開発者がシンプルにHTTPリクエストを扱えるように設計されている。これにより、外部サービスとの連携が非常に便利で柔軟に行えるようになる。

RestTemplateには、外部サービスとの連携を容易にするいくつかの重要な特徴がある。まず、先ほど説明したように「同期的なHTTP呼び出し」を行うため、リクエストを投げたら応答が来るまで待つ、という素直な動作をする。次に、GET、POST、PUT、PATCH、DELETE、OPTIONSといった、RESTful APIで利用される主要なHTTPメソッドをすべてサポートしている。これにより、データの取得、新規作成、更新、削除といった一連のCRUD操作を簡単に実装できる。

また、RestTemplateは「柔軟なレスポンス処理」を提供する。たとえば、レスポンスの本体だけをJavaオブジェクトとして取得するgetForObject()のようなメソッドがある。また、HTTPステータスコードやHTTPヘッダーを含む完全なレスポンス情報をResponseEntityとして取得するgetForEntity()のようなメソッドもある。さらに、exchange()メソッドを使うことで、リクエストメソッド、ヘッダー、ボディ、レスポンスの型をより細かく制御できる。URIテンプレートのサポートも特徴の一つで、URLの中に{id}のようなプレースホルダーを設け、実行時に動的な値を埋め込むことができる。リクエストボディの扱いも簡単で、JavaオブジェクトをJSONやXML形式に変換して送信し、受け取ったレスポンスも自動的にJavaオブジェクトにマッピングできる。認証トークンや追跡IDなどの追加情報を送りたい場合は、HttpHeadersとHttpEntityを使って「カスタムヘッダー」を追加することも可能である。

HTTP通信ではエラーがつきものだが、RestTemplateは「例外処理」の仕組みも備えている。たとえば、4xx（クライアントエラー）や5xx（サーバーエラー）のようなHTTPエラーが発生した場合、特定の例外をスローするので、開発者はこれらの例外を捕捉して適切にエラーハンドリングを行うことができる。さらに高度な使い方として、「インターセプター」や「リクエストファクトリ」を使うことも可能だ。インターセプターを使えば、全てのリクエストに対して共通の処理（ログ出力や認証トークンの追加など）を差し込むことができる。リクエストファクトリを交換することで、RestTemplateの基盤となるHTTPクライアントをカスタマイズし、タイムアウト設定やコネクションプーリングといった詳細な挙動を制御できる。

Spring BootアプリケーションでRestTemplateを使うには、まずプロジェクトに適切な依存関係を追加する必要がある。もしspring-boot-starter-webという依存関係をすでに使用していれば、RestTemplateはその中に含まれているため、追加で何かをする必要はない。もし含まれていない場合は、プロジェクトのpom.xmlファイルにspring-boot-starter-webの依存関係を追加するだけでよい。

次に、RestTemplateのインスタンスをSpringが管理するコンポーネント、つまり「Bean」として定義する必要がある。これには、@Configurationアノテーションが付いたクラスを作成し、その中に@Beanアノテーションを付加したメソッドでnew RestTemplate()を返すように記述する。こうすることで、Springアプリケーションが起動する際にRestTemplateのインスタンスが作成され、Springのコンテキスト内で利用できるようになる。

最後に、作成したRestTemplateのBeanを、実際にHTTP通信を行いたいサービスやコントローラーなどのクラスに「注入（インジェクション）」して使用する。これは、クラスのコンストラクタにRestTemplateを引数として受け取るように記述することで実現できる。Springの依存性注入の仕組みによって、必要な場所に自動的にRestTemplateのインスタンスが提供される。

ここからは、実際のHTTP通信でよく使われるRestTemplateのメソッドを具体例とともに見ていく。

データの取得を行う「GET操作」では主に二つのメソッドがある。getForObject()は、指定したURLからリソースを取得し、そのレスポンスボディだけを直接Javaオブジェクトにマッピングして返すメソッドだ。非常にシンプルで、レスポンスボディの内容だけが必要な場合に便利である。例えば、http://localhost:8081/customers/{id}というURLから特定の顧客情報を取得する際、restTemplate.getForObject(URL + "/{id}", CustomerDto.class, customerId)のように使うことで、customerIdに対応する顧客情報をCustomerDtoオブジェクトとして直接受け取れる。一方、getForEntity()は、レスポンスボディだけでなく、HTTPステータスコードやHTTPヘッダーといった詳細な情報もResponseEntityというオブジェクトにラップして返す。これは、通信が成功したかどうかのステータスコードを確認したり、レスポンスヘッダーに含まれる情報を利用したい場合に役立つ。最も柔軟なメソッドはexchange()で、これはGETだけでなく、あらゆるHTTPメソッドで使用でき、リクエストヘッダーやリクエストボディ、レスポンスの型などを完全に制御できる。

新しいデータを作成する「POST操作」では主に二つのメソッドが使われる。postForObject()は、指定したURLにリクエストボディとしてJavaオブジェクトを送信し、作成されたリソースのレスポンスボディをJavaオブジェクトとして返す。postForEntity()も同様にリクエストボディを送信するが、こちらはResponseEntityとして、作成後のリソースのレスポンスボディ、HTTPステータス、ヘッダーをすべて返す。

既存のデータを更新する「PUT操作」では、put()メソッドを使用する。このメソッドは、指定したURLにリクエストボディとして更新したいJavaオブジェクトを送信する。通常、更新が成功した場合は特にレスポンスボディを返さないことが多い。

データを削除する「DELETE操作」では、delete()メソッドを使用する。指定したURLにDELETEリクエストを送信し、特定のIDのリソースを削除する。これも通常、削除が成功した場合は特にレスポンスボディを返さない。

外部のWebサービスと通信する際、常に通信が成功するとは限らないため、例外処理は非常に重要である。ネットワークの問題、外部サービスが停止している、あるいはリクエストの内容が不正である、といった様々な理由でエラーが発生することがある。これらのエラーを適切に処理しないと、アプリケーションが予期せぬ停止をしたり、ユーザーに不適切なメッセージを表示したりする可能性があるためだ。

RestTemplateがスローする主な例外には、HTTPステータスコードが4xxのクライアントエラーを表すHttpClientErrorException、HTTPステータスコードが5xxのサーバーエラーを表すHttpServerErrorException、そしてネットワーク関連のエラーを表すResourceAccessExceptionがある。これらの例外を処理する方法は大きく二つある。一つは「ローカルな例外処理」で、RestTemplateの呼び出しを行うサービスメソッド内で直接try-catchブロックを使って例外を捕捉し、処理する方法だ。この方法は、特定のメソッドだけで特別なエラーハンドリングを行いたい場合に適している。

もう一つは「グローバルな例外処理」で、@ControllerAdviceと@ExceptionHandlerアノテーションを組み合わせることで、アプリケーション全体で発生する例外を一元的に処理する方法である。@ControllerAdviceが付与されたクラス内に、各例外タイプに対応する@ExceptionHandlerメソッドを定義することで、Springは例外が発生した際に自動的に適切なハンドラーを呼び出す。これにより、各サービスメソッドにtry-catchブロックを繰り返し書く手間が省け、エラー処理のロジックを集中管理できるようになる。

重要な点として、RestTemplateは現在、Springチームによって「非推奨（deprecated）」とされており、活発な機能開発は終了している。Springが推奨する代替手段は「WebClient」である。WebClientは、非ブロッキングかつリアクティブなHTTP通信を可能にし、よりスケーラブルで高パフォーマンスなアプリケーションの構築に適している。しかし、RestTemplateが非推奨であるにもかかわらず、多くの既存のプロダクション環境では今もRestTemplateが広く使われている。そのため、既存のアプリケーションの保守や、WebClientへの移行がまだ進んでいないプロジェクトに携わる場合、RestTemplateに関する知識は依然として非常に重要だ。現在Spring Boot開発者を目指す初心者にとっては、過去の遺産を理解するためにも、そしてWebClientへのスムーズな移行を理解するためにも、RestTemplateの基礎を学ぶことは決して無駄ではない。

これまで、Spring BootにおけるRestTemplateの基本的な概念から、その特徴、設定方法、具体的なCRUD操作の実装例、そして例外処理の仕方までを詳しく解説した。RestTemplateは、サービス間通信が頻繁に発生するマイクロサービスアーキテクチャにおいて、Spring Bootアプリケーションが外部のRESTfulサービスと連携するための強力なツールとして長らく利用されてきた。同期的な処理モデルで理解しやすく、多様なHTTPメソッドや柔軟なレスポンス処理、カスタムヘッダーの追加、例外処理といった機能を備えている。現在ではWebClientが推奨されるようになったが、既存の多くのプロジェクトで活躍しているため、システムエンジニアを目指す上ではぜひ理解しておくべき技術の一つである。