500。もう一度、押す前に。 ログと更新結果をつなげて調べる。

実装・エラー解決

Spring Bootで500エラーが出たら|再実行する前にログと更新結果を確認する

注文を登録したら500エラーが出た。もう一度押せば通るかもしれない。でも最初の注文が登録されていたら、二重になるかもしれない。

この記事は、Spring Bootアプリで初めて500エラーを調べる人向けです。同じリクエストの応答・ログ・保存結果を揃え、再実行前に何を確認するかを、手元で動く注文登録APIで追います。500が返ったときの再送前チェックへ直接進めます。

更新系の操作は、500だから何も保存されていないとは限りません。対象の注文と送信先の結果を確認するまで、むやみに同じ登録を繰り返さないでください。

この記事でわかること

  • 同じ500でも注文が1件残る場合と0件の場合がある理由
  • 応答のrequestIdからログ・自作コード・保存結果を照合する手順
  • 入力400や405/415を保ち、未知の例外を安全な500へ変換する例
  • HTTPだけでなく保存結果も検査するテスト

500は結果であって、故障箇所ではない

HTTP500は処理を完了できない予期しない状態をサーバーが検出した結果です。ステータスだけでは、DB・コード・応答変換・外部APIのどこで止まったか分かりません。HTTP仕様の定義

このサンプルは、商品BOOKを保存し、その後に通知スタブを呼びます。個別保存のコミットが先に済む経路では、通知失敗で500になっても対象の注文が1件残ります。Service全体のトランザクション内で同じ実行時例外が外へ出る経路では、対象の注文が0件になります。

対象リクエストの注文保存結果を比較。個別コミット後は通知スタブ失敗でHTTP500でも対象の注文1件が残る。Service全体のトランザクションでは同じ実行時例外でロールバックし、対象の注文0件になる。
件数は対象のrequestIdに対応する注文数で、DB全体の件数ではありません。囲み(Tx)はトランザクションの範囲です。通知失敗はローカルスタブの実行時例外で再現し、外部には送信しません。

このサンプルの通知は、例外を意図的に投げるローカルスタブです。外部サービスへは送信しません。実際の通知が受信済みか、通信の読み取りタイムアウトが起きたかを検証した例ではありません。

DBのロールバックは、外部への通知を取り消す機能ではありません。ここで比較するのはDBの保存境界です。通知処理をDBトランザクションへ含めることを、すべてのシステムへの修正方針として勧めるものではありません。

次の3ファイルを比べます。個別版のcreateには@Transactionalがなく、別BeanのOrderRepository.saveから戻る時点でその保存がコミットします。Tx版のcreateには@Transactionalがあり、Repositoryの保存もServiceのトランザクションへ参加します。saveReturned=trueだけでは、Tx版のコミット完了を意味しません。

クリックで全文を開く:IndividualCommitOrderService.java
package info.syachiku.order500;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;

@Service
public class IndividualCommitOrderService {
    private static final Logger log = LoggerFactory.getLogger(IndividualCommitOrderService.class);
    private final OrderRepository repository;
    private final NotificationStub notification;

    public IndividualCommitOrderService(OrderRepository repository, NotificationStub notification) {
        this.repository = repository;
        this.notification = notification;
    }

    public OrderView create(CreateOrderRequest request, String requestId) {
        OrderView order = repository.save(request.item(), requestId);
        log.info("operation=createOrder boundary=repository saveReturned=true requestId={}", requestId);
        notification.send(order, request.failNotification());
        log.info("operation=createOrder result=success requestId={}", requestId);
        return order;
    }
}
クリックで全文を開く:TransactionalOrderService.java
package info.syachiku.order500;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

@Service
public class TransactionalOrderService {
    private static final Logger log = LoggerFactory.getLogger(TransactionalOrderService.class);
    private final OrderRepository repository;
    private final NotificationStub notification;

    public TransactionalOrderService(OrderRepository repository, NotificationStub notification) {
        this.repository = repository;
        this.notification = notification;
    }

    @Transactional
    public OrderView create(CreateOrderRequest request, String requestId) {
        OrderView order = repository.save(request.item(), requestId);
        log.info("operation=createOrder boundary=service saveReturned=true commitNotYet=true requestId={}", requestId);
        notification.send(order, request.failNotification());
        log.info("operation=createOrder result=success requestId={}", requestId);
        return order;
    }
}
クリックで全文を開く:OrderRepository.java
package info.syachiku.order500;

import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Repository;
import org.springframework.transaction.annotation.Transactional;

import java.util.List;
import java.util.UUID;

@Repository
public class OrderRepository {
    private final JdbcTemplate jdbc;

    public OrderRepository(JdbcTemplate jdbc) {
        this.jdbc = jdbc;
    }

    @Transactional
    public OrderView save(String item, String requestId) {
        String orderId = UUID.randomUUID().toString();
        jdbc.update("INSERT INTO orders(order_id, item, request_id) VALUES (?, ?, ?)",
                orderId, item, requestId);
        return new OrderView(orderId, item, requestId);
    }

    @Transactional(readOnly = true)
    public List<OrderView> findByRequestId(String requestId) {
        return jdbc.query("SELECT order_id, item, request_id FROM orders WHERE request_id = ? ORDER BY order_id",
                (row, number) -> new OrderView(row.getString("order_id"),
                        row.getString("item"), row.getString("request_id")), requestId);
    }
}

通知スタブのIllegalStateExceptionは実行時例外です。デフォルトのロールバック条件を確認し、checked exceptionまで同じ扱いだと一般化しないでください。Springのロールバック条件。この例はControllerから別Service Beanを呼ぶ経路で、同じクラス内の自己呼出しの例ではありません。

クリックで全文を開く:NotificationStub.java
package info.syachiku.order500;

import org.springframework.stereotype.Component;

import java.net.SocketTimeoutException;

@Component
public class NotificationStub {
    public void send(OrderView order, boolean fail) {
        if (fail) {
            // ローカル例外モデル。ソケットも通知先への送信も作らない。
            throw new IllegalStateException("local notification stub failed",
                    new SocketTimeoutException("simulated notification timeout"));
        }
    }
}

最初の確認は、リクエスト・ログ・更新結果の三つ

調べるもの残す情報次の判断に使うこと
操作時刻、URL、HTTPメソッド、対象ID、操作内容どの一件を調べるか
サーバーログリクエストID、例外、原因チェーン、自作コードの行どこで止まったか
更新結果保存済みか、外部へ送信済みか、未確認か再実行してよいか

認証トークンや個人情報を丸ごとチケットへ貼る必要はありません。調査担当が原本を参照できる場所を残し、共有文は必要な情報へ絞ります。

まずは手元でHTTPと保存結果を揃えます。ZIPを展開してpom.xmlのある場所で次を実行してください。3行目はターミナルAで動き続けるコマンドです。H2はJVM内だけに作られ、停止すると破棄されます。

java -version
mvn clean verify
java -jar target/order-http500-2161-1.0.0.jar > application.log 2>&1

既定は127.0.0.1:18081です。ポート使用中ならjarの後ろに--server.port=18082を付け、以下のURLもすべて18082へ揃えます。新しいJVMの注文は0件。ターミナルBで初期状態を読みます。

curl -i http://127.0.0.1:18081/api/orders/by-request/demo-order-ok

最初はHTTP200、{"sourceRequestId":"demo-order-ok","count":0,"orders":[]}です。3例は異なるrequestIdを使います。

入力POST末尾HTTP対象requestIdの件数テスト
BOOK・通知成功/individual2011O01
BOOK・通知失敗/individual5001O02
BOOK・同じ通知失敗/transactional5000O03

件数は対象POSTのrequestIdに対応する注文数です。DB全件数ではありません。3例を同じ起動で順に試すと、正常と個別コミット失敗で全体には2件残ります。

500が返ったら、再送の前に対象の注文を確認する

このサンプルでは、500の応答に入っているrequestIdを使い、GET /api/orders/by-request/{requestId}で対象の注文を読みます。1件ならすでに保存されています。同じ注文を作り直すと増えるので、既存の注文IDを確認します。通知を再実行する場合は、先に送信先の結果も確認します。0件なら、この実行では注文が残っていません。エラーの原因を解消し、実務では他システムへの送信などが済んでいないかも確認してから再実行を判断します。

同じ失敗条件のPOSTを2回送り、送るたびに実HTTPのGETで件数を読みました。どちらの経路も応答は2回とも500です。個別にコミットする経路は0 → 1 → 2件、注文保存もロールバックする経路は0 → 0 → 0件でした。各経路は0件から開始し、経路内では同じX-Request-Idと同じ本文を送っています。

この例のX-Request-Idは、HTTPの応答とログ、注文を照合するためのIDです。同じ値を付けたPOSTをもう一度送ると、注文は追加されます。再送を受け付けるAPIでは、初回から同じ操作に使う受付IDを仕様に入れ、DBで重複しないようにします。同じ受付IDと同じ内容なら、先に保存した受付を返す実装にできます。

関連記事Spring BootでPOSTの二重登録を防ぐ|同じ受付IDの再送をDBで判定 同じ受付ID・同じ内容なら既存の受付を返し、同じIDで内容が異なれば409を返す例です。DBに1件だけ残ることをテストで確認します。 記事を読む

この記事の3例を手元でやり直す場合は、アプリを再起動するか、別のrequestIdに変えて確認用GETも揃えてください。

正常:201と対象注文1件

curl -i -X POST http://127.0.0.1:18081/api/orders/individual \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: demo-order-ok' \
  -d '{"item":"BOOK","failNotification":false}'

curl -i http://127.0.0.1:18081/api/orders/by-request/demo-order-ok

採取時のHTTP記録から、URL・ステータス・X-Request-Id・JSONを抜き出して表示用に整形しました。全ヘッダーを含む原記録はevidence/http-evidence.jsonにあります。手元の既定ポートは18081ですが、証跡の完全URLは検証用の一時ポートです。orderIdのUUIDと時刻は実行ごとに変わります。

POST http://127.0.0.1:61685/api/orders/individual
HTTP 201
X-Request-Id: demo-order-ok
{"orderId": "8e46c2c8-a30a-4c2c-b9c6-8473dcb57227", "item": "BOOK", "requestId": "demo-order-ok"}

GET http://127.0.0.1:61685/api/orders/by-request/demo-order-ok
HTTP 200
{"sourceRequestId": "demo-order-ok", "count": 1, "orders": [{"orderId": "8e46c2c8-a30a-4c2c-b9c6-8473dcb57227", "item": "BOOK", "requestId": "demo-order-ok"}]}

個別コミット後の通知失敗:500と対象注文1件

curl -i -X POST http://127.0.0.1:18081/api/orders/individual \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: demo-order-individual-fail' \
  -d '{"item":"BOOK","failNotification":true}'

curl -i http://127.0.0.1:18081/api/orders/by-request/demo-order-individual-fail

採取時のHTTP記録から、URL・ステータス・X-Request-Id・JSONを抜き出して表示用に整形しました。全ヘッダーを含む原記録はevidence/http-evidence.jsonにあります。手元の既定ポートは18081ですが、証跡の完全URLは検証用の一時ポートです。orderIdのUUIDと時刻は実行ごとに変わります。

POST http://127.0.0.1:61685/api/orders/individual
HTTP 500
X-Request-Id: demo-order-individual-fail
{"status": 500, "code": "INTERNAL_ERROR", "message": "処理を完了できませんでした", "requestId": "demo-order-individual-fail"}

GET http://127.0.0.1:61685/api/orders/by-request/demo-order-individual-fail
HTTP 200
{"sourceRequestId": "demo-order-individual-fail", "count": 1, "orders": [{"orderId": "c6498ea2-592d-4205-aaad-ae5db8c32558", "item": "BOOK", "requestId": "demo-order-individual-fail"}]}

Service Tx内の通知失敗:500と対象注文0件

curl -i -X POST http://127.0.0.1:18081/api/orders/transactional \
  -H 'Content-Type: application/json' \
  -H 'X-Request-Id: demo-order-transactional-fail' \
  -d '{"item":"BOOK","failNotification":true}'

curl -i http://127.0.0.1:18081/api/orders/by-request/demo-order-transactional-fail

採取時のHTTP記録から、URL・ステータス・X-Request-Id・JSONを抜き出して表示用に整形しました。全ヘッダーを含む原記録はevidence/http-evidence.jsonにあります。手元の既定ポートは18081ですが、証跡の完全URLは検証用の一時ポートです。orderIdのUUIDと時刻は実行ごとに変わります。

POST http://127.0.0.1:61685/api/orders/transactional
HTTP 500
X-Request-Id: demo-order-transactional-fail
{"status": 500, "code": "INTERNAL_ERROR", "message": "処理を完了できませんでした", "requestId": "demo-order-transactional-fail"}

GET http://127.0.0.1:61685/api/orders/by-request/demo-order-transactional-fail
HTTP 200
{"sourceRequestId": "demo-order-transactional-fail", "count": 0, "orders": []}

POST完了後のGETは別のHTTP・別の読取りトランザクションです。GET自身にもX-Request-Idが付きますが、照合するのはURLの元POSTのIDとJSONのsourceRequestIdです。POSTが500でも保存されたかは、この読取で確認します。

クリックで全文を開く:OrderApplication.java
package info.syachiku.order500;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class OrderApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderApplication.class, args);
    }
}
クリックで全文を開く:OrderController.java
package info.syachiku.order500;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.validation.Valid;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@RestController
public class OrderController {
    private final IndividualCommitOrderService individual;
    private final TransactionalOrderService transactional;
    private final OrderRepository repository;

    public OrderController(IndividualCommitOrderService individual,
            TransactionalOrderService transactional, OrderRepository repository) {
        this.individual = individual;
        this.transactional = transactional;
        this.repository = repository;
    }

    @PostMapping("/api/orders/individual")
    public ResponseEntity<OrderView> createIndividual(@Valid @RequestBody CreateOrderRequest body,
            HttpServletRequest request) {
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(individual.create(body, RequestIdFilter.current(request)));
    }

    @PostMapping("/api/orders/transactional")
    public ResponseEntity<OrderView> createTransactional(@Valid @RequestBody CreateOrderRequest body,
            HttpServletRequest request) {
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(transactional.create(body, RequestIdFilter.current(request)));
    }

    @GetMapping("/api/orders/by-request/{requestId}")
    public OrderReadback readByRequest(@PathVariable String requestId) {
        List<OrderView> orders = repository.findByRequestId(requestId);
        return new OrderReadback(requestId, orders.size(), orders);
    }
}
クリックで全文を開く:CreateOrderRequest.java
package info.syachiku.order500;

import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Size;

public record CreateOrderRequest(
        @NotBlank @Size(max = 64) String item,
        boolean failNotification) {
}
クリックで全文を開く:OrderView.java
package info.syachiku.order500;

public record OrderView(String orderId, String item, String requestId) {
}
クリックで全文を開く:OrderReadback.java
package info.syachiku.order500;

import java.util.List;

public record OrderReadback(String sourceRequestId, int count, List<OrderView> orders) {
}
クリックで全文を開く:pom.xml
<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.samples</groupId><artifactId>order-http500-2161</artifactId><version>1.0.0</version>
  <properties><java.version>17</java.version><project.build.sourceEncoding>UTF-8</project.build.sourceEncoding></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-jdbc</artifactId></dependency>
    <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-validation</artifactId></dependency>
    <dependency><groupId>com.h2database</groupId><artifactId>h2</artifactId><scope>runtime</scope></dependency>
    <dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>
  </dependencies>
  <build><plugins><plugin><groupId>org.springframework.boot</groupId><artifactId>spring-boot-maven-plugin</artifactId></plugin></plugins></build>
</project>
クリックで全文を開く:application.properties
server.address=127.0.0.1
server.port=18081
spring.datasource.url=jdbc:h2:mem:order500;DB_CLOSE_DELAY=-1
spring.datasource.username=sa
spring.datasource.password=
spring.sql.init.mode=always
spring.h2.console.enabled=false
server.error.include-message=never
server.error.include-stacktrace=never
logging.pattern.console=%d{yyyy-MM-dd'T'HH:mm:ss.SSSXXX} %-5level requestId=%X{requestId:-none} %logger{36} - %msg%n
クリックで全文を開く:schema.sql
CREATE TABLE IF NOT EXISTS orders (
    order_id VARCHAR(36) PRIMARY KEY,
    item VARCHAR(64) NOT NULL,
    request_id VARCHAR(64) NOT NULL
);

画面の時刻から、同じリクエストのログを探す

実行時刻に加え、POST応答のX-Request-IdとJSONのrequestIdを控えます。今回はdemo-order-individual-failです。リクエスト全体を無差別に貼るのではなく、そのIDで対象の処理を絞ります。

sed -n '/result=failed.*requestId=demo-order-individual-fail/,$p' application.log

次は配布のevidence/request-matching.logからそのまま取り出した実採取ログの先頭です。架空のOrderServiceや行番号を作った説明ではありません。

2026-11-13T15:49:21.076+09:00 ERROR requestId=demo-order-individual-fail i.s.order500.ApiExceptionHandler - operation=createOrder result=failed path=/api/orders/individual requestId=demo-order-individual-fail
java.lang.IllegalStateException: local notification stub failed
	at info.syachiku.order500.NotificationStub.send(NotificationStub.java:12)
	at info.syachiku.order500.IndividualCommitOrderService.create(IndividualCommitOrderService.java:21)
	at info.syachiku.order500.OrderController.createIndividual(OrderController.java:32)

この後のフレームワークのスタック行はここでは省略し、原因チェーンの行だけを示します。省略前のログ全文と実ソース行の対応は、配布のevidence/request-matching.logとevidence/source-locations.jsonにあります。

Caused by: java.net.SocketTimeoutException: simulated notification timeout

NotificationStub.sendで例外を作り、IndividualCommitOrderService.createからControllerへ出ています。例外の原因名がSocketTimeoutExceptionでも、この教材ではスタブが作った例外で、ネットワークの実タイムアウトではありません。API応答から受信先の成否を判断することもできません。

保存はNotificationStubより前です。ログのsaveReturned=trueが個別版ではコミット後、Service Tx版ではcommitNotYet=trueとともに未コミットの記録になることを、先の実装とGETで照合します。Service Tx版の500ログはTransactionalOrderService.createを指します。同じ操作を再実行してよいかは、業務上の注文IDとDB・送信先の結果を別途調べて判断します。

requestIdを設定するコードも次に含めています。指定値は英数字で始まる64文字以内の英数字・ピリオド・下線・ハイフンだけを採用し、不正または未指定ならUUIDを発行します。MDCには処理中だけ入れ、finallyで消すため、同じスレッドの次の要求へ前のIDを残しません。

クリックで全文を開く:RequestIdFilter.java
package info.syachiku.order500;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.UUID;

@Component
public class RequestIdFilter extends OncePerRequestFilter {
    public static final String ATTRIBUTE = "requestId";

    @Override
    protected void doFilterInternal(HttpServletRequest request,
            HttpServletResponse response, FilterChain chain)
            throws ServletException, IOException {
        String supplied = request.getHeader("X-Request-Id");
        String requestId = supplied != null
                && supplied.matches("[A-Za-z0-9][A-Za-z0-9._-]{0,63}")
                ? supplied : UUID.randomUUID().toString();
        request.setAttribute(ATTRIBUTE, requestId);
        response.setHeader("X-Request-Id", requestId);
        MDC.put("requestId", requestId);
        try {
            chain.doFilter(request, response);
        } finally {
            MDC.remove("requestId");
        }
    }

    public static String current(HttpServletRequest request) {
        return (String) request.getAttribute(ATTRIBUTE);
    }
}

例外ごとに、最初に見る場所を変える

ログの手がかり最初の確認
NullPointerException発生行でnullだった値と、その値を返した処理
DB制約違反保存値、制約、既存データ、同時更新
外部通信のタイムアウト呼び出し先、相手の処理結果、再試行の有無
応答のJSON変換エラー戻り値の型や参照関係、保存との処理順
テンプレート処理のエラーView名、式、Modelへ渡した値

今回の通知スタブは500調査の一例です。NullPointerExceptionやDB制約、JSON応答変換などの500まで、通知の問題として扱わないでください。起動していないアプリには別の入口が必要です。Bean不足は起動ログ、プロキシが返す500なら応答したサーバーを確認します。アプリに対象リクエストがなければ、まずどこが500を返したかを絞ります。

スタックのCaused byからどの自作コードを開くかで止まった場合は、次の記事で原因チェーンの読み方を確認できます。

関連記事Javaのスタックトレースの読み方|Caused byの後、どのコードを開けばいい? Caused byと自作コードの行を手掛かりに、例外の原因・渡された値・次に調べる場所を絞る手順を確認できます。 記事を読む

原因が未確定でも、第一報は出せる

次は上のローカル実行で確認できた事実を第一報へまとめた説明例です。本番障害の実績や、外部通知を受信できたことを示す報告ではありません。

2026-11-13T15:49:21.076+09:00の実行で、BOOKの注文登録POSTがHTTP500になりました。requestIdはdemo-order-individual-failです。同じIDのログにNotificationStub.sendの実行時例外があり、POST完了後のGETでは対象注文が1件残っています。通知はローカル故障スタブで、外部へ送信していません。同じ操作の再実行はせず、保存境界と他リクエストへの影響を確認します。次の連絡時点を担当者間で決め、原因が未確定でもそこまでに分かった事実を共有します。

事実は500・対象ID・保存1件。外部通知先の状態を調べた記録はありません。「次に連絡する時点」と「復旧する時点」は別です。Service Tx版を報告するなら、同じ例外でも保存結果が0件であることと、対象IDがdemo-order-transactional-failであることへ置き換えます。異なるリクエストのログや件数を一つの障害報告へ混ぜないでください。

全例外をcatchして200を返す修正はしない

画面の500を消すためにcatchして200へ変えると、失敗が成功に見えます。未知の例外は500にし、利用者へ内部クラス名・SQL・スタックを返さず、調査ログには原因チェーンを残します。次は配布と同じ例外ハンドラ全文です。

クリックで全文を開く:ApiExceptionHandler.java
package info.syachiku.order500;

import jakarta.servlet.http.HttpServletRequest;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.HttpStatusCode;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.ServletWebRequest;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.mvc.method.annotation.ResponseEntityExceptionHandler;

@RestControllerAdvice
public class ApiExceptionHandler extends ResponseEntityExceptionHandler {
    private static final Logger log = LoggerFactory.getLogger(ApiExceptionHandler.class);

    @Override
    protected ResponseEntity<Object> handleExceptionInternal(Exception exception, Object body,
            HttpHeaders headers, HttpStatusCode status, WebRequest webRequest) {
        HttpServletRequest request = ((ServletWebRequest) webRequest).getRequest();
        String requestId = RequestIdFilter.current(request);
        boolean serverError = status.is5xxServerError();
        if (serverError) {
            log.error("operation=request result=failed path={} requestId={}",
                    request.getRequestURI(), requestId, exception);
        }
        ApiError safeBody = new ApiError(status.value(),
                serverError ? "INTERNAL_ERROR" : "INVALID_REQUEST",
                serverError ? "処理を完了できませんでした" : "入力内容を確認してください", requestId);
        // 405のAllowなど、Springが決めたstatusと必要headerを維持する。
        return new ResponseEntity<>(safeBody, headers, status);
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiError> handleUnexpected(Exception exception, HttpServletRequest request) {
        String requestId = RequestIdFilter.current(request);
        log.error("operation=createOrder result=failed path={} requestId={}",
                request.getRequestURI(), requestId, exception);
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(new ApiError(500, "INTERNAL_ERROR", "処理を完了できませんでした", requestId));
    }
}
クリックで全文を開く:ApiError.java
package info.syachiku.order500;

public record ApiError(int status, String code, String message, String requestId) {
}

handleUnexpectedは未知例外を500へ変換し、status/code/message/requestIdだけを返します。入力不備などSpring MVCが識別した例外は、ResponseEntityExceptionHandlerのhandleExceptionInternalで安全なJSONへ変えます。ここではSpringが決めたstatusとheadersをそのまま返すため、壊れたJSONとitem省略の400、メソッド不一致の405とAllow、メディアタイプ不一致の415を維持します。

200へ変更する故障が検査で見つかることも、O02で確認しています。エラー本文だけが500でもHTTPが200なら失敗です。Spring公式の例外ハンドラ。画面向けの案内と、権限管理した調査ログを分けてください。

修正後は「画面が通る」より先へ確認する

このサンプルの確認は「画面がエラーでなくなったか」だけではありません。正常の201と注文1件、500でも1件残る個別コミット版、同じ500で0件になるService Tx版を、完了後の別HTTP GETまで見て確かめます。

検査入力・操作期待値
O00未投入requestId0件
O01/O04BOOK・通知成功、個別版/Service Tx版201、対象1件、応答とGET同一
O02BOOK・個別保存後の通知失敗500、対象1件、安全JSONと原因ログ
O03BOOK・Service Tx内の通知失敗500、対象0件、原因ログ
O05/O06壊れたJSON/item省略400、対象0件
O07不正requestIdUUIDへ置換、応答と保存ID一致
O08POST用URLへGET405、AllowにPOST、対象0件
O09text/plain送信415、対象0件
F01/F02同一スレッド2要求/チェーンIOExceptionID独立、MDCを終了後除去

通知が成功した後にも処理が続くなら、どこで失敗させるかをテストで分けます。Service分割の実習では、メール送信の記録が付いた後で監査を失敗させると、注文と監査は0件に戻っても、メール送信を模した記録が1件残ります。実案件でも、再送を判断する前にDBの結果と実際の送信履歴をそれぞれ照合します。

実践|通知後の失敗もテストするSpringのServiceが肥大化したらどこで分ける?計算・保存・通知の分割例 注文保存・メール送信・監査の順に呼ぶ処理を、分割前と分割後で検証します。メールの送信記録と処理終了後のDBを別々に確認できます。 記事を読む

手動実行と採取ログはdemo-order-で始まるID、JUnitは独立したhttp-で始まるIDを使います。同じIDの再利用による件数混在を避けるためで、商品BOOKと通知失敗の条件は対応しています。

O00〜O09はRANDOM_PORTで起動した実サーバーへJava HttpClientでアクセスする10件です。テスト全体へ@Transactionalは付けず、別HTTP GETで保存結果を読みます。FilterのF01/F02はMockHttpServletRequest/Responseを使う単体2件で、HTTPテストの件数へ混ぜません。

クリックで全文を開く:OrderHttpTest.java
package info.syachiku.order500;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.extension.ExtendWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.system.CapturedOutput;
import org.springframework.boot.test.system.OutputCaptureExtension;
import org.springframework.boot.test.web.server.LocalServerPort;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;
import java.util.UUID;

import static org.junit.jupiter.api.Assertions.*;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@ExtendWith(OutputCaptureExtension.class)
class OrderHttpTest {
    @LocalServerPort
    private int port;
    private final ObjectMapper json = new ObjectMapper();
    private final HttpClient http = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(5)).build();

    private URI uri(String path) {
        return URI.create("http://127.0.0.1:" + port + path);
    }

    private HttpResponse<String> post(String boundary, String requestId, String body) throws Exception {
        return http.send(HttpRequest.newBuilder(uri("/api/orders/" + boundary))
                .timeout(Duration.ofSeconds(10))
                .header("Content-Type", "application/json")
                .header("X-Request-Id", requestId)
                .POST(HttpRequest.BodyPublishers.ofString(body)).build(),
                HttpResponse.BodyHandlers.ofString());
    }

    private JsonNode readback(String sourceRequestId) throws Exception {
        // POST完了後の別HTTP GET。テスト全体へ@Transactionalを付けない。
        HttpResponse<String> response = http.send(HttpRequest.newBuilder(
                        uri("/api/orders/by-request/" + sourceRequestId))
                .timeout(Duration.ofSeconds(10)).GET().build(), HttpResponse.BodyHandlers.ofString());
        assertEquals(200, response.statusCode());
        JsonNode body = json.readTree(response.body());
        assertEquals(sourceRequestId, body.get("sourceRequestId").asText());
        return body;
    }

    private void assertError(HttpResponse<String> response, int expectedStatus, String requestId)
            throws Exception {
        assertEquals(expectedStatus, response.statusCode());
        assertTrue(response.headers().firstValue("Content-Type").orElse("").contains("application/json"));
        assertEquals(requestId, response.headers().firstValue("X-Request-Id").orElseThrow());
        JsonNode body = json.readTree(response.body());
        assertEquals(4, body.size());
        assertEquals(expectedStatus, body.get("status").asInt());
        assertEquals(requestId, body.get("requestId").asText());
        assertEquals(expectedStatus == 500 ? "INTERNAL_ERROR" : "INVALID_REQUEST",
                body.get("code").asText());
        assertEquals(expectedStatus == 500 ? "処理を完了できませんでした" : "入力内容を確認してください",
                body.get("message").asText());
        assertFalse(response.body().contains("SocketTimeoutException"));
        assertFalse(response.body().contains(".java:"));
        assertFalse(response.body().contains("INSERT INTO"));
    }

    @Test
    void O00_initialUnsubmittedRequest_hasNoRows() throws Exception {
        JsonNode db = readback("http-never-submitted");
        assertEquals(0, db.get("count").asInt());
        assertEquals(0, db.get("orders").size());
    }

    @Test
    void O01_success_returns201AndOneCommittedOrder(CapturedOutput output) throws Exception {
        String id = "http-individual-ok";
        HttpResponse<String> response = post("individual", id,
                "{\"item\":\"BOOK\",\"failNotification\":false}");
        assertEquals(201, response.statusCode());
        JsonNode created = json.readTree(response.body());
        assertEquals(id, created.get("requestId").asText());
        assertEquals(id, response.headers().firstValue("X-Request-Id").orElseThrow());
        JsonNode db = readback(id);
        assertEquals(1, db.get("count").asInt());
        assertEquals(created, db.get("orders").get(0));
        assertTrue(output.getAll().contains("operation=createOrder result=success requestId=" + id));
    }

    @Test
    void O02_individualFailure_returns500ButKeepsOneOrder(CapturedOutput output) throws Exception {
        String id = "http-individual-fail";
        HttpResponse<String> response = post("individual", id,
                "{\"item\":\"BOOK\",\"failNotification\":true}");
        assertError(response, 500, id);
        JsonNode db = readback(id);
        assertEquals(1, db.get("count").asInt());
        assertEquals("BOOK", db.get("orders").get(0).get("item").asText());
        assertEquals(id, db.get("orders").get(0).get("requestId").asText());
        assertTrue(output.getAll().contains("path=/api/orders/individual requestId=" + id));
        assertTrue(output.getAll().contains("Caused by: java.net.SocketTimeoutException: simulated notification timeout"));
        assertTrue(output.getAll().contains("NotificationStub.send(NotificationStub.java:"));
        assertTrue(output.getAll().contains("IndividualCommitOrderService.create(IndividualCommitOrderService.java:"));
    }

    @Test
    void O03_serviceTransactionFailure_returns500AndRollsBack(CapturedOutput output) throws Exception {
        String id = "http-transactional-fail";
        HttpResponse<String> response = post("transactional", id,
                "{\"item\":\"BOOK\",\"failNotification\":true}");
        assertError(response, 500, id);
        JsonNode db = readback(id);
        assertEquals(0, db.get("count").asInt());
        assertEquals(0, db.get("orders").size());
        assertTrue(output.getAll().contains("path=/api/orders/transactional requestId=" + id));
        assertTrue(output.getAll().contains("commitNotYet=true requestId=" + id));
        assertTrue(output.getAll().contains("Caused by: java.net.SocketTimeoutException: simulated notification timeout"));
        assertTrue(output.getAll().contains("TransactionalOrderService.create(TransactionalOrderService.java:"));
    }

    @Test
    void O04_serviceTransactionSuccess_returns201AndOneOrder() throws Exception {
        String id = "http-transactional-ok";
        HttpResponse<String> response = post("transactional", id,
                "{\"item\":\"BOOK\",\"failNotification\":false}");
        assertEquals(201, response.statusCode());
        JsonNode db = readback(id);
        assertEquals(1, db.get("count").asInt());
        assertEquals(json.readTree(response.body()), db.get("orders").get(0));
    }

    @Test
    void O05_malformedJson_returnsSafe400AndNoRows() throws Exception {
        String id = "http-malformed";
        assertError(post("individual", id, "{"), 400, id);
        assertEquals(0, readback(id).get("count").asInt());
    }

    @Test
    void O06_missingItem_returnsSafe400AndNoRows() throws Exception {
        String id = "http-missing-item";
        assertError(post("individual", id,
                "{}"), 400, id);
        assertEquals(0, readback(id).get("count").asInt());
    }

    @Test
    void O07_invalidSuppliedRequestId_isReplacedWithUuid() throws Exception {
        HttpResponse<String> response = post("individual", "bad id",
                "{\"item\":\"BOOK\",\"failNotification\":false}");
        assertEquals(201, response.statusCode());
        String id = response.headers().firstValue("X-Request-Id").orElseThrow();
        assertDoesNotThrow(() -> UUID.fromString(id));
        assertEquals(id, json.readTree(response.body()).get("requestId").asText());
        assertEquals(1, readback(id).get("count").asInt());
    }

    @Test
    void O08_wrongMethod_preserves405AndAllow() throws Exception {
        String id = "http-wrong-method";
        HttpResponse<String> response = http.send(HttpRequest.newBuilder(uri("/api/orders/individual"))
                .header("X-Request-Id", id).GET().build(), HttpResponse.BodyHandlers.ofString());
        assertError(response, 405, id);
        assertTrue(response.headers().firstValue("Allow").orElse("").contains("POST"));
        assertEquals(0, readback(id).get("count").asInt());
    }

    @Test
    void O09_wrongMediaType_preserves415() throws Exception {
        String id = "http-wrong-media";
        HttpResponse<String> response = http.send(HttpRequest.newBuilder(uri("/api/orders/individual"))
                .header("X-Request-Id", id).header("Content-Type", "text/plain")
                .POST(HttpRequest.BodyPublishers.ofString("BOOK")).build(),
                HttpResponse.BodyHandlers.ofString());
        assertError(response, 415, id);
        assertEquals(0, readback(id).get("count").asInt());
    }
}
クリックで全文を開く:RequestIdFilterTest.java
package info.syachiku.order500;

import org.junit.jupiter.api.Test;
import org.slf4j.MDC;
import org.springframework.mock.web.MockHttpServletRequest;
import org.springframework.mock.web.MockHttpServletResponse;

import java.io.IOException;
import java.util.UUID;

import static org.junit.jupiter.api.Assertions.*;

class RequestIdFilterTest {
    @Test
    void F01_sequentialRequestsOnSameThread_haveSeparateIdsAndClearMdc() throws Exception {
        RequestIdFilter filter = new RequestIdFilter();
        assertNull(MDC.get("requestId"));
        MockHttpServletRequest first = new MockHttpServletRequest();
        first.addHeader("X-Request-Id", "filter-first");
        MockHttpServletResponse firstResponse = new MockHttpServletResponse();
        filter.doFilter(first, firstResponse, (request, response) -> {
            assertEquals("filter-first", MDC.get("requestId"));
            assertEquals("filter-first", request.getAttribute(RequestIdFilter.ATTRIBUTE));
        });
        assertEquals("filter-first", firstResponse.getHeader("X-Request-Id"));
        assertNull(MDC.get("requestId"));

        MockHttpServletRequest second = new MockHttpServletRequest();
        MockHttpServletResponse secondResponse = new MockHttpServletResponse();
        filter.doFilter(second, secondResponse, (request, response) -> {
            String id = (String) request.getAttribute(RequestIdFilter.ATTRIBUTE);
            assertDoesNotThrow(() -> UUID.fromString(id));
            assertNotEquals("filter-first", id);
            assertEquals(id, MDC.get("requestId"));
        });
        assertNotEquals(firstResponse.getHeader("X-Request-Id"), secondResponse.getHeader("X-Request-Id"));
        assertNull(MDC.get("requestId"));
    }

    @Test
    void F02_chainIOException_stillClearsMdcInFinally() {
        RequestIdFilter filter = new RequestIdFilter();
        MockHttpServletRequest request = new MockHttpServletRequest();
        request.addHeader("X-Request-Id", "filter-throws");
        IOException failure = new IOException("local test failure");
        IOException actual = assertThrows(IOException.class, () -> filter.doFilter(request,
                new MockHttpServletResponse(), (req, res) -> {
                    assertEquals("filter-throws", MDC.get("requestId"));
                    throw failure;
                }));
        assertSame(failure, actual);
        assertNull(MDC.get("requestId"));
    }
}
mvn clean verify
mvn test '-Dtest=OrderHttpTest#O02*'
mvn test '-Dtest=OrderHttpTest#O03*'

1行目の全件コマンドは、原本とZIP展開先の両方で実HTTP10件+Filter2件、合計12件成功を確認しました。2・3行目はそれぞれ対象1件です。検証用アプリは終了後に停止しています。

誤修正の検出も別コピーで確認しました。handleUnexpectedの500をResponseEntity.ok()へ変えると、O02はexpected500/actual200で失敗します。TransactionalOrderService.createの@Transactionalだけを外すと、O03はHTTP500のままでもcountのexpected0/actual1で失敗します。両方とも戻した対象テスト1件の成功と、修正版ZIPの全12件成功を確認しています。元コードを変えず、手順はREADMEに従って別コピーで試してください。

レビュー前に確認すること

  • 応答・ログ・GETの元requestIdが同じか
  • 対象注文数とDB全件数を混同していないか
  • saveReturnedをTx全体のコミット完了と誤認していないか
  • 400/405/415と未知500を200へ変えていないか
  • 通知先の受信結果が未確認なら、再実行を確定していないか
  • ログや共有文へ認証情報や個人情報を混ぜていないか

保存境界を別の題材で試す:ユーザーとプロフィール

以下は今回の注文APIとは別の、記事1567で取得できる登録Serviceの2テストです。既存ユーザー/プロフィール各1件から、同じハンドル名で新規登録するとプロフィールの一意制約で失敗します。対象は注文や通知ではなく、ユーザー総数とプロフィール総数です。今回のHTTP10件+Filter2件には合算しません。

下のカードから別サンプルZIPを取得し、JDK17/Maven3.9系でpom.xmlの場所からmvn -Dtest=RegistrationServiceTest testを実行します。両ケースで例外が出ることと、失敗後のDB件数を検査する2テストです。

保存の境界ユーザー総数プロフィール総数
個々の保存でコミット2件1件
Serviceで一つのトランザクション1件1件

個々の保存では新規ユーザーだけが残り、Serviceでまとめると追加はロールバックします。この例の2件/1件はユーザー総数で、今回のrequestId別注文1件/0件とは集計範囲も違います。

関連記事Spring Bootの@Transactionalはどこに付ける? 同じプロフィール保存エラーでも、トランザクション境界で保存件数がどう変わるかを比較できます。サンプルZIPとテスト全文もここから確認できます。 記事を読む

保存後に例外が出たとき、何がDBへ残るかをコードで判断するには、DI/AOPとトランザクション・JDBCのつながりを整理する必要があります。『Spring徹底入門 第2版』はこのつながりを学び直したい人の候補です。本書が扱うSpring Framework5と、今回実行したBoot3.5.16の設定や版を同一視しないでください。

書籍「Spring徹底入門 第2版」の表紙
商品画像:Amazon.co.jp
PR 入門後の参考書|Spring Framework 5向け

Spring徹底入門 第2版

株式会社NTTデータ (著), 株式会社NTTデータグループ (編集)

アプリを作った後に、DIやDB更新の仕組みを調べる。

DI、MVC、データアクセス、テスト、セキュリティまで幅広く確認できます。小さなWebアプリを一通り作り、Springの仕組みを詳しく学びたい人に向く参考書です。

  • Springで小さなWebアプリを作ったことがある
  • DIやトランザクションの仕組みを確認したい

Spring Framework 5向けです。Boot 3の実装に使うコード・設定は、採用している版の公式資料と照合してください。

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

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