@ControllerAdvice
@ControllerAdvice() は、その @ExceptionHandler メソッドがアプリケーションのすべてのコントローラーのエラーに応答する Bean を示します。@RestControllerAdvice() も同じです。
使う理由
BookNotFoundException のようなエラーは多くのコントローラーから発生し得ます。同じ @ExceptionHandler をそれぞれに書くとコードが重複し、応答も少しずつずれていきます。アドバイス Bean は、すべてのコントローラーのためのハンドラーを一度だけ持ちます。また、どのコントローラーにも見えないエラーも見ます。何もマッピングされていないパス (404)、誤ったメソッド (405)、誰も扱わない Accept や Content-Type (406、415)、WebSocket ハンドシェイクのエラーです。
アプリケーションの部分ごとに応答を変えたい場合、たとえば公開 API より詳しい情報を返す管理用 API がある場合は、アドバイスを絞り込みます。
例
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';
class BookNotFoundException implements Exception {
BookNotFoundException(this.isbn);
final String isbn;
}
class AdminOnly {
const AdminOnly();
}
abstract class ReportController {}
// すべてのコントローラー用。アドバイス Bean の中で最初に試される。
@RestControllerAdvice()
@Order(1)
class ApiErrors {
@ExceptionHandler()
@ResponseStatus(HttpStatus.notFound)
ProblemDetail notFound(BookNotFoundException e) =>
ProblemDetail.forStatusAndDetail(HttpStatus.notFound, 'No book ${e.isbn}')
..setProperty('isbn', e.isbn);
// 未知のパス: ドキュメントの場所を案内する。
@ExceptionHandler()
@ResponseStatus(HttpStatus.notFound)
ProblemDetail unknown(NoHandlerFoundException e) =>
ProblemDetail.forStatusAndDetail(
HttpStatus.notFound,
'No ${e.path}; see https://shop.example/api-docs',
);
}
// package:shop/admin/ 以下のライブラリのコントローラーだけ。
@RestControllerAdvice.of(basePackages: ['package:shop/admin/'])
class AdminErrors {
@ExceptionHandler()
@ResponseStatus(HttpStatus.conflict)
ProblemDetail conflict(StateError e) =>
ProblemDetail.forStatusAndDetail(HttpStatus.conflict, e.message);
}
// ある型またはそのサブタイプのコントローラー、あるいはアノテーションを持つコントローラー。
@ControllerAdvice.of(
name: 'reportErrors',
assignableTypes: [ReportController],
annotations: [AdminOnly],
)
class ReportErrors {
@ExceptionHandler()
@ResponseStatus(HttpStatus.badRequest)
ProblemDetail invalid(ArgumentError e) =>
ProblemDetail.forStatusAndDetail(HttpStatus.badRequest, '${e.message}');
}
パラメーター
@ControllerAdvice([name]) と @RestControllerAdvice([name]): すべてのコントローラーのためのアドバイス。
| 名前 | 型 | デフォルト | 意味 |
|---|---|---|---|
name (位置引数) |
String? |
null |
Bean 名。null の場合はクラス名の lowerCamelCase。 |
@ControllerAdvice.of(...) と @RestControllerAdvice.of(...): 一部のコントローラーのためのアドバイス。いずれかのリストに一致するコントローラーがアドバイスの対象になります。
| 名前 | 型 | デフォルト | 意味 |
|---|---|---|---|
name |
String? |
null |
Bean 名。 |
basePackages |
List<String> |
const [] |
コントローラーが宣言されているライブラリ URI の接頭辞。package:shop/admin/ など (Spring の basePackages に相当し、Java のパッケージの代わりに Dart のライブラリ URI を使う)。 |
assignableTypes |
List<Type> |
const [] |
これらの型のコントローラー、またはこれらのいずれかを実装または継承する型のコントローラー。 |
annotations |
List<Type> |
const [] |
クラスに、これらのいずれかと厳密に同じ型のアノテーション (RestController など) を持つコントローラー。列挙した型を継承するアノテーションは一致しない。 |
三つのリストがすべて空の場合、.of は短い形と同じく、すべてのコントローラーを対象にします。
ルール
- アドバイスは Bean です。
@ControllerAdviceは@Componentを継承しているので、クラスは他の Bean と同じように生成され、注入されます。コンストラクターでサービスを受け取れます。 - 数に入るのは
@ExceptionHandlerメソッドだけです。 他のメソッドは無視されます。ハンドラーメソッドは、パラメーター、戻り値、@ResponseStatusについて @ExceptionHandler のルールに従います。 @RestControllerAdviceと@ControllerAdviceは同じように動きます。 ビューがないため、どのアドバイスもハンドラーの戻り値をボディとして書き出します。@RestControllerAdviceは、Spring 向けに書いたコードが同じように読めるように存在します。- コントローラー自身のハンドラーが先です。 アドバイスは、コントローラーのハンドラーが応答しなかったものに応答します。
- 順序。 アドバイス Bean は
@Order順に試されます (小さい値が先。@Orderがなければ最後。同じ値なら登録順)。コントローラーに適用され、かつそのエラーのハンドラーを持つ最初の Bean が応答します。Spring と同じく、後の Bean により具体的なハンドラーがあってもそうなります。一つの Bean の中では、最も具体的なハンドラーが選ばれます。 - 絞り込んだアドバイスとコントローラーのないエラー。 Spring と同じく、
.ofで絞り込んだアドバイスは、コントローラーメソッドが選ばれる前に発生したエラー (404、405、406、415、ヘッダー条件を満たさない場合の 400) も、他のハンドラーマッピングのエラーも見ません。 - フィルターが投げたエラー はどのアドバイスにも届きません。
HandlerExceptionResolverBean には、どのアドバイスも (コントローラーのハンドラーも) 応答しなかった場合にだけ問い合わせます (HandlerExceptionResolver を参照)。
Spring (Java) との対応
@RestControllerAdvice
@Order(1)
class ApiErrors {
@ExceptionHandler
@ResponseStatus(HttpStatus.NOT_FOUND)
ProblemDetail notFound(BookNotFoundException e) { ... }
}
@RestControllerAdvice(basePackages = "com.shop.admin")
class AdminErrors { ... }
重要な違い:
basePackagesは、Java のパッケージではなくライブラリ URI の接頭辞 (package:shop/admin/) を受け取ります。basePackageClassesはありません。annotationsはコントローラーのアノテーションの型と厳密に一致 するものだけで、それをメタアノテーションとして持つアノテーションは一致しません。- 名前以外の属性には
.ofコンストラクターが必要です。 - Spring の
@ControllerAdviceは@InitBinderや@ModelAttributeメソッドも持てますが、ここにあるのは@ExceptionHandlerメソッドだけです。