@ExceptionHandler

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

使う理由

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

例

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() {}
}

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

@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 の型も持たないハンドラーも同様です (起動時のチェック を参照)。バインディングのアノテーション (@RequestParam、@PathVariable など) はハンドラーのパラメーターでは読まれません。代わりにリクエストを受け取ってください。

戻り値

メソッドはコントローラーメソッドと同じものを返し、同じように書き出されます (戻り値 を参照)。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 Bean が応答します。後の Bean により具体的なハンドラーがあってもそうなります。
  3. 一つのコントローラーまたは Bean の中では、最も具体的なハンドラーが選ばれます。@ExceptionHandler([...]) にエラーの実行時の型をそのまま列挙したハンドラー、なければ例外パラメーターの型が最も具体的なハンドラーです (Error より ArgumentError が先)。

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

ルール:

Spring (Java) との対応

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

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

重要な違い:

関連項目