コントローラー
コントローラーは、メソッドが HTTP リクエストに応答する Bean です。各メソッドにはマッピングアノテーションが付き、各引数は値の出どころを示し、戻り値がレスポンスになります。
使う理由
コントローラーが持つのは、エンドポイントに固有のコード、つまりどのサービスをどの値で呼ぶかだけです。その周りのすべてはスターターが行い、アノテーションで宣言します。
- メソッドが応答するリクエスト: @GetMapping とその他のマッピング
- 値の出どころ: @PathVariable、@RequestParam、@RequestBody、@RequestHeader と @CookieValue
- 応答の書き方: 戻り値
- エラーへの応答: エラー
例
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);
}
リクエストの流れ
- サーバー がリクエストを読み、
dispatcherHandlerBean(Spring のDispatcherServlet)に渡します。各リクエストは専用のZoneで実行されるため、awaitをまたいでも、処理中のどこでもRequestContextHolder.currentRequestがそのリクエストになります。 server.context-pathがパスから取り除かれます。その外のリクエストは 404 です。- フィルター が
@Orderの順に実行されます(フィルター を参照)。 - ハンドラーマッピング に順に問い合わせます。コントローラーが最初(
requestMappingHandlerMapping、順序 0)、次に WebSocket のエンドポイント、次に静的リソースです(ハンドラーマッピング を参照)。 - ルーターがメソッドを選びます。 パスパターンが一致するマッピングのうち、リクエストの HTTP メソッドのものを残し(なければ
405)、次にconsumesがContent-Typeに合うもの(415)、次にproducesがAcceptに合うもの(406)、次にheadersの条件が成り立つもの(400)を残します。最も具体的なパターンが勝ち、次に条件の多いマッピングが勝ちます(@RequestMapping を参照)。 - メソッドの CORS のルール が適用されます(CORS を参照)。
WebMvcConfigurerが登録した インターセプター のpreHandleが実行されます(WebMvcConfigurer を参照)。- 引数が 1 つずつリクエストから埋められます。 必須の値がなければ 400、変換できない値は引数を示す 400 です。
- メソッドが呼ばれます。 コンテナが保持する Bean に対して呼ばれるため、コントローラーへの AOP のアドバイス(
@Cacheable、メソッドバリデーション、セキュリティスターターの@PreAuthorize)が適用されます。Futureは await されます。 - インターセプターの
postHandleが実行され、その後に結果が書き込まれます(戻り値 を参照)。 - 手順 5 から 10 のどこかで起きた 例外 は、@ExceptionHandler メソッド、次に HandlerExceptionResolver Bean、最後にデフォルトの応答に送られます(エラー を参照)。
- アップロードの一時ファイルが削除され、インターセプターの
afterCompletionが実行されます。
HEAD には、すべての GET マッピングが応答します(ヘッダーと Content-Length を返し、ボディは返しません)。OPTIONS マッピングのないマップ済みのパスへの OPTIONS リクエストには、Allow ヘッダー付きの 200 が返ります。
引数の一覧
| 引数 | 値 | ページ |
|---|---|---|
@PathVariable() String isbn |
パスの {isbn} |
@PathVariable |
@RequestParam('q') String query |
クエリパラメーターまたはフォームのフィールド。Map はすべてを受け取る |
@RequestParam |
@RequestBody() Book book |
JSON としてのボディ(またはテキスト、バイト、ストリーム、フォームのマップ) | @RequestBody |
@RequestBody() @Valid() NewBook book |
検証されたボディ。違反は 400 | @RequestBody |
@RequestHeader('X-Trace') String? trace |
ヘッダー。HttpHeaders または Map はすべてを受け取る |
ヘッダーとクッキー |
@CookieValue('session') String session |
クッキー | ヘッダーとクッキー |
@RequestPart('cover') MultipartFile cover |
マルチパートアップロードのパート | アップロード |
ServerHttpRequest、ServerHttpResponse、HttpHeaders、HttpMethod、Uri、Principal |
リクエスト、レスポンス、そのヘッダー、メソッド、URI、ユーザー | ヘッダーとクッキー |
アノテーションのない単純な型(String q、int page) |
その名前のクエリパラメーター | @RequestParam |
| 独自の型 | 自分で登録する HandlerMethodArgumentResolver |
WebMvcConfigurer |
単純な値 は、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: クラスのアノテーション、Bean、クラスに付ける
@ResponseStatus。 - @RequestMapping と @GetMapping: すべてのマッピングアノテーションと属性、パスパターン、照合の順序。
- @PathVariable: パス変数とその変換。
- @RequestParam: クエリパラメーター、フォームのフィールド、リストとマップ。
- @RequestBody: JSON、テキスト、バイト、ストリーム、フォーム。
@Valid()。 - ヘッダー、クッキー、リクエスト:
@RequestHeader、@CookieValue、アノテーションのない引数。 - 戻り値: すべての戻り値の型、
ResponseEntity、@ResponseStatus、条件付きリクエスト。 - 起動時のチェック: 起動時に何がチェックされるかと、その正確なメッセージ。
Spring (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 も結果をボディとして書きます)、より多くの誤りが起動時に見つかります。