【Spring MVC】RestTemplateを使ったAPIアクセス（exchangeによる汎用的な通信方法）

概要

RestTemplate#exchangeを使った汎用的な使い方についてまとめた。
動作確認を行うための事前準備については、以下に記載している。

あわせて読みたい

【Spring MVC】RestTemplateの導入

概要 RESTfulなAPIを呼ぶクライアントライブラリである、RestTemplateの概要についてまとめた。 RestTemplateを使用するための準備と、どんなメソッドがあるのかを紹介している。   前提 今[…]

汎用的な通信方法

各APIを呼び出す際に、統一された形式で呼び出させるようにした。
また、RequestEntityの設定を隠蔽して統一されたヘッダー情報で送信できるようにした。
汎用的なメソッドを作成することで、API仕様変更の影響も最小限に抑えられる。

実装方法

取得したいレスポンスの型が「Class<T>」と「ParameterizedTypeReference<T>」の2つのケースが存在するため、オーバーロードして使用する。
※シンプルなレスポンスを取得したい場合は「Class<T>」を、リストなどのジェネリクスを使用したレスポンスを取得したい場合は「ParameterizedTypeReference<T>」を使用する

RestClient.java

package com.example.client_prototype.biz;

import java.net.URI;
import java.util.Collections;
import java.util.Map;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.HttpMethod;
import org.springframework.http.MediaType;
import org.springframework.http.RequestEntity;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Component;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.util.UriComponentsBuilder;

@Component
public class RestClient {

	@Autowired
	private RestTemplate restTemplate;
	
	private static final String BASE_URL = "http://localhost:8080/rest_prototype/"; // 本来はプロパティなどから取得

	/**
	 * 汎用的なメソッド
	 * @param <T>
	 * @param url URL文字列
	 * @param method HTTPメソッド
	 * @param body リクエストボディ
	 * @param responseType レスポンスの型
	 * @param queryParams クエリパラメータ
	 * @param pathParams パスパラメータ
	 * @return
	 */
	public <T> ResponseEntity<T> exchange(String url, HttpMethod method, Object body, Class<T> responseType,
			Map<String, Object> queryParams, Map<String, Object> pathParams) {

		UriComponentsBuilder builder = UriComponentsBuilder.fromUriString(BASE_URL + url);

		// クエリパラメータ設定
		if (queryParams != null) {
			for (Map.Entry<String, Object> entry : queryParams.entrySet()) {
				builder.queryParam(entry.getKey(), entry.getValue());
			}
		}

		// 最終的にURIを生成
		URI uri = builder.buildAndExpand(pathParams != null ? pathParams : Collections.emptyMap()) // パスパラメータ設定
				.encode() // URIエンコード
				.toUri();

		// RequestEntity生成
		RequestEntity<Object> requestEntity = RequestEntity
				.method(method, uri)
				.contentType(MediaType.APPLICATION_JSON)
				.body(body);

		// exchangeメソッドでリクエストを送信し、ResponseEntityを返却
		return restTemplate.exchange(requestEntity, responseType);
	}

	/**
	 * 汎用的なメソッド
	 * @param <T>
	 * @param url URL文字列
	 * @param method HTTPメソッド
	 * @param body リクエストボディ
	 * @param responseType レスポンスの型
	 * @param queryParams クエリパラメータ
	 * @param pathParams パスパラメータ
	 * @return
	 */
	public <T> ResponseEntity<T> exchange(String url, HttpMethod method, Object body, ParameterizedTypeReference<T> responseType,
			Map<String, Object> queryParams, Map<String, Object> pathParams) {

		UriComponentsBuilder builder = UriComponentsBuilder.fromUriString(BASE_URL + url);

		// クエリパラメータ設定
		if (queryParams != null) {
			for (Map.Entry<String, Object> entry : queryParams.entrySet()) {
				builder.queryParam(entry.getKey(), entry.getValue());
			}
		}

		// 最終的にURIを生成
		URI uri = builder.buildAndExpand(pathParams != null ? pathParams : Collections.emptyMap()) // パスパラメータ設定
				.encode() // URIエンコード
				.toUri();

		// RequestEntity生成
		RequestEntity<Object> requestEntity = RequestEntity
				.method(method, uri)
				.contentType(MediaType.APPLICATION_JSON)
				.body(body);

		// exchangeメソッドでリクエストを送信し、ResponseEntityを返却
		return restTemplate.exchange(requestEntity, responseType);
	}
}

ドメイン部分とエンドポイントを結合して、UriComponentsBuilderを生成している。
UriComponentsBuilderを使用することで、柔軟にURIを作成することができる。

クエリパラメータのマップが存在する場合、UriComponentsBuilderを使用してエンドポイント以降にクエリパラメータを動的に作成する。

パスパラメータのマップが存在する場合、URL文字列のプレースホルダーにバインドさせる。

URIエンコードを行って、URIオブジェクトを生成している。
ここまでで、「URL文字列」と「クエリパラメータマップ」と「パスパラメータマップ」を受け取って動的にURIを生成する。

API通信時の共通したRequestEntityを生成している。
必要に応じて、ここでヘッダー等に必要な値を設定する。

作成したRequestEntityと取得したいレスポンスの型を指定してexchangeを呼び出す。
戻り値はResponseEntityとなる。

使用例

すべてのHTTPメソッドを扱えるが、ここではPOSTとGETを使用した例を紹介する。

POST

リクエストボディを用意して、POST通信を行う。

動作確認用クラス

// リクエストボディ
var req = new Resource("4", "ごま", LocalDate.of(2099, 5, 1));
// API疎通
ResponseEntity<Void> res = restClient.exchange(
		"rest02/create", 
		HttpMethod.POST, 
		req,
		Void.class, 
		null, 
		null);

// 動作確認
System.out.println(res.getStatusCode());
System.out.println(res.getHeaders());
System.out.println(res.getBody());

コンソール

201 CREATED
[Location:"http://localhost:8080/rest_prototype/rest01/4", Content-Length:"0", Date:"Tue, 01 Apr 2025 00:10:47 GMT", Keep-Alive:"timeout=20", Connection:"keep-alive"]
null

GET

必要に応じてクエリパラメータ、パスパラメータを設定してGET通信を行う。

クエリパラメータ

クエリパラメータを作成して送信する。

動作確認用クラス

// クエリパラメータ
Map<String, Object> queryParams = Map.of("name", "ご");
// API疎通
ResponseEntity<List<Resource>> res = restClient.exchange(
		"rest05/", 
		HttpMethod.GET, 
		null,
		new ParameterizedTypeReference<List<Resource>>() {}, 
		queryParams, 
		null);

// 動作確認
System.out.println(res.getStatusCode());
System.out.println(res.getHeaders());
System.out.println(res.getBody());

コンソール

200 OK
[Content-Type:"application/json;charset=UTF-8", Transfer-Encoding:"chunked", Date:"Tue, 01 Apr 2025 00:14:52 GMT", Keep-Alive:"timeout=20", Connection:"keep-alive"]
[Resource(id=1, name=りんご, hogeDate=2025-02-01), Resource(id=2, name=ごりら, hogeDate=2024-06-05), Resource(id=4, name=ごま, hogeDate=2099-05-01)]

パスパラメータ

パスパラメータを作成して送信する。

動作確認用クラス

// パスパラメータ
Map<String, Object> pathParams = Map.of("id", "4");
// API疎通
ResponseEntity<Resource> res = restClient.exchange(
		"rest01/{id}",
		HttpMethod.GET,
		null,
		Resource.class,
		null,
		pathParams);
		
// 動作確認
System.out.println(res.getStatusCode());
System.out.println(res.getHeaders());
System.out.println(res.getBody());

コンソール

200 OK
[Content-Type:"application/json;charset=UTF-8", Transfer-Encoding:"chunked", Date:"Tue, 01 Apr 2025 00:16:40 GMT", Keep-Alive:"timeout=20", Connection:"keep-alive"]
Resource(id=4, name=ごま, hogeDate=2099-05-01)

まとめ