
# @ExceptionHandler

`@ExceptionHandler()` は、例外を HTTP レスポンスに変換するメソッドを示します。コントローラーに付けた場合はそのコントローラーのメソッドのエラーを、[@ControllerAdvice](controller-advice.md) Bean に付けた場合はすべてのコントローラーのエラーを扱います。

## 使う理由

ハンドラーがない場合、コントローラーメソッドが投げた例外は 500 になるか、`ResponseStatusException` のような `ErrorResponse` のステータスになります。サービスは通常、HTTP について何も知らないドメインの例外 (`BookNotFoundException`、`StateError`) を投げます。例外ハンドラーは、それらを一か所で適切な応答に対応付けます。`BookNotFoundException` は 404 に、競合は役に立つメッセージ付きの 409 になります。スターター自身の応答、たとえばバリデーションエラーの形を置き換えることもできます。

## 例

```dart
import 'dart:async';

import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

class Book {
  const Book({required this.isbn, required this.title});

  final String isbn;
  final String title;
}

class BookNotFoundException implements Exception {
  BookNotFoundException(this.isbn);

  final String isbn;
}

@RestController()
@RequestMapping('/api/books')
class BookController {
  @GetMapping('/{isbn}')
  Book find(@PathVariable() String isbn) => throw BookNotFoundException(isbn);

  @PostMapping('/{isbn}/reserve')
  void reserve(@PathVariable() String isbn) => throw StateError('Already reserved');

  @GetMapping('/{isbn}/price')
  Future<double> price(@PathVariable() String isbn) =>
      Future.delayed(const Duration(seconds: 1), () => throw TimeoutException('slow'));

  // パラメーターの型が例外を選ぶ (サブタイプも含む)。リクエストは
  // 省略できる。problem には ISBN を入れる。
  @ExceptionHandler()
  @ResponseStatus(HttpStatus.notFound)
  ProblemDetail notFound(BookNotFoundException e, ServerHttpRequest request) =>
      ProblemDetail.forStatusAndDetail(HttpStatus.notFound, 'No book ${e.isbn}')
        ..setProperty('isbn', e.isbn);

  // 応答に独自のステータスとヘッダーが必要なときは ResponseEntity を返す。
  @ExceptionHandler()
  ResponseEntity<ProblemDetail> conflict(StateError e) =>
      ResponseEntity.status(HttpStatus.conflict)
          .header('Retry-After', ['60'])
          .body(ProblemDetail.forStatusAndDetail(HttpStatus.conflict, e.message));

  // 列挙した型は実行時の型と厳密に一致させる。ステータス以外に伝えることはない。
  @ExceptionHandler([TimeoutException])
  @ResponseStatus(HttpStatus.gatewayTimeout)
  void timeout() {}
}
```

すべてのコントローラーについて、スターターのバリデーションの応答を置き換える例です。

```dart
@RestControllerAdvice()
class ValidationErrors {
  // {"isbn": "must not be blank", "title": "must not be blank"}
  @ExceptionHandler()
  @ResponseStatus(HttpStatus.badRequest)
  Map<String, String?> invalid(MethodArgumentNotValidException e) => {
    for (final error in e.bindingResult.fieldErrors())
      error.field: error.defaultMessage,
  };
}
```

## パラメーター

| 名前 | 型 | デフォルト | 意味 |
|---|---|---|---|
| `value` (位置引数) | `List<Type>` | `const []` | 扱う例外の型。実行時の型と厳密に一致させる。サブタイプは一致しない。空の場合は例外パラメーターの型で決まる。 |

## メソッドのパラメーター

ハンドラーメソッドは、任意の順で次のものを受け取れます。

| パラメーター | 値 |
|---|---|
| 例外 (以下以外の型を持つ最初のパラメーター) | エラー。その型で、メソッドが扱うエラーが決まる |
| `ServerHttpRequest` | リクエスト |
| `ServerHttpResponse` | レスポンス |
| `HttpHeaders` | リクエストヘッダー |

それ以外のパラメーターがあると起動が止まります。例外パラメーターも `value` の型も持たないハンドラーも同様です ([起動時のチェック](../controllers/startup-checks.md) を参照)。バインディングのアノテーション (`@RequestParam`、`@PathVariable` など) はハンドラーのパラメーターでは読まれません。代わりにリクエストを受け取ってください。

## 戻り値

メソッドはコントローラーメソッドと同じものを返し、同じように書き出されます ([戻り値](../controllers/results.md) を参照)。`async` にもできます。

| 戻り値 | 応答 |
|---|---|
| `ProblemDetail` | problem のステータス、または `@ResponseStatus` の `application/problem+json` |
| `ResponseEntity<T>` | そのステータス、ヘッダー、ボディ |
| `ErrorResponse` (`ResponseStatusException` など) | そのステータス、ヘッダー、problem |
| オブジェクト、`Map`、`List`、`String` | ボディ。ステータスは `@ResponseStatus`、なければ **200** |
| `void`、`null` | `@ResponseStatus` のステータス (なければ 200)。ボディなし |

オブジェクトを返すハンドラーや何も返さないハンドラーには `@ResponseStatus` を付けてください (または `ResponseEntity` を返してください)。付けないと、エラーが 200 で応答されます。

## どのハンドラーが応答するか

1. **コントローラー自身のハンドラー** が先です。対象は、そのメソッドの一つがリクエストを処理している間に投げられたエラーです。メソッド自身、パラメーターのバインディング (値の欠落、変換、`@Valid` の違反)、インターセプター、レスポンスのコミット前の戻り値の書き出しが含まれます。
2. **次にアドバイス Bean** が `@Order` 順に試されます。コントローラーに適用され、そのエラーのハンドラーを持つ最初の [@ControllerAdvice](controller-advice.md) Bean が応答します。後の Bean により具体的なハンドラーがあってもそうなります。
3. **一つのコントローラーまたは Bean の中では**、最も具体的なハンドラーが選ばれます。`@ExceptionHandler([...])` にエラーの実行時の型をそのまま列挙したハンドラー、なければ例外パラメーターの型が最も具体的なハンドラーです (`Error` より `ArgumentError` が先)。

`value` と例外パラメーターの両方を持つハンドラーは、列挙した型のうち、パラメーターの型が受け入れるインスタンスだけを扱います。

ルール:

- **メソッドが選ばれる前のエラー** (ルーターの 404、405、406、415、ヘッダー条件を満たさない場合の 400) と、他のハンドラーマッピングのエラー (WebSocket ハンドシェイク) は、アドバイスのハンドラーにだけ届きます。それも、一部のコントローラーに絞り込まれていないアドバイスだけです。
- **フィルターが投げたエラー** はどのハンドラーにも届きません。
- **`server.request-timeout` の 503** はどのハンドラーにも届きません。応答した時点でハンドラーはまだ実行中だからです。
- **例外を投げたハンドラー** は警告としてログに記録され (`The @ExceptionHandler ... failed handling ...`)、元のエラーは次のステップに進みます ([エラー](index.md) を参照)。
- **コミット済みのレスポンス** にはハンドラーは使われません。ステータスとヘッダーが送られた後は、接続が切断されます。
- **`HandlerInterceptor.afterCompletion`** は、ハンドラーが応答した場合でも例外を受け取ります。
- **組み込みの例外** も他の例外と同じように扱えます。`NoHandlerFoundException` (アドバイスで)、`MissingRequestValueException`、`MethodArgumentTypeMismatchException`、`HttpMessageNotReadableException` (`message` が理由を示す)、`MethodArgumentNotValidException` (`bindingResult` が違反を持つ)、その他 [エラー](index.md) にあるものです。

## Spring (Java) との対応

```java
@ExceptionHandler
@ResponseStatus(HttpStatus.NOT_FOUND)
ProblemDetail notFound(BookNotFoundException e) { ... }

@ExceptionHandler(TimeoutException.class)
@ResponseStatus(HttpStatus.GATEWAY_TIMEOUT)
void timeout() { }
```

重要な違い:

- **`@ExceptionHandler([types])` は実行時の型と厳密に一致させます。** Dart では、ある `Type` が別の型のサブタイプかどうかを調べられないためです。サブタイプは例外パラメーターの型で一致させます (`@ExceptionHandler() void on(StateError e)`)。
- **パラメーター** は、例外、リクエスト、レスポンス、ヘッダーに限られます。Spring は `WebRequest`、`Locale`、`Model` なども受け取ります。
- **`@ResponseStatus` のないハンドラー** がオブジェクトを返すと、Spring と同じく 200 で応答します。
- **より多くの誤りで起動が止まります。** 未知のパラメーター、例外の型のないハンドラーなどです。

## 関連項目

- [@ControllerAdvice](controller-advice.md)
- [ProblemDetail](problem-detail.md)
- [HandlerExceptionResolver](handler-exception-resolver.md)
- [エラー](index.md)
