@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 つのコンストラクターがあります。
@GetMapping('/path'): パスだけ。パスなしの@GetMapping()はベースパスそのものをマップします。@GetMapping.of(path: '/path', produces: ..., consumes: ..., headers: [...]): すべての属性を名前で指定します。
例
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 文字以上 |
- 結合。 クラスのパスとメソッドのパスはつなげられます。
@RequestMapping('/api/books')と@GetMapping('/{isbn}')で/api/books/{isbn}になります。先頭の/がなければ追加されます。 - プレースホルダー。 パスの中の
${...}は、起動時に設定から埋められます:@GetMapping(r'${shop.api.base:/api}/books')。producesとconsumesでも同じです。Dart が$を自分で解釈しないよう、そのようなパスは raw 文字列(r'...')で書いてください。 - マトリクスパラメーター は、Spring と同様に照合から除外されます。
/books/1111;v=1はisbnを1111として/books/{isbn}に一致します。 - 安全でないパスは届きません。 エンコードされた
/、\、NUL(%2F、%5C、%00)を含むパス、マトリクスパラメーターで隠された.や..のセグメント(/files/..;/secret)、UTF-8 でない%エスケープには、どのフィルターよりも前にサーバーが 400 で応答します。そのため..%2F..%2Fsecretがパス変数に届くことはありません。 - 不正な形式のパターンは起動を止めます: 末尾以外の
**や{*name}、対応しない波括弧、不正な正規表現、2 回使われた変数などです(起動時のチェック を参照)。
ヘッダーの条件
headers の各要素が 1 つの条件で、構文は Spring と同じです。クラスの要素とメソッドの要素は合算されます。
| 要素 | リクエストに求められること |
|---|---|
'X-Api-Key' |
そのヘッダーを持つ |
'!X-Debug' |
そのヘッダーを持たない |
'X-Api-Version=2' |
そのヘッダーをちょうどこの値で持つ |
'X-Api-Version!=2' |
そのヘッダーをこの値で持たない(ヘッダーがなければ通る) |
パス、メソッド、メディアタイプには一致するが、どのヘッダー条件にも一致しないリクエストには、400 Unsatisfied header conditions が返ります。
メディアタイプ
consumesはリクエストのContent-Typeと比較されます。application/*のような型はapplication/jsonを含みます。Content-Typeのないリクエストは、Spring と同様にapplication/octet-streamとして比較されます。415 の応答には、そのパスが読む型を列挙したAcceptヘッダーが付きます。producesはリクエストのAcceptと比較されます。Acceptのない(または解析できない)リクエストはすべてを受け付けます。406 の応答の詳細には、そのパスが書く型が列挙されます:Acceptable representations: [text/csv].- 書かれる型。
producesを持つマッピングでは、レスポンスのContent-Typeは、クライアントのq値の順で、クライアントが受け付ける最初の型になります。戻り値 を参照してください。 - クラスとメソッドの両方にある場合、メソッドの
producesやconsumesはクラスのものに追加されるのではなく、置き換えます。 - メディアタイプの定数は
MediaTypeにあります:applicationJson、applicationProblemJson、applicationNdjson、applicationOctetStream、applicationFormUrlencoded、multipartFormData、textPlain、textHtml、textEventStream、imagePngなどです。
どのマッピングが勝つか
リクエストに対して、ルーターは次のように処理します。
- パターンがパスに一致するマッピングを残します。なければ、次のハンドラーマッピング(WebSocket のエンドポイント、静的リソース)に問い合わせ、それでもなければ 404
No endpoint GET /x.です。 - リクエストの HTTP メソッドのものを残します。
GETマッピングはHEADにも応答します。なければAllowヘッダー付きの 405(OPTIONSならAllow付きの 200)です。 consumesがContent-Typeを含むものを残します(なければ 415)。producesがAcceptに合うものを残します(なければ 406)。headersの条件が成り立つものを残します(なければ 400)。- 最も具体的なパターンを選びます。
**や{*name}のないパターンがそれらを持つものより先、次に変数とワイルドカードが少ないもの、次に固定テキストが長いものです。そのため/books/newは/books/{isbn}に勝ちます。パターンが同等なら、条件(produces、consumes、headers)の多いマッピングが勝ちます。
ルール:
HEADはGETのメソッドを実行します。ハンドラーは通常どおり書き込み、ボディは捨てられ、Content-Lengthは保たれます。OPTIONSマッピングのないマップ済みのパスへのOPTIONSには、200とAllowで応答します。Allowには、マップされたメソッド、GETがあればHEAD、そしてOPTIONSが列挙されます。- CORS のプリフライト(
OriginとAccess-Control-Request-Methodを持つOPTIONS)には CORS のルールから応答し、メソッドに渡すことはありません(CORS を参照)。 - 2 つのメソッドが同じリクエストをマップしている(同じメソッド、パターン、条件)と、
Ambiguous mappingで起動が止まります。 - 1 つのメソッドに 1 つのマッピング。 1 つのメソッドに複数のマッピングアノテーションがあると起動が止まります。他の HTTP メソッドには
@RequestMapping.ofを使ってください。 - どのメソッドもストリーミングできます。
GETと同じくPOSTもサーバー送信イベントで応答できます(サーバー送信イベント を参照)。
起動時にすべてのマッピングを確認するには、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) { ... }
}
重要な違い:
- パス以外の属性には
.ofコンストラクターが必要です:@GetMapping.of(path: '/export', produces: 'text/csv')。 produces、consumes、methodは配列ではなく 1 つの値(メディアタイプはカンマ区切りのリスト)を受け取ります。pathは複数ではなく 1 つのパターンを受け取ります。paramsの条件(params = "version=2")はサポートされていません。- より多くの誤りが起動を止めます(起動時のチェック を参照)。