> 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 + RFC 9457 によるエラー返却入門

## 講義の区切り

タスク API の事前準備を済ませた状態で、基本編の目安は 90 分です。終了条件は「同じ 409 でクライアントの判断がどう変わるか、どの入力違反をまとめられるかを説明できる」です。
発展内容は、MockMvc、problem type の登録と契約管理、メディアタイプ交渉です。
準備と前後の章は [学習ガイド](/Practical-Introduction-to-Spring-Boot/introduction.md) で確認できます。

## 概要

HTTP API のエラーを、RFC 9457 が定義する Problem Details の形式で返します。
同じ形式を使いながら、標準メンバーだけで返す方法、独自の問題種別を定義する方法、複数の問題をまとめる方法を扱います。
「どの情報を標準に任せ、どこからアプリの契約にするか」を判断できることを目指します。

## 対象読者

- Spring Boot で REST API を作成できる方
- エラー応答の形式を API の契約として設計したい方
- RFC 9457 の用語と Spring の `ProblemDetail` の対応を知りたい方

## 事前準備と到達目標

Java 21、Maven Wrapper、Spring Boot 4.0 系を使います。
[例外処理・エラー応答入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/例外処理・エラー応答入門.md) の基本部分を前提にします。
Advice による共通化と HTTP ステータスの対応を先に確認しておくと、この資料の差分が分かりやすくなります。

[Spring Initializr](https://start.spring.io/) で Maven / Java / Jar / YAML を選び、新しいプロジェクトを作成します。
パッケージ名は `dev.mikoto2000.springboot.rfc9457` にします。
依存関係は Spring Web と Validation です。講義までに「DTO と業務例外の作成」「Service と Controller の作成」を済ませ、アプリを起動できる状態にします。講義では「パターン1」から進みます。

完了時には、次の 3 つを自分の言葉で説明できることを目指します。

1. 標準メンバーだけで返すとき、何を利用者に伝えられるか。
2. 独自の `type` を定義するとき、何を契約として固定するか。
3. 複数の問題を 1 つの応答にまとめるとき、何に注意するか。

## この資料の構成

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

1. 触って学ぶ RFC 9457 エラー返却: 3 つの返し方を実装し、curl で比べるハンズオン。契約テストは発展。
2. 座学で学ぶ RFC 9457 エラー返却: 仕様の用語、`type` の設計、複数問題の扱いを整理する座学。

| 触って学ぶ（ハンズオン）            | 座学で学ぶ（理論）                                        |
| ----------------------- | ------------------------------------------------ |
| パターン1: 標準メンバーだけで返す      | RFC 9457 の位置づけと標準メンバー                            |
| パターン2: 独自の `type` を定義する | `type` の設計と problem type の登録                     |
| パターン3: 複数の問題をまとめる       | 複数問題の扱いと拡張メンバー                                   |
| 応答と Content-Type の確認    | `application/problem+json` と content negotiation |
| MockMvc による契約の検証（発展）    | 契約としてのエラー応答とセキュリティ                               |

## 触って学ぶ RFC 9457 エラー返却

### 題材とするタスク API

小さなタスク管理 API を使います。3 つの失敗場面が、そのまま 3 つの返し方に対応します。

| 場面               | 失敗  | 返し方                       |
| ---------------- | --- | ------------------------- |
| 存在しないタスクを取得する    | 404 | パターン1: 標準メンバーだけで返す        |
| 完了済みタスクをもう一度完了する | 409 | パターン2: 独自の `type` を定義して返す |
| 入力が不正            | 400 | パターン3: 複数の問題を 1 つにまとめて返す  |

### DTO と業務例外の作成（事前準備）

`src/main/java/dev/mikoto2000/springboot/rfc9457/` に次のファイルを作成します。

```java title="TaskRequest.java"
package dev.mikoto2000.springboot.rfc9457;

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

public record TaskRequest(
    @NotBlank(message = "title は必須です")
    @Size(max = 50, message = "title は 50 文字以内です")
    String title,
    @NotBlank(message = "assignee は必須です")
    String assignee) {}
```

```java title="Task.java"
package dev.mikoto2000.springboot.rfc9457;

public record Task(String id, String title, String assignee, boolean completed) {}
```

```java title="TaskNotFoundException.java"
package dev.mikoto2000.springboot.rfc9457;

public class TaskNotFoundException extends RuntimeException {
  public TaskNotFoundException(String id) {
    super(id);
  }
}
```

```java title="TaskAlreadyCompletedException.java"
package dev.mikoto2000.springboot.rfc9457;

public class TaskAlreadyCompletedException extends RuntimeException {
  public TaskAlreadyCompletedException(String id) {
    super(id);
  }
}
```

例外は失敗の意味だけを持ちます。HTTP ステータスや応答の文章は、次のハンドラーで決めます。

### Service と Controller の作成（事前準備）

```java title="TaskService.java"
package dev.mikoto2000.springboot.rfc9457;

import java.util.concurrent.ConcurrentHashMap;
import java.util.concurrent.ConcurrentMap;
import java.util.concurrent.atomic.AtomicLong;
import org.springframework.stereotype.Service;

@Service
public class TaskService {
  private final ConcurrentMap<String, Task> tasks = new ConcurrentHashMap<>();
  private final AtomicLong lastTaskId = new AtomicLong(2);

  public TaskService() {
    tasks.put("t1", new Task("t1", "資料を読む", "alice", false));
    tasks.put("t2", new Task("t2", "レビューする", "bob", true));
  }

  public Task find(String id) {
    Task task = tasks.get(id);
    if (task == null) {
      throw new TaskNotFoundException(id);
    }
    return task;
  }

  public Task create(TaskRequest request) {
    String id = "t" + lastTaskId.incrementAndGet();
    Task task = new Task(id, request.title(), request.assignee(), false);
    tasks.put(id, task);
    return task;
  }

  public Task complete(String id) {
    return tasks.compute(id, (key, task) -> {
      if (task == null) {
        throw new TaskNotFoundException(key);
      }
      if (task.completed()) {
        throw new TaskAlreadyCompletedException(key);
      }
      return new Task(task.id(), task.title(), task.assignee(), true);
    });
  }
}
```

`ConcurrentHashMap.compute` の中で、同じ ID の状態確認と更新を原子的に行います。
同じタスクへの完了リクエストが重なっても、成功するのは 1 件です。それ以外は完了済みの例外となり、パターン2で 409 に変換します。
存在しないタスクでは、更新前と同じく未検出の例外を返します。

```java title="TaskController.java"
package dev.mikoto2000.springboot.rfc9457;

import jakarta.validation.Valid;
import java.net.URI;
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;

@RestController
@RequestMapping("/tasks")
public class TaskController {
  private final TaskService service;

  public TaskController(TaskService service) {
    this.service = service;
  }

  @GetMapping("/{id}")
  public Task get(@PathVariable String id) {
    return service.find(id);
  }

  @PostMapping
  public ResponseEntity<Task> create(@Valid @RequestBody TaskRequest request) {
    Task task = service.create(request);
    return ResponseEntity.created(URI.create("/tasks/" + task.id())).body(task);
  }

  @PostMapping("/{id}/complete")
  public Task complete(@PathVariable String id) {
    return service.complete(id);
  }
}
```

この時点ではハンドラーがないため、`TaskNotFoundException` は 500 になります。
アプリを起動し、別のターミナルから `curl -i http://localhost:8080/tasks/t1` を実行して 200 が返れば事前準備は完了です。講義では、次のパターンから失敗の意味に合った応答へ変換します。

### パターン1: 標準メンバーだけで返す

まず、RFC 9457 が定義する標準メンバーだけを使います。
アプリ固有の項目を足さず、HTTP ステータスの意味に任せる返し方です。

```java title="Pattern1ExceptionHandler.java"
package dev.mikoto2000.springboot.rfc9457;

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 Pattern1ExceptionHandler {
  @ExceptionHandler(TaskNotFoundException.class)
  public ProblemDetail notFound(TaskNotFoundException ex) {
    return ProblemDetail.forStatusAndDetail(
        HttpStatus.NOT_FOUND, "指定したタスクが見つかりません");
  }
}
```

`@ExceptionHandler` から `ProblemDetail` を返すと、`instance` はリクエストのパスで初期化されます。
`title` は、よく知られたステータスなら `HttpStatus` の理由句から設定されます。

アプリを起動して確認します。

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

404 と `Content-Type: application/problem+json` が返り、本文は次の形になります。

```json
{
  "title": "Not Found",
  "status": 404,
  "detail": "指定したタスクが見つかりません",
  "instance": "/tasks/missing"
}
```

`type` がないことに注目してください。
RFC 9457 では、`type` がない場合は `about:blank` とみなします。
`about:blank` は「HTTP ステータス以上の意味を持たない」ことを表します。

Spring Framework 7 では `ProblemDetail` の `type` は既定で設定されません。
この教材の標準構成では、Spring の Jackson 用ミックスインが未設定の `type` を JSON 応答から省略します。
Spring Framework 6.2 以前は `"type": "about:blank"` が出力されていました。
どちらも RFC 9457 に適合しますが、JSON の見た目は変わります。

このパターンの利点は、契約が小さいことです。
利用者は HTTP ステータスと `detail` だけを見ればよく、独自の語彙を覚える必要がありません。

この例では `forStatusAndDetail` で説明を指定します。標準構成では、`forStatus` で生成して `detail` を設定しない場合、JSON 応答から `detail` が省略されます。
一方で、同じ 404 でも「タスクがない」のか「別の資源がない」のかを機械的に区別できません。

### パターン2: 独自の `type` を定義する

次に、アプリ固有の問題種別を `type` で表します。
同じ 409 でも、何が競合したのかを機械的に区別できるようにします。

まず、完了済みタスクの 409 を標準メンバーだけで返してみます。`Pattern2ExceptionHandler.java` を作成します。

```java title="Pattern2ExceptionHandler.java（比較用）"
package dev.mikoto2000.springboot.rfc9457;

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 Pattern2ExceptionHandler {
  @ExceptionHandler(TaskAlreadyCompletedException.class)
  public ProblemDetail alreadyCompleted(TaskAlreadyCompletedException ex) {
    return ProblemDetail.forStatusAndDetail(
        HttpStatus.CONFLICT, "このタスクはすでに完了しています");
  }
}
```

アプリを再起動し、次を実行します。

```bash
curl -i -X POST http://localhost:8080/tasks/t2/complete
```

409 で `type` が省略され、クライアントは HTTP ステータスから競合と判断できます。将来、同じ 409 に別の競合が加わったとき、完了済みの場合だけ画面を更新するには何を見ればよいでしょうか。

同じファイルを次の完成版で置き換え、再起動後に同じリクエストを送ります。HTTP ステータスは 409 のままで、`type` を見れば完了済みの場合を識別できます。

```java title="Pattern2ExceptionHandler.java"
package dev.mikoto2000.springboot.rfc9457;

import java.net.URI;
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 Pattern2ExceptionHandler {
  private static final URI TASK_ALREADY_COMPLETED =
      URI.create("https://example.com/problems/task-already-completed");

  @ExceptionHandler(TaskAlreadyCompletedException.class)
  public ProblemDetail alreadyCompleted(TaskAlreadyCompletedException ex) {
    ProblemDetail body = ProblemDetail.forStatusAndDetail(
        HttpStatus.CONFLICT, "このタスクはすでに完了しています");
    body.setType(TASK_ALREADY_COMPLETED);
    body.setTitle("Task Already Completed");
    return body;
  }
}
```

`type` は問題の種類を表す URI 参照です。
同じ種類の失敗には、同じ `type` を返します。
`title` は種類の短い説明で、発生ごとに変えません。
個々の発生についての説明は `detail` に置きます。`title` はローカライズで変わることがあるため、クライアントが種別で分岐するときは `type` を使います。

```bash
curl -i -X POST http://localhost:8080/tasks/t2/complete
```

409 と次の本文が返ります。

```json
{
  "type": "https://example.com/problems/task-already-completed",
  "title": "Task Already Completed",
  "status": 409,
  "detail": "このタスクはすでに完了しています",
  "instance": "/tasks/t2/complete"
}
```

`type` の URI は、自組織が管理する範囲のものを使います。
RFC 9457 は、問題の解決方法を説明する文書へ解決できることを推奨しています。
ただし、解決できない URI を使う場合の指針も示されています。
社内 API で文書を公開しない場合は、一意で安定していれば解決不能でも運用できます。
その場合も、`type` の値は勝手に変えないでください。

このパターンの利点は、利用者が `type` で分岐できることです。
`detail` の文章を解析する必要がありません。
一方で、`type` の一覧を API の契約として管理する必要があります。

### パターン3: 複数の問題をまとめる

入力不正では、複数の項目が同時に違反します。
この場合は、1 つの入力検証エラーを表し、個々の違反を `errors` にまとめます。
この例で `errors` に含めるのは、`getFieldErrors()` が返す項目単位の違反です。DTO 全体に対する違反をまとめる場合は、`getGlobalErrors()` の結果も扱います。

```java title="Pattern3ExceptionHandler.java"
package dev.mikoto2000.springboot.rfc9457;

import java.net.URI;
import java.util.List;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class Pattern3ExceptionHandler {
  private static final URI INVALID_INPUT =
      URI.create("https://example.com/problems/invalid-task-input");

  public record FieldProblem(String field, String message) {}

  @ExceptionHandler(MethodArgumentNotValidException.class)
  public ProblemDetail invalidInput(MethodArgumentNotValidException ex) {
    ProblemDetail body = ProblemDetail.forStatusAndDetail(
        HttpStatus.BAD_REQUEST, "入力内容を確認してください");
    body.setType(INVALID_INPUT);
    body.setTitle("Invalid Task Input");
    List<FieldProblem> errors = ex.getBindingResult().getFieldErrors().stream()
        .map(error -> new FieldProblem(error.getField(), error.getDefaultMessage()))
        .toList();
    body.setProperty("errors", errors);
    return body;
  }
}
```

`errors` は RFC 9457 の標準メンバーではなく、拡張メンバーです。
拡張メンバーは、problem type の定義の一部としてアプリが決めます。
この API では `errors` の各要素を `field` と `message` にします。RFC 9457 の例は `pointer` と `detail` を使っており、どちらの形も各 API が定める契約です。

```bash
curl -i -X POST http://localhost:8080/tasks \
  -H 'Content-Type: application/json' \
  -d '{"title":"","assignee":""}'
```

400 と次の本文が返ります。

```json
{
  "type": "https://example.com/problems/invalid-task-input",
  "title": "Invalid Task Input",
  "status": 400,
  "detail": "入力内容を確認してください",
  "instance": "/tasks",
  "errors": [
    { "field": "title", "message": "title は必須です" },
    { "field": "assignee", "message": "assignee は必須です" }
  ]
}
```

ここで注意したいのは、まとめてよい範囲です。
同じ種類の問題が複数ある場合は、1 つの応答にまとめられます。
一方、種類の異なる問題が同時に起きた場合は、最も重要または緊急なものを 1 つ返すことを推奨しています。
種類の違う問題を無理に 1 つの応答へ詰め込むと、HTTP の意味と対応しにくくなります。

入力検証の複数違反は、すべて「入力が不正」という同じ種類です。
そのため `errors` にまとめるのは自然です。
「入力が不正」と「対象が存在しない」が同時に起きた場合は、どちらを返すかを決めてください。

### 3 つのパターンの比較

| 観点        | パターン1             | パターン2   | パターン3             |
| --------- | ----------------- | ------- | ----------------- |
| 独自 `type` | なし（`about:blank`） | あり      | あり                |
| 拡張メンバー    | なし                | なし      | `errors`          |
| 機械的な分岐    | ステータスのみ           | `type`  | `type` と `errors` |
| 契約の大きさ    | 小さい               | 中程度     | 中程度               |
| 主な用途      | 一般的な失敗            | 業務固有の失敗 | 入力検証              |

この教材ではパターンを分けて確認するため、Advice を 3 つに分けています。
実際のアプリでは 1 つの Advice にまとめてかまいません。
その場合も、問題種別ごとに `type` と拡張メンバーを一貫させてください。

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

この節は発展です。基本編では curl の結果を見て、3 つの形式でクライアントに伝わる情報を説明します。

`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/rfc9457/Rfc9457ContractTest.java` に配置します。

```java title="Rfc9457ContractTest.java"
package dev.mikoto2000.springboot.rfc9457;

import static org.hamcrest.Matchers.hasSize;
import static org.mockito.ArgumentMatchers.any;
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.post;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.content;
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(TaskController.class)
@Import({Pattern1ExceptionHandler.class, Pattern2ExceptionHandler.class,
    Pattern3ExceptionHandler.class})
class Rfc9457ContractTest {
  @Autowired
  MockMvc mvc;

  @MockitoBean
  TaskService service;

  @Test
  void missingTaskReturns404WithStandardMembersOnly() throws Exception {
    when(service.find("missing")).thenThrow(new TaskNotFoundException("missing"));
    mvc.perform(get("/tasks/missing"))
        .andExpect(status().isNotFound())
        .andExpect(content().contentTypeCompatibleWith(MediaType.APPLICATION_PROBLEM_JSON))
        .andExpect(jsonPath("$.status").value(404))
        .andExpect(jsonPath("$.title").value("Not Found"))
        .andExpect(jsonPath("$.instance").value("/tasks/missing"))
        .andExpect(jsonPath("$.type").doesNotExist());
  }

  @Test
  void alreadyCompletedReturns409WithProblemType() throws Exception {
    when(service.complete("t2")).thenThrow(new TaskAlreadyCompletedException("t2"));
    mvc.perform(post("/tasks/t2/complete"))
        .andExpect(status().isConflict())
        .andExpect(jsonPath("$.type")
            .value("https://example.com/problems/task-already-completed"))
        .andExpect(jsonPath("$.title").value("Task Already Completed"))
        .andExpect(jsonPath("$.status").value(409));
  }

  @Test
  void invalidInputReturnsErrorsExtension() throws Exception {
    mvc.perform(post("/tasks").contentType(MediaType.APPLICATION_JSON)
        .content("{\"title\":\"\",\"assignee\":\"\"}"))
        .andExpect(status().isBadRequest())
        .andExpect(jsonPath("$.status").value(400))
        .andExpect(jsonPath("$.type").value("https://example.com/problems/invalid-task-input"))
        .andExpect(jsonPath("$.errors", hasSize(2)))
        .andExpect(jsonPath("$.errors[0].field").exists())
        .andExpect(jsonPath("$.errors[0].message").exists());
  }
}
```

`$.type` の検証は、使う Spring Framework の版で変わります。
Spring Framework 7 では `type` が省略されるため、存在しないことを検証します。
Spring Framework 6.2 以前では `about:blank` が出力されるため、その値を検証してください。

`errors` の順序は保証されません。
件数と、各要素に必要な項目があることを確認します。
メッセージの完全な文章を成功条件にしないでください。
ロケールや制約の変更で変わります。

### 練習

1. パターン2 の `type` を、存在しないタスクの 404 にも付けてみましょう。
   `about:blank` を使う場合と、独自の種類を使う場合で、利用者の分岐がどう変わるかを比べてください。
2. パターン3 の `errors` に、拒否した値そのものを含めるべきか考えてみましょう。
   入力値をそのまま返すと、ログや画面に機密情報を残すおそれがある。
3. 同じ 409 でも「すでに完了」と「名前の重複」が起きた場合、どちらを返すかを決めてください。

## 座学で学ぶ RFC 9457 エラー返却

### RFC 9457 の位置づけと標準メンバー

RFC 9457 は「Problem Details for HTTP APIs」という仕様です。
2023 年 7 月に公開され、RFC 7807 を置き換えました。
HTTP API のエラーを表す共通形式を定義し、API ごとに新しい形式を作らなくて済むようにします。

仕様が定義する標準メンバーは 5 つです。
すべて省略可能で、必須の項目はありません。

| メンバー       | 型      | 役割               |
| ---------- | ------ | ---------------- |
| `type`     | URI 参照 | 問題の種類を識別する       |
| `title`    | 文字列    | 問題の種類の短い説明       |
| `status`   | 整数     | この発生の HTTP ステータス |
| `detail`   | 文字列    | この発生の説明          |
| `instance` | URI 参照 | この発生を識別する URI    |

`type` と `title` は「種類」の情報です。
同じ種類の失敗では、同じ値を使います。
`status`、`detail`、`instance` は「今回の発生」の情報です。
個々の発生についての情報で、別の発生でも同じ値を取ることがあります。たとえば、同じ種類の競合が繰り返されても `status` は 409 です。

この区別が設計の出発点になります。
`detail` に種類の情報を詰め込むと、利用者は文章を解析する必要が出てきます。
種類は `type` で表し、`detail` は人間向けの補足に留めるのが基本です。

`type` を省略した場合は `about:blank` とみなされます。
`about:blank` は「HTTP ステータス以上の意味を持たない」ことを表します。
この場合、`title` は HTTP ステータスの理由句と同じにすることが推奨されています。

### `type` の設計

`type` は URI 参照です。
可能なら絶対 URI を使います。相対 URI は応答の基準 URI から解決されるため、同じ文字列でも異なる種別として解釈されることがあります。
重要なのは、同じ問題には同じ値を使い、値を勝手に変えないことです。

RFC 9457 は、`type` の URI が問題の解決方法を説明する文書へ解決できることを推奨しています。
ただし、解決できない URI を使う場合の指針も示しています。
社内 API のように文書を公開しない場合でも、一意で安定していれば運用できます。

`type` を設計するときは、次の点を決めておきます。

- どの失敗を 1 つの種類としてまとめるか
- 種類ごとに、どの拡張メンバーを伴うか
- `type` の値を変更する場合の互換性の扱い

`type` の一覧は API の契約です。
利用者が `type` で分岐するなら、値を追加しても既存の値は変えないでください。

#### 発展: problem type の登録

IANA の「HTTP Problem Types」レジストリには `about:blank` などが登録されています。広く使われる種類を設計するときは、登録済みの種別も確認します。

### 複数問題の扱いと拡張メンバー

RFC 9457 は、複数の問題をどう扱うかについても指針を示しています。
同じ種類の問題が複数ある場合は、1 つの応答にまとめられます。
入力検証の複数違反がこれにあたります。

一方、種類の異なる問題が同時に起きた場合は、最も重要または緊急なものを 1 つ返すことが推奨されています。
複数の異なる種類を 1 つの応答に詰め込む「batch」形式は、HTTP の意味と対応しにくいとされています。

拡張メンバーは、problem type の定義の一部として追加します。
標準メンバーと同じ名前を使うと意味が衝突するため、避けてください。
RFC 9457 自身も、入力検証の例で `errors` という拡張を使っています。

拡張メンバーを設計するときは、次を決めておきます。

- 名前と型
- どの problem type で伴うか
- 省略可能か、必須か
- 値を追加した場合の互換性

拡張メンバーはアプリの契約です。
標準メンバーではないため、利用者には API の文書で伝える必要があります。

### `application/problem+json` と content negotiation（発展）

Problem Details を JSON で返すときのメディアタイプは `application/problem+json` です。
XML の場合は `application/problem+xml` です。

Spring Framework では、Jackson の JSON コーデックが `ProblemDetail` に対して `application/problem+json` を生成可能なメディアタイプとして扱います。
そのため、content negotiation で優先されます。

利用者側は、本文を読む前に Content-Type を確認してください。
JSON はどのオブジェクトも Problem Details の形に見えることがあります。
Content-Type が `application/problem+json` であることが、Problem Details であることの手がかりになります。

`Accept` ヘッダーで `application/problem+json` を指定しない場合でも、エラー応答はこの形式で返ることがあります。
クライアントの実装では、エラー応答の Content-Type を決め打ちしないでください。

### 契約としてのエラー応答とセキュリティ

エラー応答は API の契約です。
正常系と同じように、テストで確認します。

検証する項目は、ステータス、Content-Type、標準メンバー、拡張メンバーです。
`detail` の完全な文章や `instance` の具体的な値に、依存しすぎないでください。

セキュリティでは、応答に含める情報を絞ります。
`detail` に SQL、接続情報、クラス名、スタックトレースを含めないでください。
拡張メンバーも同じです。
入力値をそのまま返すと、機密情報が応答やログに残る可能性があります。

想定外の失敗では、固定した `detail` と調査用の ID を返します。
原因はサーバーのログに記録し、応答とは分けます。
この考え方は [例外処理・エラー応答入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/例外処理・エラー応答入門.md) で扱っています。

`type` の URI を外部に公開する場合、その文書に内部情報を書かないようにします。
問題の解決方法を説明する文書は、利用者が読む前提で書きます。

### 既存資料との使い分け

[バリデーション入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/バリデーション入門.md) は項目別の `errors`、[バリデーションテスト](/Practical-Introduction-to-Spring-Boot/SpringBootテスト入門/バリデーションテスト.md) は `code`・`message`・`errors` を持つ独自 DTO を使います。この章と例外処理の章では、RFC 9457 の標準メンバーを持つ `ProblemDetail` を使います。

[例外処理・エラー応答入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/例外処理・エラー応答入門.md) は、Advice で例外を HTTP 応答へ変換する実装が中心です。
この資料は、その応答を RFC 9457 の仕様に沿ってどう設計するかが中心です。

| 観点          | 例外処理・エラー応答入門            | この資料                       |
| ----------- | ----------------------- | -------------------------- |
| 主な関心        | 例外から応答への変換              | 応答形式の設計                    |
| Advice の作り方 | 詳しく扱う                   | 前提とする                      |
| 標準メンバー      | 一覧と使い方を確認               | 種類と発生の区別を設計                |
| `type`      | 省略して `about:blank` とみなす | 独自の種類を定義する                 |
| 問題種別の識別子    | アプリ固有の `code`           | 独自 `type` を定義した応答では、その URI |
| 複数問題        | `errors` の実装            | まとめてよい範囲を判断                |

独自の problem type を定義したら、クライアントは `type` の URI を問題種別の主識別子として使います。既存クライアントが `code` に依存する場合は、対応する値を拡張メンバーとして返し続けられます。

まず実装を学びたい場合は [例外処理・エラー応答入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/例外処理・エラー応答入門.md) から読んでください。
応答形式を設計したい場合は、この資料の座学から読むと判断材料が揃います。

## まとめ

- RFC 9457 は HTTP API のエラー形式を定義し、RFC 7807 を置き換えた。
- 標準メンバーは `type`、`title`、`status`、`detail`、`instance` の 5 つで、すべて省略可能。
- `type` と `title` は種類、`status`、`detail`、`instance` は発生の情報。
- `type` を省略すると `about:blank` とみなされ、HTTP ステータス以上の意味を持たない。
- 同じ種類の複数問題はまとめられ、異なる種類は最も重要な 1 つを返すことが推奨される。
- 拡張メンバーは problem type の定義の一部として、アプリの契約になる。
- 応答は `application/problem+json` で返し、Content-Type を確認して扱う。
- エラー応答も契約としてテストし、内部情報を含めない。

## 参考資料

- [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html)
- [Spring MVC のエラー応答](https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html)
- [ProblemDetail](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/http/ProblemDetail.html)
- [例外処理・エラー応答入門](/Practical-Introduction-to-Spring-Boot/SpringBoot入門/例外処理・エラー応答入門.md)
