送料見積APIの404と503を別の結果に仕分ける記事のアイキャッチ

実装・エラー解決

Spring BootのRestClientで404だけを「見つからない」にする|503を見落とさないテスト

通販の注文画面で配送先を入力すると、外部の送料見積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への通信はテスト内で置き換えます。

サンプルZIPをダウンロード GitHubでコード全文と実行手順を見る

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();
}
同じ送料見積APIでも、404と503は別の結果にする
404 提供元の契約で
対象が見つからない
見積なし Optional.empty()
503 一時的に見積を
取得できない
取得失敗 ServiceUnavailable

画面だけでは、どこで結果が変わったか分かりません。開発環境で同じ郵便番号を指定し、まず自分のアプリが受け取った外部APIのステータスを確認します。外部は503を返しているのに、findQuote の結果が空なら、Controllerの表示を調べる前に、クライアントが例外をどの値へ変換したかを追います。修正後は同じ入力で503の例外が残ることを確認します。

ここで見ているのは、自分のアプリが外部へ送ったGETの応答です。ブラウザや他のアプリから自分のControllerへ入力が来る段階で400になるときは、リクエストの形やバインドを確かめます。

関連記事Spring Bootで400 Bad Requestになる原因|Controllerに値が入らない時の確認順 自分のControllerが400を返すときは、リクエストの型や必須項目をこの手順で確かめます。 記事を読む

見積あり、見積なし、取得失敗の三つを呼び出し元に伝える

まず配送チームのAPI契約を確認します。今回の架空の契約では、GET /shipping-quotes/{postalCode} が見積のある郵便番号に200とJSONを返し、見積を提供できる対象が見つからない場合に404を返します。この契約の下で、呼び出し元へ返す結果を次のように決めます。

外部APIの応答Javaの結果呼び出し元の判断
200と見積JSONOptional.of(見積)600円の見積を表示できる
404Optional.empty()APIの契約に従って見積なしを案内する
503ServiceUnavailable見積確認が一時的にできない。呼び出し元で利用者への案内を決める
401Unauthorized外部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: 0

MockRestServiceServerの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を支える技術」の表紙
商品画像:Amazon.co.jp
PR Web開発に入る新人向け

Webを支える技術

山本 陽平 (著)

HTTP・URI・RESTを、Webアプリ開発の土台から理解する。

RequestParamやRequestBodyの暗記だけでは見えにくい、Web通信の基本原則を整理できます。

  • HTTPの仕組みから理解したい
  • RESTやURIの設計意図を学びたい

当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。

関連記事Spring Boot初心者におすすめの本3冊|現場で必要な力を身につける Spring Bootで機能を作り、HTTPの流れを説明し、テストで変更を確かめるための本を選べます。 記事を読む 関連記事Spring Bootで500エラーが出たら|再実行する前にログと更新結果を確認する 自分のアプリが500を返したら、再実行する前にログと更新結果を照合し、どこまで処理が進んだかを確認します。 記事を読む

まとめ

外部APIの仕様に合わせて、見積あり・見積なし・取得失敗を分けます。404だけを Optional.empty() に変えるなら、401と503が呼び出し元へ届くテストも同時に書きます。空になった値から失敗理由を探すより、変換する場所で理由を残す方が、利用者の案内と担当者の調査をそろえやすくなります。

-実装・エラー解決
-, ,