通販の注文画面で配送先を入力すると、外部の送料見積APIへ問い合わせます。ある日、画面に「この地域には配送できません」と出ました。利用者が入力した郵便番号は対象地域です。調べると、送料見積APIはメンテナンス中で 503 を返していました。
送料が見つからない結果と、送料を確認できなかった結果では、利用者の次の行動が変わります。見積APIが対象なしを 404 で返す契約なら、その場合だけ Optional.empty() に変えます。503 や 401 は失敗として呼び出し元へ伝えます。
この記事でわかること
retrieve().body()がHTTPエラーに出会ったときの動き- 外部APIの404だけを「該当なし」に変える書き方
- 200・404・503・401・本文なしの200を、外部サーバーなしで試す方法
記事と同じコードを実行する
ZIPを展開し、JDK 17とMaven 3.9系で mvn test を実行します。Javaの本体とテスト、pom.xml、READMEを収録しています。送料見積APIへの通信はテスト内で置き換えます。
503でも「配送不可」になるのは、catchの範囲が広すぎるから
改修前の画面は、見積が入った Optional なら送料を表示し、空なら「この地域には配送できません」と案内します。呼び出し元からは、どのHTTPステータスを受け取ったかが空の値に含まれません。クライアントで401や503まで空に変換した時点で、後段で表示を分ける手掛かりを失います。
RestClient の既定の retrieve().body() は、4xxや5xxを読み取ると例外にします。retrieve() のチェーンを作っただけで結果を受け取ったと思わず、応答を読み出す body() までを見てください。既定の扱いはSpring Framework 6.2のRestClient資料で確認できます。
下は修正版の findQuote のcatchだけを差し替える再現用の抜粋です。この変更を入れると、503や401の例外も捕まえ、404と同じ空の結果を返します。
再現用の抜粋(catchの型だけ変更)
catch (org.springframework.web.client.RestClientResponseException ex) {
return Optional.empty();
}対象が見つからない 見積なし
Optional.empty()取得できない 取得失敗
ServiceUnavailable画面だけでは、どこで結果が変わったか分かりません。開発環境で同じ郵便番号を指定し、まず自分のアプリが受け取った外部APIのステータスを確認します。外部は503を返しているのに、findQuote の結果が空なら、Controllerの表示を調べる前に、クライアントが例外をどの値へ変換したかを追います。修正後は同じ入力で503の例外が残ることを確認します。
ここで見ているのは、自分のアプリが外部へ送ったGETの応答です。ブラウザや他のアプリから自分のControllerへ入力が来る段階で400になるときは、リクエストの形やバインドを確かめます。
見積あり、見積なし、取得失敗の三つを呼び出し元に伝える
まず配送チームのAPI契約を確認します。今回の架空の契約では、GET /shipping-quotes/{postalCode} が見積のある郵便番号に200とJSONを返し、見積を提供できる対象が見つからない場合に404を返します。この契約の下で、呼び出し元へ返す結果を次のように決めます。
| 外部APIの応答 | Javaの結果 | 呼び出し元の判断 |
|---|---|---|
| 200と見積JSON | Optional.of(見積) | 600円の見積を表示できる |
| 404 | Optional.empty() | APIの契約に従って見積なしを案内する |
| 503 | ServiceUnavailable | 見積確認が一時的にできない。呼び出し元で利用者への案内を決める |
| 401 | Unauthorized | 外部APIへ送る認証情報や設定を調べる |
| 200で本文なし | IllegalStateException | 成功応答に見積を含める契約を確認する |
404を見積なしと扱う前に、接続先のURLとパスが合っていることも確かめます。環境設定を変えた直後からどの郵便番号でも404なら、見積が存在することが分かっている郵便番号で、ホスト・パス・APIの版を確認します。404の意味が提供元の契約に書かれていない場合は、空に変える判断を保留します。
たとえば検証環境で、提供元が見積ありと明記した郵便番号と、見積なしと明記した郵便番号を一つずつ指定します。前者が200と見積JSON、後者が404なら、対象の有無を区別できています。両方が404なら、入力だけを変えても原因を切り分けられません。リクエストが届いたホストとパスを提供元の例に照らします。「見積なし」は送料データの有無を表すため、画面を「配送不可」とするかは業務ルールで決めます。
NotFoundだけを捕まえ、200の本文なしも失敗にする
クライアントに渡すのは、接続先と RestClient.Builder です。findQuote はGETとJSONの受け取りを行い、正常な見積を返します。catchの対象を HttpClientErrorException.NotFound に絞ると、401の Unauthorized と503の ServiceUnavailable は捕まらず、そのまま呼び出し元へ届きます。これは追加のステータスハンドラーを設定していない場合の例です。
ShippingQuoteClient.java(全文)
package info.syachiku.shipping;
import java.util.Optional;
import org.springframework.http.MediaType;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.RestClient;
public final class ShippingQuoteClient {
private final RestClient client;
public ShippingQuoteClient(RestClient.Builder builder, String baseUrl) {
this.client = builder.baseUrl(baseUrl).build();
}
public Optional<ShippingQuote> findQuote(String postalCode) {
try {
ShippingQuote quote = client.get()
.uri("/shipping-quotes/{postalCode}", postalCode)
.accept(MediaType.APPLICATION_JSON)
.retrieve()
.body(ShippingQuote.class);
if (quote == null) {
throw new IllegalStateException("送料見積APIの成功応答に見積がありません");
}
return Optional.of(quote);
} catch (HttpClientErrorException.NotFound ex) {
return Optional.empty();
}
}
}body(ShippingQuote.class) が本文を返さない場合は、成功に必要なデータがないため例外にしています。空ボディを Optional.ofNullable(quote) へそのまま渡すと、200の契約違反を404と同じ結果に戻してしまいます。ここでは配送サービス名と料金だけを受け取ります。料金の上限や、JSON内の各フィールドの必須条件は提供元との契約に合わせて別に定義します。
ShippingQuote.java(全文)
package info.syachiku.shipping;
public record ShippingQuote(String service, int feeYen) {
}Spring Bootのアプリに組み込むときは、Spring Boot 3.5の公式資料にある、構成済みの RestClient.Builder を注入して使う方法が入口になります。接続先を環境ごとの設定に置き、クライアントの生成時に渡します。ここではHTTPクライアントの結果を検証するところまでを扱います。
同じGETに5種類の応答を返し、失敗が消えないか確かめる
ZIPを展開したら、pom.xml がある場所で mvn test を実行します。MockRestServiceServer を RestClient.Builder に先に結び付け、同じBuilderから本体を作ります。JUnitは外部サーバーを使わず、各テストで返すステータスと本文を選びます。テスト対象は、実際にコードが組み立てたリクエストと、それに対するJSON変換や例外の結果です。
各テストはURL、GET、Accept: application/json を確認します。200のテストは600円という結果まで照合し、503と401のテストは例外の型とHTTPステータスを確認します。404のテストだけを見ていると、503を誤って空にした変更も通るため、失敗の扱いを別に確かめます。
テストを読むときは、まず preserves503AsFailure を開きます。andRespond で外部から来る503を用意し、assertThrows の中で郵便番号 1000001 の見積を1回取りに行きます。そこで得た例外の getStatusCode() も503と照合します。次に returnsEmptyFor404 を見ると、同じ郵便番号で応答だけを404に変え、期待値を空にしていることが分かります。入力をそろえることで、結果を分けた条件がHTTP応答だと追えます。
ShippingQuoteClientTest.java(全文)
package info.syachiku.shipping;
import java.util.Optional;
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.springframework.http.HttpMethod;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.test.web.client.MockRestServiceServer;
import org.springframework.test.web.client.ResponseActions;
import org.springframework.web.client.HttpClientErrorException;
import org.springframework.web.client.HttpServerErrorException;
import org.springframework.web.client.RestClient;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.springframework.test.web.client.match.MockRestRequestMatchers.header;
import static org.springframework.test.web.client.match.MockRestRequestMatchers.method;
import static org.springframework.test.web.client.match.MockRestRequestMatchers.requestTo;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withStatus;
import static org.springframework.test.web.client.response.MockRestResponseCreators.withSuccess;
class ShippingQuoteClientTest {
private static final String BASE_URL = "https://shipping.example.test";
private static final String POSTAL_CODE = "1000001";
private MockRestServiceServer server;
private ShippingQuoteClient client;
@BeforeEach
void setUp() {
RestClient.Builder builder = RestClient.builder();
server = MockRestServiceServer.bindTo(builder).build();
client = new ShippingQuoteClient(builder, BASE_URL);
}
@AfterEach
void verifyRequest() {
server.verify();
}
@Test
void returnsQuoteFor200Json() {
expectQuoteRequest().andRespond(withSuccess(
"""
{"service":"STANDARD","feeYen":600}
""", MediaType.APPLICATION_JSON));
assertEquals(Optional.of(new ShippingQuote("STANDARD", 600)),
client.findQuote(POSTAL_CODE));
}
@Test
void returnsEmptyFor404() {
expectQuoteRequest().andRespond(withStatus(HttpStatus.NOT_FOUND));
assertEquals(Optional.empty(), client.findQuote(POSTAL_CODE));
}
@Test
void preserves503AsFailure() {
expectQuoteRequest().andRespond(withStatus(HttpStatus.SERVICE_UNAVAILABLE));
var error = assertThrows(HttpServerErrorException.ServiceUnavailable.class,
() -> client.findQuote(POSTAL_CODE));
assertEquals(HttpStatus.SERVICE_UNAVAILABLE, error.getStatusCode());
}
@Test
void preserves401AsFailure() {
expectQuoteRequest().andRespond(withStatus(HttpStatus.UNAUTHORIZED));
var error = assertThrows(HttpClientErrorException.Unauthorized.class,
() -> client.findQuote(POSTAL_CODE));
assertEquals(HttpStatus.UNAUTHORIZED, error.getStatusCode());
}
@Test
void failsWhen200HasNoQuoteBody() {
expectQuoteRequest().andRespond(withStatus(HttpStatus.OK));
var error = assertThrows(IllegalStateException.class,
() -> client.findQuote(POSTAL_CODE));
assertEquals("送料見積APIの成功応答に見積がありません", error.getMessage());
}
private ResponseActions expectQuoteRequest() {
return server.expect(requestTo(BASE_URL + "/shipping-quotes/" + POSTAL_CODE))
.andExpect(method(HttpMethod.GET))
.andExpect(header("Accept", MediaType.APPLICATION_JSON_VALUE));
}
}pom.xml(全文)
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.16</version>
<relativePath/>
</parent>
<groupId>info.syachiku</groupId>
<artifactId>restclient-shipping-status-sample</artifactId>
<version>1.0.0</version>
<properties>
<java.version>17</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
</dependency>
</dependencies>
</project>修正版は5件すべて成功します。冒頭で示したcatchへ広げてから同じ mvn test を実行すると、503と401の2件が「例外が投げられなかった」と報告します。200・404・本文なしの200の3件は引き続き成功します。手元で再現したらcatchを元に戻し、5件が成功する状態へ戻します。
修正版とcatchを広げた再現版のログ抜粋
修正版: mvn test
[INFO] Tests run: 5, Failures: 0, Errors: 0, Skipped: 0
再現版: mvn test
[ERROR] ShippingQuoteClientTest.preserves401AsFailure:75 Expected org.springframework.web.client.HttpClientErrorException.Unauthorized to be thrown, but nothing was thrown.
[ERROR] ShippingQuoteClientTest.preserves503AsFailure:66 Expected org.springframework.web.client.HttpServerErrorException.ServiceUnavailable to be thrown, but nothing was thrown.
[ERROR] Tests run: 5, Failures: 2, Errors: 0, Skipped: 0MockRestServiceServerのRestClient用APIで、Builderを渡す形を確認できます。今回の5件はHTTP応答の扱いを対象にしています。ネットワーク断やタイムアウト、実際の配送サービスとの契約は、開発・検証環境で別に確かめます。
レビューでは「空になった理由」を、呼び出し元が判断できるかを見る
レビューコメント例「404で見積なしになることは確認できました。503のときも同じ画面表示になると、メンテナンス中に利用者が配送対象外だと判断します。クライアントでは503を例外として残し、呼び出し元のテストで『見積を確認できません』の案内を確認しましょう。」
外部APIのステータスを、そのまま自分の画面やAPIのステータスにする必要はありません。外部サービスへの401なら、自分の利用者がログインし直しても直らない構成があります。外部への認証設定を確認する担当へ原因が伝わるよう、呼び出し元の例外処理で、利用者向けの案内と調査に必要な情報を決めます。
画面側の受入条件を書くなら、404では「送料の見積がありません」と案内し、503では「現在、送料を確認できません」と案内する、と結果を分けます。たとえば、503で送料を0円とみなして注文確定へ進めてしまうと、後から請求額を直す必要が出ます。送料を確定できるまで注文を止める業務なら、503のときに確定ボタンが使えないことも画面側のテストに加えます。本文のサンプルが確認するのは、その判断に必要な503がクライアントの外に届くところまでです。
503の再試行を加える場合も、まず503だったと分かることが前提です。画面で待てる時間、再試行できる回数、外部APIの制限を決めてから変更します。今回のコードに再試行は入っていないため、5件の成功を再試行まで確認した結果として扱いません。
提出前に、対象なしと取得失敗のテストを一つずつ確認する
- 提供元の資料で、対象なしを返すステータスと正常時に必要な本文を確認した。
- 対象のURLとGETメソッドを、見積が存在する入力で確認した。
- 404を空にするテストと、401・503で例外を残すテストを別々に用意した。
- 200のJSONから配送サービスと料金を取り出すことを確認した。
- 取得に失敗したとき、利用者に何を案内し、担当者が何を調べるか決めた。
HTTPの結果を読めるようになる本。ステータスコードとリクエストの役割から学び直すなら、『Webを支える技術』のステータスコードの章が入口です。外部APIの仕様書を読むとき、どの応答を呼び出し元の判断に使うかを整理しやすくなります。
Webを支える技術
HTTP・URI・RESTを、Webアプリ開発の土台から理解する。
RequestParamやRequestBodyの暗記だけでは見えにくい、Web通信の基本原則を整理できます。
- HTTPの仕組みから理解したい
- RESTやURIの設計意図を学びたい
当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。
この記事とあわせて読みたい
まとめ
外部APIの仕様に合わせて、見積あり・見積なし・取得失敗を分けます。404だけを Optional.empty() に変えるなら、401と503が呼び出し元へ届くテストも同時に書きます。空になった値から失敗理由を探すより、変換する場所で理由を残す方が、利用者の案内と担当者の調査をそろえやすくなります。



