HandlerExceptionResolver
HandlerExceptionResolver Bean は、どの @ExceptionHandler メソッドも扱わないエラーを応答に変換します。ErrorResponse (ステータス、ヘッダー、ProblemDetail) を返すか、エラーを次に渡すために null を返します。
使う理由
ライブラリが、アプリケーションにアドバイスを書かせずに自身の例外を HTTP に対応付けるための方法です。たとえばデータスターターは、バージョンの競合に 500 ではなく 409 で応答します。アプリケーション自身の @ExceptionHandler メソッドが常に先に試されるので、アプリケーションはこれらのエラーのどれにでも独自の方法で応答できます。
ハンドラーメソッドより、コードとして書いたほうが簡単なルールのために、アプリケーションが使うこともできます。表で対応付ける例外の一群や、リクエストによって変わる対応付けなどです。
例
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()),
);
}
}
インターフェース
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) との対応
@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) は読まれません。