
# @ControllerAdvice

`@ControllerAdvice()` は、その `@ExceptionHandler` メソッドがアプリケーションのすべてのコントローラーのエラーに応答する Bean を示します。`@RestControllerAdvice()` も同じです。

## 使う理由

`BookNotFoundException` のようなエラーは多くのコントローラーから発生し得ます。同じ `@ExceptionHandler` をそれぞれに書くとコードが重複し、応答も少しずつずれていきます。アドバイス Bean は、すべてのコントローラーのためのハンドラーを一度だけ持ちます。また、どのコントローラーにも見えないエラーも見ます。何もマッピングされていないパス (404)、誤ったメソッド (405)、誰も扱わない `Accept` や `Content-Type` (406、415)、WebSocket ハンドシェイクのエラーです。

アプリケーションの部分ごとに応答を変えたい場合、たとえば公開 API より詳しい情報を返す管理用 API がある場合は、アドバイスを絞り込みます。

## 例

```dart
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](exception-handler.md) のルールに従います。
- **`@RestControllerAdvice` と `@ControllerAdvice` は同じように動きます。** ビューがないため、どのアドバイスもハンドラーの戻り値をボディとして書き出します。`@RestControllerAdvice` は、Spring 向けに書いたコードが同じように読めるように存在します。
- **コントローラー自身のハンドラーが先です。** アドバイスは、コントローラーのハンドラーが応答しなかったものに応答します。
- **順序。** アドバイス Bean は `@Order` 順に試されます (小さい値が先。`@Order` がなければ最後。同じ値なら登録順)。コントローラーに適用され、かつそのエラーのハンドラーを持つ最初の Bean が応答します。Spring と同じく、後の Bean により具体的なハンドラーがあってもそうなります。一つの Bean の中では、最も具体的なハンドラーが選ばれます。
- **絞り込んだアドバイスとコントローラーのないエラー。** Spring と同じく、`.of` で絞り込んだアドバイスは、コントローラーメソッドが選ばれる前に発生したエラー (404、405、406、415、ヘッダー条件を満たさない場合の 400) も、他のハンドラーマッピングのエラーも見ません。
- **フィルターが投げたエラー** はどのアドバイスにも届きません。
- **`HandlerExceptionResolver` Bean** には、どのアドバイスも (コントローラーのハンドラーも) 応答しなかった場合にだけ問い合わせます ([HandlerExceptionResolver](handler-exception-resolver.md) を参照)。

## Spring (Java) との対応

```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` メソッドだけです。

## 関連項目

- [@ExceptionHandler](exception-handler.md)
- [HandlerExceptionResolver](handler-exception-resolver.md)
- [エラー](index.md)
- [@Component](../../spring-core-dart/beans/component.md)
