Spring Boot 例外処理・エラー応答入門
講義の区切り
基本編の目安は 90 分です。終了条件は「404・409・400・500の契約を確認」です。
発展内容・次回の目安: その他 MVC 例外・MockMvc の契約テスト。基本の確認後に取り組んでください。
準備と前後の章は 学習ガイド で確認できます。
概要
応答形式の設計は RFC 9457 エラー返却入門 で学びます。
対象が存在しない、名前が重複する、入力が不正といった失敗を、利用者が判断できる HTTP 応答に変換します。
Controller ごとに例外処理を書く代わりに、@RestControllerAdvice で共通化します。
想定外の失敗では、内部情報を応答に含めず、調査に必要な例外をログに残します。
対象読者
- Controller / Service とバリデーションを使った API を作成できる方
- 例外と HTTP ステータスの対応を整理したい方
- フロントエンドから扱いやすいエラー応答を作りたい方
事前準備と到達目標
Java 21、Maven Wrapper、Spring Boot 4.0 系を使います。
バリデーション入門 と テスト入門 の基本部分を前提にします。
DB アクセス・トランザクション入門 の後に読むと、保存処理の失敗との関係も整理できます。
ただし、このハンズオンのプロジェクトは独立しています。
Spring Initializr で Maven / Java / Jar / YAML を選び、新しいプロジェクトを作成します。
パッケージ名は dev.mikoto2000.springboot.errors にします。
依存関係は Spring Web と Validation です。DB、Lombok、Spring Security は使いません。
このハンズオンでは、サーブレットを使う Spring MVC で例外を処理します。
完了時には、失敗の種類ごとにステータスとエラーコードを決め、共通形式で返せることを目指します。
HTTP の応答とサーバーの調査用ログを分け、テストで契約を確認できるようにしましょう。
この資料の構成
この資料は 2 部構成です。
- 触って学ぶ例外処理・エラー応答: 失敗する API を作り、共通応答とテストを実装するハンズオン。
- 座学で学ぶ例外処理・エラー応答: 例外の責務、HTTP ステータス、応答形式、ログの考え方を整理する座学。
触って学ぶ例外処理・エラー応答
題材とする商品 API
商品名を登録し、名前を指定して取得します。
データはメモリー上に保持し、再起動すると失われます。
DB アクセスを省き、例外から HTTP 応答への変換に集中します。
故障の再現用エンドポイントは、ローカル演習のために作ります。
演習後に削除し、公開するアプリには含めません。
DTO と業務例外の作成
以下の Java ファイルは src/main/java/dev/mikoto2000/springboot/errors の下に配置します。
Initializr が生成した @SpringBootApplication のクラスも、このパッケージに置きます。
ProductRequest.java
package dev.mikoto2000.springboot.errors;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Pattern;
import jakarta.validation.constraints.Size;
public record ProductRequest(
@NotBlank @Size(max = 50) @Pattern(regexp = "[A-Za-z0-9_-]+") String name) {}
商品名はこの教材では英数字・_・- の1〜50文字に制限します。
/、;、空白を受け入れるとパスとしての意味が変わるため、400 で拒否します。
本番の API では、表示名と URL に使う安定した ID を分ける設計も検討してください。
Product.java
package dev.mikoto2000.springboot.errors;
public record Product(String name) {}
ProductNotFoundException.java
package dev.mikoto2000.springboot.errors;
public class ProductNotFoundException extends RuntimeException {
public ProductNotFoundException() {
super("Product not found");
}
}
DuplicateProductException.java
package dev.mikoto2000.springboot.errors;
public class DuplicateProductException extends RuntimeException {
public DuplicateProductException() {
super("Product already exists");
}
}
Service と Controller の作成
ProductService.java
package dev.mikoto2000.springboot.errors;
import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
import org.springframework.stereotype.Service;
@Service
public class ProductService {
private final ConcurrentMap<String, Product> products = new ConcurrentHashMap<>();
public Product create(String name) {
Product product = new Product(name);
if (products.putIfAbsent(name, product) != null) {
throw new DuplicateProductException();
}
return product;
}
public Product find(String name) {
Product product = products.get(name);
if (product == null) {
throw new ProductNotFoundException();
}
return product;
}
}
putIfAbsent は、存在確認と登録をひとつの操作として行います。
今回は完全に一致する名前を重複とみなします。大文字小文字や前後の空白の正規化は扱いません。
ProductController.java
package dev.mikoto2000.springboot.errors;
import java.net.URI;
import jakarta.validation.Valid;
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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.util.UriComponentsBuilder;
@RestController
@RequestMapping("/products")
public class ProductController {
private final ProductService service;
public ProductController(ProductService service) {
this.service = service;
}
@PostMapping
public ResponseEntity<Product> create(@Valid @RequestBody ProductRequest request) {
Product product = service.create(request.name());
URI location = UriComponentsBuilder.fromPath("/products/{name}")
.encode().buildAndExpand(product.name()).toUri();
return ResponseEntity.created(location).body(product);
}
@GetMapping("/{name}")
public Product find(@PathVariable("name") String name) {
return service.find(name);
}
}
FailureDemoController.java
package dev.mikoto2000.springboot.errors;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class FailureDemoController {
@GetMapping("/demo/failure")
public void fail() {
throw new IllegalStateException("Demo internal failure");
}
}
ハンドラー追加前の確認
アプリを起動し、存在しない商品を取得します。
別のターミナルで実行します。コマンドは Bash 用です。
PowerShell では .\mvnw.cmd と curl.exe を使い、JSON はファイルに保存して --data-binary @request.json で送れます。
curl -i http://localhost:8080/products/missing
まだ業務例外を HTTP に対応付けていないため、応答は 500 になります。
商品が存在しないという利用者に説明できる失敗を、404 に変換しましょう。
業務例外 1 件を 404 に変換する
ApiExceptionHandler.java を作成します。@RestControllerAdvice はハンドラーを Controller 間で共通化し、@ExceptionHandler は処理する例外型を指定します。まず、商品が見つからない場合だけを扱います。
ApiExceptionHandler.java(最初の段階)
package dev.mikoto2000.springboot.errors;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
@RestControllerAdvice
public class ApiExceptionHandler {
@ExceptionHandler(ProductNotFoundException.class)
public ProblemDetail notFound(ProductNotFoundException ex) {
return ProblemDetail.forStatusAndDetail(
HttpStatus.NOT_FOUND, "指定した商品が見つかりません");
}
}
アプリを再起動し、同じリクエストを送ります。
curl -i http://localhost:8080/products/missing
HTTP ステータスが 500 から 404 に変わり、Content-Type が application/problem+json になることを確認します。本文の status と detail は上のコードから組み立てられ、instance には Spring MVC がリクエストのパスを設定します。
重複・入力不正・想定外の失敗まで広げる
先ほどの ApiExceptionHandler.java を、以下の完成版に置き換えます。業務例外と想定外の例外は @ExceptionHandler で対応付けます。JSON の読み取り失敗と DTO の制約違反は、ResponseEntityExceptionHandler が用意する専用メソッドを上書きします。
ProblemDetail の code はアプリが決める識別子です。制約違反では errors、想定外の失敗ではログとの照合用に errorId を追加します。
ApiExceptionHandler の完成コード
ApiExceptionHandler.java
package dev.mikoto2000.springboot.errors;
import java.net.URI;
import java.util.List;
import java.util.UUID;
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.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.http.converter.HttpMessageNotReadableException;
import org.springframework.web.bind.MethodArgumentNotValidException;
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);
public record FieldError(String field, String message) {}
private ProblemDetail problem(HttpStatusCode status, String code,
String detail, WebRequest request) {
ProblemDetail body = ProblemDetail.forStatusAndDetail(status, detail);
body.setProperty("code", code);
// Spring MVC の例外処理では ServletWebRequest が渡されます。
String path = ((ServletWebRequest) request).getRequest().getRequestURI();
// 明示設定するとこの値が使われ、未設定なら Spring MVC がリクエストのパスで補います。
body.setInstance(URI.create(path));
return body;
}
@ExceptionHandler(ProductNotFoundException.class)
public ResponseEntity<ProblemDetail> notFound(
ProductNotFoundException ex, WebRequest request) {
ProblemDetail body = problem(HttpStatus.NOT_FOUND, "PRODUCT_NOT_FOUND",
"指定した商品が見つかりません", request);
return ResponseEntity.status(HttpStatus.NOT_FOUND).body(body);
}
@ExceptionHandler(DuplicateProductException.class)
public ResponseEntity<ProblemDetail> duplicate(
DuplicateProductException ex, WebRequest request) {
ProblemDetail body = problem(HttpStatus.CONFLICT, "PRODUCT_ALREADY_EXISTS",
"同じ名前の商品が登録されています", request);
return ResponseEntity.status(HttpStatus.CONFLICT).body(body);
}
@Override
protected ResponseEntity<Object> handleMethodArgumentNotValid(
MethodArgumentNotValidException ex, HttpHeaders headers,
HttpStatusCode status, WebRequest request) {
ProblemDetail body = problem(status, "VALIDATION_ERROR",
"入力内容を確認してください", request);
List<FieldError> errors = ex.getBindingResult().getFieldErrors().stream()
.map(error -> new FieldError(error.getField(), error.getDefaultMessage()))
.toList();
body.setProperty("errors", errors);
return handleExceptionInternal(ex, body, headers, status, request);
}
@Override
protected ResponseEntity<Object> handleHttpMessageNotReadable(
HttpMessageNotReadableException ex, HttpHeaders headers,
HttpStatusCode status, WebRequest request) {
ProblemDetail body = problem(status, "INVALID_JSON",
"JSON の形式または値の型が不正です", request);
return handleExceptionInternal(ex, body, headers, status, request);
}
@ExceptionHandler(Exception.class)
public ResponseEntity<ProblemDetail> unexpected(Exception ex, WebRequest request) {
String errorId = UUID.randomUUID().toString();
log.error("Unexpected error. errorId={}", errorId, ex);
ProblemDetail body = problem(HttpStatus.INTERNAL_SERVER_ERROR, "INTERNAL_ERROR",
"処理中にエラーが発生しました", request);
body.setProperty("errorId", errorId);
return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(body);
}
}
対象なしと重複の確認
アプリを停止し、再起動してから順に実行します。
curl -i http://localhost:8080/products/missing
curl -i -X POST http://localhost:8080/products -H 'Content-Type: application/json' -d '{"name":"Book"}'
curl -i -X POST http://localhost:8080/products -H 'Content-Type: application/json' -d '{"name":"Book"}'
curl -i http://localhost:8080/products/Book
順に 404・201・409・200 になります。
404 の Content-Type は application/problem+json で、本文は次の形になります。
{
"title": "Not Found",
"status": 404,
"detail": "指定した商品が見つかりません",
"instance": "/products/missing",
"code": "PRODUCT_NOT_FOUND"
}
Spring Framework 7 では ProblemDetail の type は既定で設定されません。
この教材の標準構成では、Spring の Jackson 用ミックスインが未設定の type を JSON 応答から省略します。
たとえば、ミックスインなしの JsonMapper で直接シリアライズすると "type": null が出力されます。
RFC 9457 では、type がない場合は about:blank とみなします。
about:blank は、HTTP ステータス以上の意味を持たないことを表します。
Spring Framework 6.2 以前は "type": "about:blank" が出力されていました。
利用者は detail の文章を解析せず、HTTP ステータスと code で処理を分岐できます。
入力不正と JSON 読み取り失敗の確認
curl -i -X POST http://localhost:8080/products -H 'Content-Type: application/json' -d '{"name":""}'
curl -i -X POST http://localhost:8080/products -H 'Content-Type: application/json' -d '{'
どちらも 400 ですが、前者は VALIDATION_ERROR、後者は INVALID_JSON です。
前者には errors 配列があり、field が name の項目を確認できます。
制約のメッセージはロケールなどで変わるため、完全な文章が同じであることを成功判定に使いません。
JSON の読み取りが失敗すると、DTO のバリデーションまで進めません。
INVALID_JSON の detail に、パーサーの例外メッセージや受け取った JSON をそのまま返さないようにします。
想定外の失敗とログの確認
curl -i http://localhost:8080/demo/failure
故障の再現では、500 と INTERNAL_ERROR、errorId が返ります。
応答に Demo internal failure やスタックトレースは含まれません。
サーバーログには同じ errorId と例外のスタックトレースが記録されます。
発展: 他の MVC 例外も共通形式にする
基本編はここまでです。405 や 415 も共通形式にする場合は、ApiExceptionHandler のクラス内に次のメソッドを追加します。ResponseEntityExceptionHandler が受け取ったステータスとヘッダーを super.handleExceptionInternal(...) に渡します。
フレームワークが生成した 405 などの detail は、共通形式の「リクエストを処理できません」に置き換えます。
ApiExceptionHandler に追加
@Override
protected ResponseEntity<Object> handleExceptionInternal(
Exception ex, Object body, HttpHeaders headers,
HttpStatusCode status, WebRequest request) {
// MVC のその他の例外も共通形式にする。元のステータスとヘッダーを維持する。
ProblemDetail result = body instanceof ProblemDetail pd ? pd
: problem(status, "HTTP_" + status.value(),
"リクエストを処理できません", request);
if (result.getProperties() == null || !result.getProperties().containsKey("code")) {
result = problem(status, "HTTP_" + status.value(),
"リクエストを処理できません", request);
}
return super.handleExceptionInternal(ex, result, headers, status, request);
}
アプリを再起動し、未対応のメソッドを送ります。
curl -i -X PATCH http://localhost:8080/products/Book
PATCH は定義していないため、405 と HTTP_405 が返ります。
Allow ヘッダーも確認してください。未対応のメソッドを 500 に変換しないことが重要です。
MockMvc による契約の検証
この節は発展内容です。直前の節で追加した共通処理も含めて検証します。
pom.xml の dependencies に、次の依存関係があることを確認します。
JUnit と Mockito の基本は テスト入門 を参照してください。
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-webmvc-test</artifactId>
<scope>test</scope>
</dependency>
次を src/test/java/dev/mikoto2000/springboot/errors/ApiExceptionHandlerTest.java に配置します。
講義では ApiExceptionHandlerTest の責務と確認する結果に注目します。実装時には次の完成コードを開いて配置してください。
ApiExceptionHandlerTest の完成コード
package dev.mikoto2000.springboot.errors;
import static org.hamcrest.Matchers.containsString;
import static org.hamcrest.Matchers.not;
import static org.mockito.Mockito.when;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.patch;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.header;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.webmvc.test.autoconfigure.WebMvcTest;
import org.springframework.context.annotation.Import;
import org.springframework.http.MediaType;
import org.springframework.test.context.bean.override.mockito.MockitoBean;
import org.springframework.test.web.servlet.MockMvc;
@WebMvcTest(ProductController.class)
@Import(ApiExceptionHandler.class)
class ApiExceptionHandlerTest {
@Autowired
MockMvc mvc;
@MockitoBean
ProductService service;
@Test
void missingProductReturns404() throws Exception {
when(service.find("missing")).thenThrow(new ProductNotFoundException());
mvc.perform(get("/products/missing"))
.andExpect(status().isNotFound())
.andExpect(content().contentTypeCompatibleWith(MediaType.APPLICATION_PROBLEM_JSON))
.andExpect(jsonPath("$.status").value(404))
.andExpect(jsonPath("$.code").value("PRODUCT_NOT_FOUND"))
.andExpect(jsonPath("$.instance").value("/products/missing"));
}
@Test
void duplicateProductReturns409() throws Exception {
when(service.create("Book")).thenThrow(new DuplicateProductException());
mvc.perform(post("/products").contentType(MediaType.APPLICATION_JSON)
.content("{\"name\":\"Book\"}"))
.andExpect(status().isConflict())
.andExpect(jsonPath("$.code").value("PRODUCT_ALREADY_EXISTS"));
}
@Test
void invalidInputReturnsFieldErrors() throws Exception {
mvc.perform(post("/products").contentType(MediaType.APPLICATION_JSON)
.content("{\"name\":\"\"}"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.code").value("VALIDATION_ERROR"))
.andExpect(jsonPath("$.errors[0].field").value("name"));
}
@Test
void namesWithPathSyntaxAreRejected() throws Exception {
for (String name : new String[] {"A/B", "A;B", "A B", "A".repeat(51)}) {
mvc.perform(post("/products").contentType(MediaType.APPLICATION_JSON)
.content("{\"name\":\"" + name + "\"}"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.code").value("VALIDATION_ERROR"));
}
}
@Test
void acceptedNameCanBeReadFromLocation() throws Exception {
String name = "A".repeat(50);
when(service.create(name)).thenReturn(new Product(name));
when(service.find(name)).thenReturn(new Product(name));
String location = mvc.perform(post("/products").contentType(MediaType.APPLICATION_JSON)
.content("{\"name\":\"" + name + "\"}"))
.andExpect(status().isCreated())
.andExpect(header().string("Location", "/products/" + name))
.andReturn().getResponse().getHeader("Location");
mvc.perform(get(location)).andExpect(status().isOk())
.andExpect(jsonPath("$.name").value(name));
}
@Test
void malformedJsonReturns400() throws Exception {
mvc.perform(post("/products").contentType(MediaType.APPLICATION_JSON).content("{"))
.andExpect(status().isBadRequest())
.andExpect(jsonPath("$.code").value("INVALID_JSON"));
}
@Test
void unexpectedFailureDoesNotExposeInternalMessage() throws Exception {
when(service.find("broken")).thenThrow(new IllegalStateException("private detail"));
mvc.perform(get("/products/broken"))
.andExpect(status().isInternalServerError())
.andExpect(jsonPath("$.code").value("INTERNAL_ERROR"))
.andExpect(jsonPath("$.errorId").isNotEmpty())
.andExpect(content().string(not(containsString("private detail"))));
}
@Test
void unsupportedMethodKeeps405AndAllowHeader() throws Exception {
mvc.perform(patch("/products/Book"))
.andExpect(status().isMethodNotAllowed())
.andExpect(jsonPath("$.code").value("HTTP_405"))
.andExpect(header().string("Allow", containsString("GET")));
}
}
実行して、8 件のテストが成功することを確認します。
このテストは Service をモックにし、例外から HTTP 応答への変換を検証しています。
重複の判定ロジック自体は Service のテストで検証します。
練習
- 商品名の最大長を超えるリクエストを送り、項目エラーを確認する。
Content-Type: text/plain で登録し、415 のまま共通形式になることを確認する。
- Service の重複判定と取得を、Spring を起動しない単体テストで検証する。
座学で学ぶ例外処理・エラー応答
例外を定義する場所と責務
Service は、対象がない、業務上の条件に反するといった失敗を判断します。
HTTP ステータスを Service に持たせず、HTTP への変換を Advice に置くと、他の入口でも業務処理を再利用できます。
今回の業務例外は、利用者に伝える失敗の分類を表します。
例外の getMessage() をそのまま応答に使うと、内部の実装情報が契約に混ざります。
応答用の文章とコードはハンドラーで決めましょう。
DB を使う場合、事前に SELECT して重複を確認するだけでは同時登録を防げません。
DB の一意制約でも守り、対象の制約違反を業務上の重複に変換します。
すべての DataIntegrityViolationException を重複扱いにすると、外部キー違反なども 409 になってしまいます。
どの制約の失敗か判断できる範囲で変換し、原因の例外は保持します。
Advice と HTTP ステータス
@RestControllerAdvice は、Controller の処理中に伝わった例外を共通処理にまとめます。
@ExceptionHandler で扱う例外を指定し、ステータスと本文を返します。
Controller 内のハンドラーや複数の Advice を併用する場合は、適用範囲と優先順位も確認してください。
4xx はリクエストに関係する失敗、5xx はサーバー側の失敗を表す分類です。
再試行できるかは、ステータスだけでは決まりません。
POST の再試行は処理の重複につながる可能性があります。
再試行と重複防止は API ごとに設計します。
RFC 9457 とエラーコード
Problem Details は、HTTP API のエラーを表す標準形式です。
RFC 9457 が定義する標準メンバーは type、title、status、detail、instance の 5 つで、すべて省略可能です。
この資料では、共通応答を組み立てるために必要な範囲だけを使います。
Spring の ProblemDetail は、RFC 9457 の標準項目と追加項目を扱います。
追加項目はアプリで決める契約です。
同じ detail を返し続けるより、安定した code を用意すると表示の翻訳や文章の変更がしやすくなります。
instance はこの教材ではパスなので、同じ URL の複数の失敗を一意には識別しません。
500 の個々の発生は errorId で区別します。
既存教材の ValidationErrors 形式も使えます。
同じ API 内で形式を統一し、すでに利用者がいる API では、応答形式の変更を互換性の変更として扱ってください。
独自の type と拡張メンバーの設計は RFC 9457 エラー返却入門 で扱います。
JSON の読み取りと入力検証の違い
リクエスト本文を Java オブジェクトへ変換し、その後で @Valid の制約を検証します。
JSON の読み取り失敗と制約違反では、発生する段階と例外の種類が異なります。
引数へ直接付けた制約の検証には HandlerMethodValidationException が使われる場合もあります。
これは入力の違反と戻り値の違反を区別する必要があります。
戻り値の制約違反はサーバー側の問題なので、すべてを 400 に変換しないでください。
今回の Controller は DTO の @Valid を使う範囲に絞っています。
内部情報と調査用ログ
利用者向けの応答には、SQL、DB の接続情報、クラス名、スタックトレースを含めません。
想定外の例外は固定したメッセージと調査用 ID を返し、サーバーで例外の原因を記録します。
ログの保管先にもアクセス制御が必要です。例外メッセージに機密情報が含まれる場合は、記録する内容を見直します。
想定内の入力不正を毎回 ERROR にすると、調査すべき障害が埋もれます。
今回の業務例外ではログを追加せず、想定外の例外を ERROR としています。
業務監査や頻度の把握が必要なら、アクセスログやメトリクスを組み合わせます。
ロギング入門 の MDC を使えば、リクエスト全体のログを関連付ける方法も学べます。
トランザクションとの関係と処理範囲
Controller からトランザクション付き Service を呼び、例外が外に伝わると、Service の境界でロールバックが判断されます。
その後に Advice が HTTP 応答へ変換します。
Advice が例外を処理しても、Service ですでに判断されたロールバックを取り消すことにはなりません。
Service 内で catch して成功を返すと、意図したロールバックやエラー応答にならない場合があります。
「どの層で捕捉するか」と「どこまで例外を伝えるか」を合わせて設計してください。
Advice は、すべての失敗を処理する仕組みではありません。
Spring Security のフィルターで発生する認証・認可の失敗は、対応する Security のハンドラーで処理します。
定期実行処理、別スレッド、応答を書き出した後の失敗にも、それぞれの処理が必要です。
別スレッドの処理は、Controller の例外ハンドラーへ自動で伝わるとは限りません。
エラー応答を契約としてテストする
正常系だけでなく、失敗時のステータス、Content-Type、エラーコード、必要な項目を検証します。
想定外の失敗では、内部メッセージが応答に含まれないことも検証できます。
UUID の具体的な値や、エラーメッセージの細かな表記には依存しすぎないようにします。
MockMvc のテストは HTTP への変換を確認し、Service の単体テストは業務条件を確認します。
DB の制約違反やロールバックは、実物の DB と組み合わせたテストで確認しましょう。
まとめ
- Service は失敗の意味を判断し、Advice は HTTP 応答に変換する。
- ステータスと安定したコードを使い、利用者が対応を選べるようにする。
- 入力不正、業務上の失敗、想定外の失敗を区別する。
- 内部情報は応答に含めず、調査用 ID とログで追跡する。
- 正常系と同様に、エラー応答もテストで契約を確認する。
参考資料