
# コントローラーのアノテーション

これらのアノテーションは、クラスを Web コントローラーにし、その応答とエラーの形を決めます。Web サーバー (`spring_boot_starter_web`) がそれらを読みます。他のパッケージがサーバーに依存せずにそれらを参照できるよう、このパッケージに置かれています。

## 使う理由

エンドポイントを追加するライブラリや、アプリケーションの API を列挙するツールには、アノテーションは必要ですが、動作中のサーバーは不要です。それらをここに置くことで、そうした依存関係を軽く保てます。

## 例

```dart
@RestController()
@RequestMapping('/api/books')
@CrossOrigin(origins: ['https://shop.neon.books']) // ショップのページから呼べる
class BookController {
  BookController(this.books);

  final BookService books;

  // POST /api/books は 200 ではなく 201 Created で応答する。
  @PostMapping()
  @ResponseStatus(HttpStatus.created)
  Future<Book> create(@RequestBody() Book book) => books.create(book);

  // すでにある本は、上のすべてのメソッドで 409 になる。
  @ExceptionHandler()
  ProblemDetail duplicate(DuplicateBookException e) =>
      ProblemDetail.forStatusAndDetail(HttpStatus.conflict, e.message);
}
```

## アノテーション

| アノテーション | 付ける場所 | Spring | 意味 |
|---|---|---|---|
| `@RestController([name])` | クラス | `@RestController` | マッピングしたメソッドがリクエストに応答する Bean。戻り値がレスポンスボディになる。 |
| `@RequestMapping('/api/books')` | クラス | 同じ | すべてのメソッドのパスのプレフィックスと、それらすべての `produces`、`consumes`、`headers`。 |
| `@ResponseStatus(HttpStatus.created, reason: ...)` | メソッド、コントローラークラス | 同じ | 通常の応答のステータス。`reason` があると結果は無視され、応答はその理由を詳細とするエラーになる。 |
| `@ExceptionHandler([types])` | メソッド | 同じ | コントローラーのメソッド (アドバイスではすべてのコントローラーのもの) が投げた例外を処理する。例外パラメーターの型、または `types` が対象を選び、実行時の型の完全一致で照合する。 |
| `@ControllerAdvice([name])`、`@RestControllerAdvice([name])` | クラス | 同じ | すべてのコントローラーのための例外ハンドラー。`@Order` の順に試される。 |
| `@CrossOrigin(origins:, originPatterns:, methods:, allowedHeaders:, exposedHeaders:, allowCredentials:, allowPrivateNetwork:, maxAge:)` | クラス、メソッド | 同じ | 他のオリジンの Web ページがコントローラーを呼べるようにする (CORS)。`maxAge` は秒。 |

引数のない `@CrossOrigin()` は、Spring と同じく、すべてのオリジン、ハンドラーがマッピングされたメソッド (`@DeleteMapping` なら `DELETE`、`@GetMapping` なら `GET` だけ)、すべてのリクエストヘッダー、クレデンシャルなし、30 分のプリフライトのキャッシュを許可します。

サーバーがそれらを適用する方法は Web スターターで説明しています: [@RestController](../spring-boot-starter-web/controllers/rest-controller.md)、[@ExceptionHandler](../spring-boot-starter-web/errors/exception-handler.md)、[@ControllerAdvice](../spring-boot-starter-web/errors/controller-advice.md)、[CORS](../spring-boot-starter-web/cors.md)。

## Spring (Java) との対応

```java
@RestController
@RequestMapping("/api/books")
@CrossOrigin(origins = "https://shop.neon.books")
class BookController { ... }
```

アノテーションは同じです。`@ExceptionHandler(types)` は実行時の型の完全一致で照合します。Dart は実行時に、ある `Type` が別の `Type` のサブタイプかどうかを調べられないためです。

## 関連項目

- [マッピングのアノテーション](mapping-annotations.md)
- [HTTP の型](http-types.md)
- [Web スターターのコントローラー](../spring-boot-starter-web/controllers/index.md)
