@RequestMapping と @GetMapping

マッピングアノテーションは、コントローラーのメソッドがどのリクエストに応答するかを示します。HTTP メソッド、パス、そして Content-Type、Accept ヘッダー、その他のヘッダーに対する省略可能な条件です。

使う理由

各エンドポイントは 1 つのアノテーションを持つ 1 つのメソッドなので、API のルートをコントローラーから読み取れます。ルーターはすべてのリクエストをこれらのマッピングと比較して最も具体的なものを選び、どれも合わなければ標準的なエラーで応答します。未知のパスには 404、既知のパスに別のメソッドで来たら 405、メソッドが読まないボディの型には 415、応答できない Accept には 406 です。

アノテーション

アノテーション HTTP メソッド
@GetMapping GET(と HEAD)
@PostMapping POST
@PutMapping PUT
@PatchMapping PATCH
@DeleteMapping DELETE
@RequestMapping method: で選ぶ任意のメソッド。クラスに付けるとベースパス

Dart では名前付き引数と並べて省略可能な位置引数を置けないため、それぞれに 2 つのコンストラクターがあります。

例

import 'package:spring_boot_starter_web/spring_boot_starter_web.dart';

class Book {
  const Book({required this.isbn, required this.title});

  final String isbn;
  final String title;
}

@RestController()
@RequestMapping('/api/books') // 以下のすべてのメソッドのプレフィックス
class BookController {
  // GET /api/books
  @GetMapping()
  List<Book> all() => const [Book(isbn: '978-0', title: 'Dune')];

  // GET /api/books/978-0
  @GetMapping('/{isbn}')
  Book find(@PathVariable() String isbn) => Book(isbn: isbn, title: 'Dune');

  // POST /api/books。JSON のボディのときだけ。
  @PostMapping.of(consumes: MediaType.applicationJson)
  Book create(@RequestBody() Book book) => book;

  // PUT /api/books/978-0 は本を置き換える。
  @PutMapping('/{isbn}')
  Book replace(@PathVariable() String isbn, @RequestBody() Book book) => book;

  // PATCH /api/books/978-0 は一部のフィールドを変更する。
  @PatchMapping('/{isbn}')
  Map<String, Object?> update(
    @PathVariable() String isbn,
    @RequestBody() Map<String, Object?> changes,
  ) => changes;

  // DELETE /api/books/978-0 → 204
  @DeleteMapping('/{isbn}')
  @ResponseStatus(HttpStatus.noContent)
  void delete(@PathVariable() String isbn) {}

  // Accept: text/csv (または */*、または Accept なし) の GET /api/books/export:
  // 両方のメソッドが一致し、こちらのほうが条件が多いので勝つ。
  @GetMapping.of(path: '/export', produces: 'text/csv')
  String csv() => 'isbn,title\n978-0,Dune\n';

  // Accept: application/json なら CSV のメソッドは外れる: JSON。
  @GetMapping('/export')
  List<Book> json() => all();

  // ヘッダーで選ばれる、メソッドのバージョン 2。
  @GetMapping.of(path: '/{isbn}/summary', headers: ['X-Api-Version=2'])
  String summaryV2(@PathVariable() String isbn) => 'v2 $isbn';

  @GetMapping.of(path: '/{isbn}/summary', headers: ['X-Api-Version!=2'])
  String summary(@PathVariable() String isbn) => 'v1 $isbn';

  // ショートカットのアノテーションがないメソッド: HEAD。
  @RequestMapping.of(path: '/{isbn}/exists', method: HttpMethod.head)
  ResponseEntity<void> exists(@PathVariable() String isbn) =>
      ResponseEntity.status(HttpStatus.ok).build();
}

クラスに付けた @RequestMapping.of は、すべてのメソッドに条件を追加します。

// すべてのメソッドが JSON を読み書きし、API キーのヘッダーを必要とする。
@RestController()
@RequestMapping.of(
  path: '/api/v2',
  produces: MediaType.applicationJson,
  consumes: MediaType.applicationJson,
  headers: ['X-Api-Key'],
)
class V2Controller {
  @GetMapping('/ping')
  Map<String, String> ping() => {'status': 'ok'};
}

属性

すべてのマッピングアノテーションが次の属性を持ちます。method は @RequestMapping.of だけです。

名前 型 デフォルト 意味
path String '' クラスの @RequestMapping からの相対のパスパターン。空ならベースパスそのもの。{variables}、ワイルドカード、${...} プレースホルダーを含められる。短いコンストラクターでは位置引数。
method HttpMethod HttpMethod.get @RequestMapping.of のみ: HTTP メソッド(get、head、post、put、patch、delete、options、trace)。ショートカットのアノテーションでは固定。クラスでは無視される。
produces String? null レスポンスのメディアタイプ。1 つ、またはカンマ区切りのリスト。Accept がそのいずれかを許すときだけメソッドが選ばれ(そうでなければ 406)、ボディはそれで書かれる。null なら任意の Accept。
consumes String? null リクエストボディのメディアタイプ。1 つ、またはカンマ区切りのリスト。Content-Type がそのいずれかのときだけメソッドが選ばれる(そうでなければ 415)。null なら任意のボディ。
headers List<String> const [] リクエストヘッダーに対する条件(後述)。条件を満たすメソッドがなければ 400。

@RequestMapping('/path')(短い形式)は GET をマップします。パスだけが意味を持つクラスでは、これが通常の形式です。

パス

パスは、クエリ文字列と server.context-path を除いたリクエストパスに対して照合されるパスパターン(spring_web_dart の PathPattern)です。

パターン 一致するもの
/books そのパス自体。末尾のスラッシュは区別される: Spring 6 と同じく、/books/ は別のパス。
/books/{isbn} 1 つのセグメント。isbn として取り出され、デコードされる
/books/{isbn:\d+} 正規表現に一致する 1 つのセグメント。取り出される
/files/{*path} パスの残り。先頭の / 付きで取り出される(末尾のみ)
/static/** 0 個以上のセグメント(末尾のみ)
/b?ok ?: セグメントの 1 文字
/*.json *: セグメントの 0 文字以上

ヘッダーの条件

headers の各要素が 1 つの条件で、構文は Spring と同じです。クラスの要素とメソッドの要素は合算されます。

要素 リクエストに求められること
'X-Api-Key' そのヘッダーを持つ
'!X-Debug' そのヘッダーを持たない
'X-Api-Version=2' そのヘッダーをちょうどこの値で持つ
'X-Api-Version!=2' そのヘッダーをこの値で持たない(ヘッダーがなければ通る)

パス、メソッド、メディアタイプには一致するが、どのヘッダー条件にも一致しないリクエストには、400 Unsatisfied header conditions が返ります。

メディアタイプ

どのマッピングが勝つか

リクエストに対して、ルーターは次のように処理します。

  1. パターンがパスに一致するマッピングを残します。なければ、次のハンドラーマッピング(WebSocket のエンドポイント、静的リソース)に問い合わせ、それでもなければ 404 No endpoint GET /x. です。
  2. リクエストの HTTP メソッドのものを残します。GET マッピングは HEAD にも応答します。なければ Allow ヘッダー付きの 405(OPTIONS なら Allow 付きの 200)です。
  3. consumes が Content-Type を含むものを残します(なければ 415)。
  4. produces が Accept に合うものを残します(なければ 406)。
  5. headers の条件が成り立つものを残します(なければ 400)。
  6. 最も具体的なパターンを選びます。** や {*name} のないパターンがそれらを持つものより先、次に変数とワイルドカードが少ないもの、次に固定テキストが長いものです。そのため /books/new は /books/{isbn} に勝ちます。パターンが同等なら、条件(produces、consumes、headers)の多いマッピングが勝ちます。

ルール:

起動時にすべてのマッピングを確認するには、logging.level.spring.web.mvc=trace を設定します。debug レベルの件数(12 mappings in 'requestMappingHandlerMapping')の後に、マッピングごとに 1 行(Mapped GET /api/books/{isbn} -> BookController.find)が出力されます。debug レベルでは、各リクエストで選ばれたメソッドもログに出ます(Mapped to BookController#find())。

Spring (Java) との対応

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

  @GetMapping(path = "/export", produces = "text/csv")
  String csv() { ... }

  @RequestMapping(path = "/{isbn}/exists", method = RequestMethod.HEAD)
  ResponseEntity<Void> exists(@PathVariable String isbn) { ... }
}

重要な違い:

関連項目