@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 は短い形と同じく、すべてのコントローラーを対象にします。

ルール

Spring (Java) との対応

@RestControllerAdvice
@Order(1)
class ApiErrors {
  @ExceptionHandler
  @ResponseStatus(HttpStatus.NOT_FOUND)
  ProblemDetail notFound(BookNotFoundException e) { ... }
}

@RestControllerAdvice(basePackages = "com.shop.admin")
class AdminErrors { ... }

重要な違い:

関連項目