コントローラー

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

使う理由

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

例

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 の順に実行されます(フィルター を参照)。
  4. ハンドラーマッピング に順に問い合わせます。コントローラーが最初(requestMappingHandlerMapping、順序 0)、次に WebSocket のエンドポイント、次に静的リソースです(ハンドラーマッピング を参照)。
  5. ルーターがメソッドを選びます。 パスパターンが一致するマッピングのうち、リクエストの HTTP メソッドのものを残し(なければ 405)、次に consumes が Content-Type に合うもの(415)、次に produces が Accept に合うもの(406)、次に headers の条件が成り立つもの(400)を残します。最も具体的なパターンが勝ち、次に条件の多いマッピングが勝ちます(@RequestMapping を参照)。
  6. メソッドの CORS のルール が適用されます(CORS を参照)。
  7. WebMvcConfigurer が登録した インターセプター の preHandle が実行されます(WebMvcConfigurer を参照)。
  8. 引数が 1 つずつリクエストから埋められます。 必須の値がなければ 400、変換できない値は引数を示す 400 です。
  9. メソッドが呼ばれます。 コンテナが保持する Bean に対して呼ばれるため、コントローラーへの AOP のアドバイス(@Cacheable、メソッドバリデーション、セキュリティスターターの @PreAuthorize)が適用されます。Future は await されます。
  10. インターセプターの postHandle が実行され、その後に結果が書き込まれます(戻り値 を参照)。
  11. 手順 5 から 10 のどこかで起きた 例外 は、@ExceptionHandler メソッド、次に HandlerExceptionResolver Bean、最後にデフォルトの応答に送られます(エラー を参照)。
  12. アップロードの一時ファイルが削除され、インターセプターの 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.

ページ一覧

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 も結果をボディとして書きます)、より多くの誤りが起動時に見つかります。

関連項目