
# HandlerExceptionResolver

`HandlerExceptionResolver` Bean は、どの `@ExceptionHandler` メソッドも扱わないエラーを応答に変換します。`ErrorResponse` (ステータス、ヘッダー、`ProblemDetail`) を返すか、エラーを次に渡すために `null` を返します。

## 使う理由

ライブラリが、アプリケーションにアドバイスを書かせずに自身の例外を HTTP に対応付けるための方法です。たとえばデータスターターは、バージョンの競合に 500 ではなく 409 で応答します。アプリケーション自身の `@ExceptionHandler` メソッドが常に先に試されるので、アプリケーションはこれらのエラーのどれにでも独自の方法で応答できます。

ハンドラーメソッドより、コードとして書いたほうが簡単なルールのために、アプリケーションが使うこともできます。表で対応付ける例外の一群や、リクエストによって変わる対応付けなどです。

## 例

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

class RoomTakenException implements Exception {}

class RoomClosedException implements Exception {
  RoomClosedException(this.until);

  final DateTime until;
}

// 部屋が埋まっていて失敗した予約には 409 で応答する。
@Component()
@Order(10)
class RoomTakenResolver implements HandlerExceptionResolver {
  @override
  ErrorResponse? resolveException(
    ServerHttpRequest request,
    Object error, {
    HandlerMethod? handler,
  }) => error is RoomTakenException
      ? ResponseStatusException(HttpStatus.conflict, 'The room is taken')
      : null;
}

// 閉鎖中の部屋: Retry-After 付きの 503。problem に日付を入れる。
@Component()
@Order(20)
class RoomClosedResolver implements HandlerExceptionResolver {
  @override
  Future<ErrorResponse?> resolveException(
    ServerHttpRequest request,
    Object error, {
    HandlerMethod? handler,
  }) async {
    if (error is! RoomClosedException) {
      return null;
    }
    return ErrorResponseException(
      HttpStatus.serviceUnavailable,
      headers: HttpHeaders()
        ..set(HttpHeaders.retryAfterHeader, HttpHeaders.formatDate(error.until)),
      body: ProblemDetail.forStatusAndDetail(
        HttpStatus.serviceUnavailable,
        'The room is closed',
      )..setProperty('until', error.until.toIso8601String()),
    );
  }
}
```

## インターフェース

```dart
abstract interface class HandlerExceptionResolver {
  FutureOr<ErrorResponse?> resolveException(
    ServerHttpRequest request,
    Object error, {
    HandlerMethod? handler,
  });
}
```

| パラメーター | 型 | 意味 |
|---|---|---|
| `request` | `ServerHttpRequest` | 失敗したリクエスト。 |
| `error` | `Object` | エラー。 |
| `handler` | `HandlerMethod?` | リクエストを処理していたコントローラーメソッド (`description`、`beanName`、`annotation<A>()`)。メソッドが選ばれる前のエラーなら `null`。 |
| 戻り値 | `FutureOr<ErrorResponse?>` | 応答。このリゾルバーが扱わないエラーなら `null`。非同期でもよい。 |

## ルール

- **Bean として宣言します** (`@Component()` または `@Bean` メソッド)。複数ある場合は `@Order` で順位を付けます。小さい値が先に実行されます。
- **問い合わせのタイミング。** コントローラーとアドバイス Bean の `@ExceptionHandler` メソッドの後、デフォルトの 500 の前です。リゾルバーは `@Order` 順に問い合わせられ、最初に応答を返したものが採用されます。`null` はエラーを次のリゾルバーに渡します。
- **見ないもの。** すでに `ErrorResponse` であるエラー (`ResponseStatusException`、ルーターの 404、405、406、415、バリデーションエラー) は見ません。そのエラーは自身の応答を持っているからです。Spring でも `ResponseStatusExceptionResolver` が先に応答します。`WebFilter` が投げたエラーも飛ばします。見るのは、コントローラー、そのインターセプター、引数のバインディング、そして他のハンドラーマッピングのエラーです。
- **応答の書き出し** は、投げられた `ErrorResponse` と同じです。ステータス、ヘッダー (`Vary` は CORS のものなど、すでにある名前に追加される)、そして problem を `application/problem+json` として書きます。problem の `instance` は、設定されていなければリクエストのパスになります。
- **詳細は一般的な内容にとどめてください。** 詳細はクライアントに送られます。例外のメッセージには SQL、テーブル名、値が含まれているかもしれません。
- **ロギング。** 解決された各エラーは、`spring.web.mvc` で debug レベルとしてログに記録されます。エラーの `toString()`、ステータス、リゾルバーが含まれます: `Resolved [Instance of 'RoomTakenException'] as 409 by RoomTakenResolver`。5xx の応答であっても警告は記録されません。debug ログを読むときに役立つ `toString()` を例外に持たせてください。
- **例外を投げたリゾルバー** は警告としてログに記録されて飛ばされ、次のリゾルバーに問い合わせます。
- **エラーごとに一度だけ。** リクエストの同じエラーについて、リゾルバーに問い合わせるのは最大一回です。

## ライブラリが登録するリゾルバー

### データスターター: `dataAccessExceptionResolver`

`spring_boot_starter_web` と `spring_boot_starter_data` の両方に依存するアプリケーションは、自分で書かなくてもリゾルバーを得られます。どちらのスターターも互いに依存できないため、ジェネレーターが Bean `dataAccessExceptionResolver` をアプリケーションのモジュールに追加します (データベースドライバーを追加するのと同じ方法です)。

| 例外 | ステータス | 詳細 |
|---|---|---|
| `OptimisticLockingFailureException` (`@Version` の競合) | 409 | `The resource was changed by someone else` |
| `DuplicateKeyException` | 409 | `The resource already exists` |
| `EmptyResultDataAccessException` | 404 | `Not found` |
| `PropertyReferenceException` | 400 | `Invalid sort property` |
| `InvalidPagingRequestException` | 400 | `Invalid page or sort request` |
| `InvalidDataArgumentException` | 400 | `Invalid request value` |

- サブタイプも対応付けられます。
- 詳細は固定で、例外のメッセージは使いません。メッセージには SQL、テーブル名、値が含まれているかもしれないためです。例外は `cause` として保持されますが、送られません。
- それ以外のデータのエラーは、他の例外と同じく詳細なしの 500 のままです。
- 置き換えるには、`dataAccessExceptionResolver` という名前の Bean を宣言します。これらのエラーの一つに別の応答をするには、それ用の `@ExceptionHandler` を書きます。こちらが先に試されます。

## Spring (Java) との対応

```java
@Component
class RoomTakenResolver implements HandlerExceptionResolver {
  public ModelAndView resolveException(HttpServletRequest request,
      HttpServletResponse response, Object handler, Exception ex) {
    if (!(ex instanceof RoomTakenException)) return null;
    response.setStatus(HttpServletResponse.SC_CONFLICT);
    return new ModelAndView();
  }
}
```

重要な違い:

- リゾルバーは、レスポンスに書き込んで `ModelAndView` を返す代わりに、`ErrorResponse` (または `null`) を返します。
- Spring の組み込みのリゾルバーは、`@ExceptionHandler` メソッド (`ExceptionHandlerExceptionResolver`)、`ResponseStatusException` と `ErrorResponse` の処理、`DefaultHandlerExceptionResolver` です。ここではそれらが組み込まれており、リゾルバー Bean には常にその後で問い合わせます。
- 例外クラスの `@ResponseStatus` (`ResponseStatusExceptionResolver`) は読まれません。

## 関連項目

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