> 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.

# Spring Boot 例外処理・エラー応答入門

## 講義の区切り

基本編の目安は 90 分です。終了条件は「404・409・400・500の契約を確認」です。
発展内容・次回の目安: その他 MVC 例外・MockMvc の契約テスト。基本の確認後に取り組んでください。
準備と前後の章は [学習ガイド](/Practical-Introduction-to-Spring-Boot/introduction.md) で確認できます。

## 概要

応答形式の設計は [RFC 9457 エラー返却入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/RFC9457エラー応答入門.md) で学びます。

対象が存在しない、名前が重複する、入力が不正といった失敗を、利用者が判断できる HTTP 応答に変換します。
Controller ごとに例外処理を書く代わりに、`@RestControllerAdvice` で共通化します。
想定外の失敗では、内部情報を応答に含めず、調査に必要な例外をログに残します。

## 対象読者

- Controller / Service とバリデーションを使った API を作成できる方
- 例外と HTTP ステータスの対応を整理したい方
- フロントエンドから扱いやすいエラー応答を作りたい方

## 事前準備と到達目標

Java 21、Maven Wrapper、Spring Boot 4.0 系を使います。
[バリデーション入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/バリデーション入門.md) と [テスト入門](/Practical-Introduction-to-Spring-Boot/SpringBootテスト入門/テスト入門.md) の基本部分を前提にします。
[DB アクセス・トランザクション入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/DBアクセス・トランザクション入門.md) の後に読むと、保存処理の失敗との関係も整理できます。
ただし、このハンズオンのプロジェクトは独立しています。

[Spring Initializr](https://start.spring.io/) で Maven / Java / Jar / YAML を選び、新しいプロジェクトを作成します。
パッケージ名は `dev.mikoto2000.springboot.errors` にします。
依存関係は Spring Web と Validation です。DB、Lombok、Spring Security は使いません。
このハンズオンでは、サーブレットを使う Spring MVC で例外を処理します。

完了時には、失敗の種類ごとにステータスとエラーコードを決め、共通形式で返せることを目指します。
HTTP の応答とサーバーの調査用ログを分け、テストで契約を確認できるようにしましょう。

## この資料の構成

この資料は 2 部構成です。

1. 触って学ぶ例外処理・エラー応答: 失敗する API を作り、共通応答とテストを実装するハンズオン。
2. 座学で学ぶ例外処理・エラー応答: 例外の責務、HTTP ステータス、応答形式、ログの考え方を整理する座学。

| 触って学ぶ（ハンズオン）      | 座学で学ぶ（理論）           |
| ----------------- | ------------------- |
| 対象なし・重複の業務例外      | 例外を定義する場所と責務        |
| 共通ハンドラーの追加        | Advice と HTTP ステータス |
| ProblemDetail の返却 | RFC 9457 とエラーコード    |
| 入力不正の処理           | JSON の読み取りと入力検証の違い  |
| 想定外の例外の処理         | 内部情報と調査用ログ          |
| MockMvc による検証（発展） | エラー応答を契約としてテストする    |

## 触って学ぶ例外処理・エラー応答

### 題材とする商品 API

商品名を登録し、名前を指定して取得します。
データはメモリー上に保持し、再起動すると失われます。
DB アクセスを省き、例外から HTTP 応答への変換に集中します。

| 操作    | エンドポイント                | 成功時 | 失敗時                  |
| ----- | ---------------------- | --- | -------------------- |
| 登録    | `POST /products`       | 201 | 入力不正は 400、名前の重複は 409 |
| 取得    | `GET /products/{name}` | 200 | 対象がなければ 404          |
| 故障の再現 | `GET /demo/failure`    | なし  | 想定外の例外で 500          |

故障の再現用エンドポイントは、ローカル演習のために作ります。
演習後に削除し、公開するアプリには含めません。

### DTO と業務例外の作成

以下の Java ファイルは `src/main/java/dev/mikoto2000/springboot/errors` の下に配置します。
Initializr が生成した `@SpringBootApplication` のクラスも、このパッケージに置きます。

```java title="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 を分ける設計も検討してください。

```java title="Product.java"
package dev.mikoto2000.springboot.errors;

public record Product(String name) {}
```

```java title="ProductNotFoundException.java"
package dev.mikoto2000.springboot.errors;

public class ProductNotFoundException extends RuntimeException {
  public ProductNotFoundException() {
    super("Product not found");
  }
}
```

```java title="DuplicateProductException.java"
package dev.mikoto2000.springboot.errors;

public class DuplicateProductException extends RuntimeException {
  public DuplicateProductException() {
    super("Product already exists");
  }
}
```

### Service と Controller の作成

```java title="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` は、存在確認と登録をひとつの操作として行います。
今回は完全に一致する名前を重複とみなします。大文字小文字や前後の空白の正規化は扱いません。

```java title="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);
  }
}
```

```java title="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
./mvnw spring-boot:run
```

別のターミナルで実行します。コマンドは Bash 用です。
PowerShell では `.\mvnw.cmd` と `curl.exe` を使い、JSON はファイルに保存して `--data-binary @request.json` で送れます。

```bash
curl -i http://localhost:8080/products/missing
```

まだ業務例外を HTTP に対応付けていないため、応答は 500 になります。
商品が存在しないという利用者に説明できる失敗を、404 に変換しましょう。

### 業務例外 1 件を 404 に変換する

`ApiExceptionHandler.java` を作成します。`@RestControllerAdvice` はハンドラーを Controller 間で共通化し、`@ExceptionHandler` は処理する例外型を指定します。まず、商品が見つからない場合だけを扱います。

```java title="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, "指定した商品が見つかりません");
  }
}
```

アプリを再起動し、同じリクエストを送ります。

```bash
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` を追加します。

<details>
<summary>ApiExceptionHandler の完成コード</summary>

```java title="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);
  }
}
```

</details>

### 対象なしと重複の確認

アプリを停止し、再起動してから順に実行します。

```bash
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` で、本文は次の形になります。

```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 読み取り失敗の確認

```bash
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 をそのまま返さないようにします。

### 想定外の失敗とログの確認

```bash
curl -i http://localhost:8080/demo/failure
```

故障の再現では、500 と `INTERNAL_ERROR`、`errorId` が返ります。
応答に `Demo internal failure` やスタックトレースは含まれません。
サーバーログには同じ `errorId` と例外のスタックトレースが記録されます。

### 発展: 他の MVC 例外も共通形式にする

基本編はここまでです。405 や 415 も共通形式にする場合は、`ApiExceptionHandler` のクラス内に次のメソッドを追加します。`ResponseEntityExceptionHandler` が受け取ったステータスとヘッダーを `super.handleExceptionInternal(...)` に渡します。
フレームワークが生成した 405 などの `detail` は、共通形式の「リクエストを処理できません」に置き換えます。

```java title="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);
  }
```

アプリを再起動し、未対応のメソッドを送ります。

```bash
curl -i -X PATCH http://localhost:8080/products/Book
```

PATCH は定義していないため、405 と `HTTP_405` が返ります。
`Allow` ヘッダーも確認してください。未対応のメソッドを 500 に変換しないことが重要です。

### MockMvc による契約の検証

この節は発展内容です。直前の節で追加した共通処理も含めて検証します。

`pom.xml` の `dependencies` に、次の依存関係があることを確認します。
JUnit と Mockito の基本は [テスト入門](/Practical-Introduction-to-Spring-Boot/SpringBootテスト入門/テスト入門.md) を参照してください。

```xml
<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 の責務と確認する結果に注目します。実装時には次の完成コードを開いて配置してください。

<details>
<summary>ApiExceptionHandlerTest の完成コード</summary>

```java
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")));
  }
}
```

</details>

実行して、8 件のテストが成功することを確認します。

```bash
./mvnw test
```

このテストは Service をモックにし、例外から HTTP 応答への変換を検証しています。
重複の判定ロジック自体は Service のテストで検証します。

### 練習

1. 商品名の最大長を超えるリクエストを送り、項目エラーを確認する。
2. `Content-Type: text/plain` で登録し、415 のまま共通形式になることを確認する。
3. Service の重複判定と取得を、Spring を起動しない単体テストで検証する。

## 座学で学ぶ例外処理・エラー応答

### 例外を定義する場所と責務

Service は、対象がない、業務上の条件に反するといった失敗を判断します。
HTTP ステータスを Service に持たせず、HTTP への変換を Advice に置くと、他の入口でも業務処理を再利用できます。

今回の業務例外は、利用者に伝える失敗の分類を表します。
例外の `getMessage()` をそのまま応答に使うと、内部の実装情報が契約に混ざります。
応答用の文章とコードはハンドラーで決めましょう。

DB を使う場合、事前に SELECT して重複を確認するだけでは同時登録を防げません。
DB の一意制約でも守り、対象の制約違反を業務上の重複に変換します。
すべての `DataIntegrityViolationException` を重複扱いにすると、外部キー違反なども 409 になってしまいます。
どの制約の失敗か判断できる範囲で変換し、原因の例外は保持します。

### Advice と HTTP ステータス

`@RestControllerAdvice` は、Controller の処理中に伝わった例外を共通処理にまとめます。
`@ExceptionHandler` で扱う例外を指定し、ステータスと本文を返します。
Controller 内のハンドラーや複数の Advice を併用する場合は、適用範囲と優先順位も確認してください。

| ステータス | この教材の意味           | 利用者の対応例          |
| ----- | ----------------- | ---------------- |
| 400   | 入力や JSON が不正      | 入力を修正            |
| 404   | 指定した商品が存在しない      | 対象の選び直し          |
| 409   | 現在の状態と競合          | 別の名前を指定          |
| 405   | 未対応の HTTP メソッド    | 呼び出し方法を修正        |
| 415   | 未対応の Content-Type | 送信形式を修正          |
| 500   | サーバー側の想定外の失敗      | 調査用 ID を添えて問い合わせ |

4xx はリクエストに関係する失敗、5xx はサーバー側の失敗を表す分類です。
再試行できるかは、ステータスだけでは決まりません。
POST の再試行は処理の重複につながる可能性があります。
再試行と重複防止は API ごとに設計します。

### RFC 9457 とエラーコード

Problem Details は、HTTP API のエラーを表す標準形式です。
RFC 9457 が定義する標準メンバーは `type`、`title`、`status`、`detail`、`instance` の 5 つで、すべて省略可能です。
この資料では、共通応答を組み立てるために必要な範囲だけを使います。
Spring の `ProblemDetail` は、RFC 9457 の標準項目と追加項目を扱います。

| 項目         | 役割               | 今回の使い方                   |
| ---------- | ---------------- | ------------------------ |
| `type`     | 問題の種類を表す URI     | 省略（`about:blank` とみなされる） |
| `title`    | 問題の種類の短い説明       | HTTP ステータスの説明            |
| `status`   | HTTP ステータス       | 応答のステータスと一致              |
| `detail`   | 今回の失敗の説明         | 利用者向けの文章                 |
| `instance` | 今回の問題発生を識別する URI | リクエストのパス                 |
| `code`     | アプリ固有の問題の種類      | `PRODUCT_NOT_FOUND` など   |
| `errors`   | 項目ごとの入力エラー       | フィールド名とメッセージ             |
| `errorId`  | 調査用ログとの対応        | 想定外の失敗で生成する UUID         |

追加項目はアプリで決める契約です。
同じ `detail` を返し続けるより、安定した `code` を用意すると表示の翻訳や文章の変更がしやすくなります。
`instance` はこの教材ではパスなので、同じ URL の複数の失敗を一意には識別しません。
500 の個々の発生は `errorId` で区別します。

既存教材の `ValidationErrors` 形式も使えます。
同じ API 内で形式を統一し、すでに利用者がいる API では、応答形式の変更を互換性の変更として扱ってください。
独自の `type` と拡張メンバーの設計は [RFC 9457 エラー返却入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/RFC9457エラー応答入門.md) で扱います。

### JSON の読み取りと入力検証の違い

リクエスト本文を Java オブジェクトへ変換し、その後で `@Valid` の制約を検証します。
JSON の読み取り失敗と制約違反では、発生する段階と例外の種類が異なります。

| 場面                     | 主な例外                              | 今回のコード             |
| ---------------------- | --------------------------------- | ------------------ |
| JSON が壊れている、読み取れない型    | `HttpMessageNotReadableException` | `INVALID_JSON`     |
| DTO の `@Valid` による制約違反 | `MethodArgumentNotValidException` | `VALIDATION_ERROR` |
| パスやクエリの型変換失敗           | `TypeMismatchException` 系         | `HTTP_400`         |

引数へ直接付けた制約の検証には `HandlerMethodValidationException` が使われる場合もあります。
これは入力の違反と戻り値の違反を区別する必要があります。
戻り値の制約違反はサーバー側の問題なので、すべてを 400 に変換しないでください。
今回の Controller は DTO の `@Valid` を使う範囲に絞っています。

### 内部情報と調査用ログ

利用者向けの応答には、SQL、DB の接続情報、クラス名、スタックトレースを含めません。
想定外の例外は固定したメッセージと調査用 ID を返し、サーバーで例外の原因を記録します。
ログの保管先にもアクセス制御が必要です。例外メッセージに機密情報が含まれる場合は、記録する内容を見直します。

想定内の入力不正を毎回 ERROR にすると、調査すべき障害が埋もれます。
今回の業務例外ではログを追加せず、想定外の例外を ERROR としています。
業務監査や頻度の把握が必要なら、アクセスログやメトリクスを組み合わせます。
[ロギング入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/ロギング入門.md) の 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 とログで追跡する。
- 正常系と同様に、エラー応答もテストで契約を確認する。

## 参考資料

- [Spring MVC のエラー応答](https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html)
- [ResponseEntityExceptionHandler](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/mvc/method/annotation/ResponseEntityExceptionHandler.html)
- [Spring MVC の例外ハンドラー](https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-controller/ann-exceptionhandler.html)
- [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html)
