
# コントローラー

コントローラーは、メソッドが HTTP リクエストに応答する Bean です。各メソッドにはマッピングアノテーションが付き、各引数は値の出どころを示し、戻り値がレスポンスになります。

## 使う理由

コントローラーが持つのは、エンドポイントに固有のコード、つまりどのサービスをどの値で呼ぶかだけです。その周りのすべてはスターターが行い、アノテーションで宣言します。

- メソッドが応答するリクエスト: [@GetMapping](request-mapping.md) とその他のマッピング
- 値の出どころ: [@PathVariable](path-variable.md)、[@RequestParam](request-param.md)、[@RequestBody](request-body.md)、[@RequestHeader と @CookieValue](headers-and-cookies.md)
- 応答の書き方: [戻り値](results.md)
- エラーへの応答: [エラー](../errors/index.md)

## 例

```dart
import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

enum Genre { fiction, science, poetry }

class Book {
  const Book({required this.isbn, required this.title, this.genre = Genre.fiction});

  final String isbn;
  final String title;
  final Genre genre;
}

@Service()
class BookService {
  Future<Book> find(String isbn) async => Book(isbn: isbn, title: 'Dune');

  Future<List<Book>> search(String query, {int page = 0, Genre? genre}) async =>
      [Book(isbn: '978-0', title: query)];

  Future<void> delete(String isbn) async {}
}

@RestController()
@RequestMapping('/api/books')
class BookController {
  BookController(this.books); // 他の Bean と同じように注入される

  final BookService books;

  // GET /api/books/978-0 → 本を JSON で返す
  @GetMapping('/{isbn}')
  Future<Book> find(@PathVariable() String isbn) => books.find(isbn);

  // GET /api/books?q=dune&page=2&genre=science
  @GetMapping()
  Future<List<Book>> search(
    @RequestParam('q') String query, {
    @RequestParam() int page = 0, // ない場合: Dart のデフォルト
    @RequestParam() Genre? genre, // ない場合: null
  }) => books.search(query, page: page, genre: genre);

  // DELETE /api/books/978-0 → 204 No Content
  @DeleteMapping('/{isbn}')
  @ResponseStatus(HttpStatus.noContent)
  Future<void> delete(@PathVariable() String isbn) => books.delete(isbn);
}
```

## リクエストの流れ

1. **サーバー** がリクエストを読み、`dispatcherHandler` Bean（Spring の `DispatcherServlet`）に渡します。各リクエストは専用の `Zone` で実行されるため、`await` をまたいでも、処理中のどこでも `RequestContextHolder.currentRequest` がそのリクエストになります。
2. **`server.context-path`** がパスから取り除かれます。その外のリクエストは 404 です。
3. **フィルター** が `@Order` の順に実行されます（[フィルター](../filters.md) を参照）。
4. **ハンドラーマッピング** に順に問い合わせます。コントローラーが最初（`requestMappingHandlerMapping`、順序 0）、次に WebSocket のエンドポイント、次に静的リソースです（[ハンドラーマッピング](../server/handler-mappings.md) を参照）。
5. **ルーターがメソッドを選びます。** パスパターンが一致するマッピングのうち、リクエストの HTTP メソッドのものを残し（なければ `405`）、次に `consumes` が `Content-Type` に合うもの（`415`）、次に `produces` が `Accept` に合うもの（`406`）、次に `headers` の条件が成り立つもの（`400`）を残します。最も具体的なパターンが勝ち、次に条件の多いマッピングが勝ちます（[@RequestMapping](request-mapping.md) を参照）。
6. メソッドの **CORS のルール** が適用されます（[CORS](../cors.md) を参照）。
7. `WebMvcConfigurer` が登録した **インターセプター** の `preHandle` が実行されます（[WebMvcConfigurer](../web-mvc-configurer.md) を参照）。
8. **引数が 1 つずつリクエストから埋められます。** 必須の値がなければ 400、変換できない値は引数を示す 400 です。
9. **メソッドが呼ばれます。** コンテナが保持する Bean に対して呼ばれるため、コントローラーへの AOP のアドバイス（`@Cacheable`、メソッドバリデーション、セキュリティスターターの `@PreAuthorize`）が適用されます。`Future` は await されます。
10. **インターセプターの `postHandle`** が実行され、その後に結果が書き込まれます（[戻り値](results.md) を参照）。
11. 手順 5 から 10 のどこかで起きた **例外** は、[@ExceptionHandler](../errors/exception-handler.md) メソッド、次に [HandlerExceptionResolver](../errors/handler-exception-resolver.md) Bean、最後にデフォルトの応答に送られます（[エラー](../errors/index.md) を参照）。
12. **アップロードの一時ファイルが削除され**、インターセプターの `afterCompletion` が実行されます。

`HEAD` には、すべての `GET` マッピングが応答します（ヘッダーと `Content-Length` を返し、ボディは返しません）。`OPTIONS` マッピングのないマップ済みのパスへの `OPTIONS` リクエストには、`Allow` ヘッダー付きの 200 が返ります。

## 引数の一覧

| 引数 | 値 | ページ |
|---|---|---|
| `@PathVariable() String isbn` | パスの `{isbn}` | [@PathVariable](path-variable.md) |
| `@RequestParam('q') String query` | クエリパラメーターまたはフォームのフィールド。`Map` はすべてを受け取る | [@RequestParam](request-param.md) |
| `@RequestBody() Book book` | JSON としてのボディ（またはテキスト、バイト、ストリーム、フォームのマップ） | [@RequestBody](request-body.md) |
| `@RequestBody() @Valid() NewBook book` | 検証されたボディ。違反は 400 | [@RequestBody](request-body.md) |
| `@RequestHeader('X-Trace') String? trace` | ヘッダー。`HttpHeaders` または `Map` はすべてを受け取る | [ヘッダーとクッキー](headers-and-cookies.md) |
| `@CookieValue('session') String session` | クッキー | [ヘッダーとクッキー](headers-and-cookies.md) |
| `@RequestPart('cover') MultipartFile cover` | マルチパートアップロードのパート | [アップロード](../streaming/uploads.md) |
| `ServerHttpRequest`、`ServerHttpResponse`、`HttpHeaders`、`HttpMethod`、`Uri`、`Principal` | リクエスト、レスポンス、そのヘッダー、メソッド、URI、ユーザー | [ヘッダーとクッキー](headers-and-cookies.md) |
| アノテーションのない単純な型（`String q`、`int page`） | その名前のクエリパラメーター | [@RequestParam](request-param.md) |
| 独自の型 | 自分で登録する `HandlerMethodArgumentResolver` | [WebMvcConfigurer](../web-mvc-configurer.md) |

**単純な値** は、`String`、`int`、`double`、`num`、`bool`、`BigInt`、`DateTime`、`Duration`、`Uri`、enum、`Object`、`dynamic`、およびそれらの `List` や `Set` です。変換できないテキストは 400 になります。

どの種類の値でも、**必須か省略可能かは Dart の引数で決まります**。

| リクエストに値がなく、引数が | 結果 |
|---|---|
| nullable（`String? q`） | `null` |
| デフォルト付きの省略可能な引数（`{int page = 0}`、`[int page = 0]`） | 呼び出しから省かれるため、Dart のデフォルトが適用される |
| それ以外 | 400 `Required parameter 'q' is not present.` |

## ページ一覧

- [@RestController](rest-controller.md): クラスのアノテーション、Bean、クラスに付ける `@ResponseStatus`。
- [@RequestMapping と @GetMapping](request-mapping.md): すべてのマッピングアノテーションと属性、パスパターン、照合の順序。
- [@PathVariable](path-variable.md): パス変数とその変換。
- [@RequestParam](request-param.md): クエリパラメーター、フォームのフィールド、リストとマップ。
- [@RequestBody](request-body.md): JSON、テキスト、バイト、ストリーム、フォーム。`@Valid()`。
- [ヘッダー、クッキー、リクエスト](headers-and-cookies.md): `@RequestHeader`、`@CookieValue`、アノテーションのない引数。
- [戻り値](results.md): すべての戻り値の型、`ResponseEntity`、`@ResponseStatus`、条件付きリクエスト。
- [起動時のチェック](startup-checks.md): 起動時に何がチェックされるかと、その正確なメッセージ。

## Spring (Java) との対応

```java
@RestController
@RequestMapping("/api/books")
class BookController {
  @GetMapping("/{isbn}")
  Book find(@PathVariable String isbn) { ... }

  @GetMapping
  List<Book> search(@RequestParam("q") String query,
      @RequestParam(defaultValue = "0") int page,
      @RequestParam(required = false) Genre genre) { ... }
}
```

モデルは Spring MVC と同じです。違いは次のとおりです。ルートはビルド時に生成され、必須かどうかとデフォルト値は Dart の引数で決まり、ビューはなく（`@Controller` も結果をボディとして書きます）、より多くの誤りが起動時に見つかります。

## 関連項目

- [エラー](../errors/index.md)
- [テスト](../testing.md)
- [spring_core_dart の @Controller](../../spring-core-dart/beans/controller.md)
