For AI agents: the complete documentation index is available at /Practical-Introduction-to-Spring-Boot/llms.txt, the full documentation bundle is available at /Practical-Introduction-to-Spring-Boot/llms-full.txt, and this page is available as Markdown at /Practical-Introduction-to-Spring-Boot/SpringBoot入門/外部API連携入門.md.

Spring Boot 外部 API 連携入門 — RestClient とタイムアウト

講義の区切り

基本編の目安は 60〜90 分です。終了条件は、配送 API に GET を送り、取得した送料を返すことです。 さらに、配送 API が返した HTTP エラーと、応答を待ち切れなかった場合を区別して確認します。

概要

利用者から地域コードを受け取り、別の HTTP サーバーに送料を問い合わせる API を作ります。 Spring MVC の Controller がリクエストを受け、配送 API への問い合わせには RestClient を使います。

配送 API は手元で起動します。地域コードによって、正常応答・エラー・遅延を切り替えられます。

事前準備

  • JDK 21
  • Controller を使った GET エンドポイントの作成経験
  • 空きポート 8080(送料照会アプリ)、8089(模擬配送 API)

Spring Initializr で新しいプロジェクトを作成します。 Maven / Java / Jar / YAML を選び、Spring Boot は 4.0 系(動作確認は 4.0.4)、Java は 21 にします。 Group は dev.mikoto2000.springboot、Artifact は shipping、Package name は dev.mikoto2000.springboot.shipping です。 依存関係に Spring Web を選びます。生成した pom.xml に spring-boot-starter-webmvc があることを確認し、dependencies に次の依存関係を追加してください。

RestClient の依存関係
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-restclient</artifactId>
</dependency>

触って学ぶ外部 API 連携

模擬配送 API を起動する

配送 API の GET /rates/{area} は、地域コードに応じて次の応答を返します。

地域コード配送 API の動作
tokyoすぐに 200 を返す
unknown対象地域が見つからず、404 を返す
maintenance配送 API の内部エラーとして、500 を返す
slow3 秒待ってから、200 を返す

演習プロジェクトのルート(pom.xml と同じ場所)に MockShippingApi.java を作ります。 JDK に付属する HTTP サーバーを使うため、このファイルは java コマンドで直接実行できます。

MockShippingApi.java
import com.sun.net.httpserver.HttpExchange;
import com.sun.net.httpserver.HttpServer;
import java.io.IOException;
import java.net.InetSocketAddress;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.Executors;

class MockShippingApi {

  public static void main(String[] args) throws IOException {
    HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", 8089), 0);
    server.setExecutor(Executors.newVirtualThreadPerTaskExecutor());
    server.createContext("/rates/", MockShippingApi::handleRate);
    server.start();
    System.out.println("Mock shipping API listening on http://127.0.0.1:8089");
  }

  private static void handleRate(HttpExchange exchange) throws IOException {
    try (exchange) {
      String path = exchange.getRequestURI().getPath();
      System.out.println(exchange.getRequestMethod() + " " + path);
      if (!"GET".equals(exchange.getRequestMethod())) {
        exchange.getResponseHeaders().set("Allow", "GET");
        sendJson(exchange, 405, """
            {"error":"method not allowed"}
            """);
        return;
      }

      switch (path) {
        case "/rates/tokyo" -> sendJson(exchange, 200, """
            {"area":"tokyo","feeYen":600}
            """);
        case "/rates/maintenance" -> sendJson(exchange, 500, """
            {"error":"shipping service error"}
            """);
        case "/rates/slow" -> {
          try {
            Thread.sleep(3000);
          } catch (InterruptedException exception) {
            Thread.currentThread().interrupt();
            return;
          }
          sendJson(exchange, 200, """
              {"area":"slow","feeYen":800}
              """);
        }
        default -> sendJson(exchange, 404, """
            {"error":"unknown area"}
            """);
      }
    }
  }

  private static void sendJson(HttpExchange exchange, int status, String json) throws IOException {
    byte[] body = json.getBytes(StandardCharsets.UTF_8);
    exchange.getResponseHeaders().set("Content-Type", "application/json");
    exchange.sendResponseHeaders(status, body.length);
    exchange.getResponseBody().write(body);
  }
}

1 つ目のターミナルで起動します。PowerShell でも同じコマンドを使えます。

java MockShippingApi.java

別のターミナルから模擬 API に直接リクエストし、200 と {"area":"tokyo","feeYen":600} が返ることを確認します。 以下の curl は、PowerShell では curl.exe に読み替えてください。

curl -i http://127.0.0.1:8089/rates/tokyo

RestClient で送料を取得する

src/main/resources/application.yaml に、配送 API の接続先とタイムアウトを設定します。 比較のため、初めは模擬 API の遅延 3 秒より長い読み取りタイムアウトを設定します。

application.yaml
spring:
  application:
    name: shipping
  mvc:
    problemdetails:
      enabled: true

shipping:
  base-url: http://127.0.0.1:8089
  connect-timeout: 1s
  read-timeout: 4s

以下の Java ファイルは src/main/java/dev/mikoto2000/springboot/shipping の下に配置します。 まず、配送 API の JSON を受け取る DTO を定義します。この演習では同じ DTO を送料照会 API の応答にも使います。

ShippingQuote.java
package dev.mikoto2000.springboot.shipping;

public record ShippingQuote(String area, int feeYen) {}

次に、配送 API を呼び出すクラスを作ります。 Spring Boot が用意する RestClient.Builder を受け取り、ベース URL と HTTP 通信の設定を指定します。 演習では SimpleClientHttpRequestFactory を使い、接続時と読み取り時のタイムアウトを明示します。

ShippingClient.java
package dev.mikoto2000.springboot.shipping;

import java.net.SocketTimeoutException;
import java.time.Duration;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.stereotype.Component;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.ResourceAccessException;
import org.springframework.web.client.RestClient;
import org.springframework.web.client.RestClientResponseException;
import org.springframework.web.server.ResponseStatusException;

@Component
public class ShippingClient {

  private final RestClient restClient;

  public ShippingClient(
      RestClient.Builder builder,
      @Value("${shipping.base-url}") String baseUrl,
      @Value("${shipping.connect-timeout}") Duration connectTimeout,
      @Value("${shipping.read-timeout}") Duration readTimeout) {
    var factory = new SimpleClientHttpRequestFactory();
    factory.setConnectTimeout(connectTimeout);
    factory.setReadTimeout(readTimeout);
    this.restClient = builder.baseUrl(baseUrl).requestFactory(factory).build();
  }

  public ShippingQuote getQuote(String area) {
    try {
      ShippingQuote quote = restClient.get()
          .uri("/rates/{area}", area)
          .accept(MediaType.APPLICATION_JSON)
          .retrieve()
          .body(ShippingQuote.class);
      if (quote == null) {
        throw new ResponseStatusException(HttpStatus.BAD_GATEWAY, "配送 API の応答本文が空です。");
      }
      return quote;
    } catch (HttpClientErrorException.NotFound exception) {
      throw new ResponseStatusException(HttpStatus.NOT_FOUND, "配送対象の地域が見つかりません。", exception);
    } catch (RestClientResponseException exception) {
      throw new ResponseStatusException(HttpStatus.BAD_GATEWAY, "配送 API がエラーを返しました。", exception);
    } catch (ResourceAccessException exception) {
      if (exception.contains(SocketTimeoutException.class)) {
        throw new ResponseStatusException(HttpStatus.GATEWAY_TIMEOUT, "配送 API の呼び出しがタイムアウトしました。", exception);
      }
      throw new ResponseStatusException(HttpStatus.BAD_GATEWAY, "配送 API と通信できません。", exception);
    }
  }
}

uri("/rates/{area}", area) で URL のパスを組み立てます。retrieve().body(ShippingQuote.class) でレスポンスを読み取り、成功時の JSON を DTO に変換します。 retrieve() のデフォルトの扱いでは、4xx や 5xx の応答を読み取ると、ステータスに応じた例外が発生します。

最後に、利用者からのリクエストを受ける Controller を作ります。

ShippingController.java
package dev.mikoto2000.springboot.shipping;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ShippingController {

  private final ShippingClient shippingClient;

  public ShippingController(ShippingClient shippingClient) {
    this.shippingClient = shippingClient;
  }

  @GetMapping("/shipping-quotes/{area}")
  public ShippingQuote getQuote(@PathVariable("area") String area) {
    return shippingClient.getQuote(area);
  }
}

HTTP 応答を確認する

模擬 API を動かしたまま、別のターミナルで送料照会アプリを起動します。PowerShell では .\mvnw.cmd spring-boot:run を使います。

./mvnw spring-boot:run

さらに別のターミナルから、今度は 8080 番の送料照会アプリにリクエストします。

curl -i http://127.0.0.1:8080/shipping-quotes/tokyo
curl -i http://127.0.0.1:8080/shipping-quotes/unknown
curl -i http://127.0.0.1:8080/shipping-quotes/maintenance
地域コード配送 API の応答送料照会アプリの応答
tokyo200200 と {"area":"tokyo","feeYen":600}
unknown404404 と「配送対象の地域が見つかりません。」
maintenance500502 と「配送 API がエラーを返しました。」

エラー応答では、Content-Type が application/problem+json となり、本文の status と detail で表の内容を確認できます。 模擬 API 側のターミナルには GET /rates/tokyo などが表示されます。受け取った地域コードを使って別の HTTP サーバーを呼び出したことが分かります。

読み取りタイムアウトを短くする

まず、読み取りタイムアウトが 4 秒のまま slow を照会します。 curl の出力末尾に、HTTP ステータスとリクエスト全体の所要時間が表示されます。

curl -sS -w '\nHTTP %{http_code}, %{time_total}s\n' http://127.0.0.1:8080/shipping-quotes/slow

模擬 API の遅延を含め、約 3 秒で 200 が返ります。 送料照会アプリを Ctrl+C で停止し、application.yaml の shipping.read-timeout を 4s から 1s に変更します。 送料照会アプリを再起動し、同じコマンドを実行してください。 今度は約 1 秒で 504 が返り、本文に「配送 API の呼び出しがタイムアウトしました。」と表示されます。時間は環境によって多少前後します。

続けて tokyo を照会し、200 が返ることも確かめます。 発展として、模擬 API を停止してからもう一度 tokyo を照会すると、ローカルでの接続拒否は 502 になります。

後片付け

送料照会アプリと模擬配送 API を、それぞれのターミナルで Ctrl+C を押して停止します。

座学で学ぶ HTTP クライアントとタイムアウト

どの HTTP リクエストを計測しているか

この演習には、利用者から送料照会アプリへの HTTP 通信と、送料照会アプリから配送 API への HTTP 通信があります。 curl の time_total は前者の所要時間です。shipping.read-timeout は後者の読み取り待ちに適用されます。 ステータスを調べるときも、どちらの通信で観測した値かを確認します。

接続と読み取りで別の待ち時間を設定する

設定待ち時間を制限する箇所
接続タイムアウト相手への接続を確立するまでの待ち時間
読み取りタイムアウト接続後に応答のデータを読み取るときの待ち時間

模擬 API の slow は接続を受け付けてから、応答を送る前に 3 秒待ちます。 そのため、このケースでは読み取りタイムアウトの値を変えると結果が変わります。 タイムアウトの値を決める際は、配送 API の通常の応答時間と、利用者が送料照会の結果を待てる時間を考えます。

呼び出し先の失敗を利用者に伝える

この演習では、配送 API の 404 を「配送対象の地域がない」という照会結果として扱います。 配送 API の 500 は、送料照会アプリが呼び出し先の異常を検知した結果として 502 にします。 待ち時間を超えた場合は、送料照会アプリが 504 を返します。このとき配送 API の HTTP ステータスは読み取れていません。 こうして、利用者は地域コードを見直す場面と、配送 API の障害や遅延を調査する場面を区別できます。

理解を確かめる

  1. slow の結果を 200 から 504 に変えた設定を挙げ、どちらの HTTP 通信に適用されるか説明する。
  2. maintenance の照会で、配送 API と送料照会アプリが返すステータスをそれぞれ答える。
  3. 模擬 API を停止したときの接続拒否と、起動中の slow のタイムアウトを、利用者がどう区別できるか説明する。

続編の リトライ入門 では、同じ模擬 API を使って、再試行の条件と回数の上限、試行間の待ち時間を確認します。

参考資料