Spring BootでAPIを書き始めると、@RequestMapping と @GetMapping が混ざったサンプルを見かけて「結局どっちを使えばいいの?」と迷いますよね。
先に結論を言うと、@GetMapping や @PostMapping は @RequestMapping(method = ...) を短く書くための合成アノテーションです。クラスには @RequestMapping で共通のパスを付け、メソッドには @GetMapping などを付ける。この使い分けでほぼ困りません。
この記事では、URL・HTTPメソッド・Content-Typeをハンドラに結びつける「マッピング」に絞って、パスの結合ルールや絞り込み属性、マッピングが原因の404・405・415・406・Ambiguous mappingの直し方まで見ていきます。前提はSpring Boot 3.x(Spring Framework 6)です。
クラスには @RestController を付けておく前提で進めます。依存関係がまだなら spring-boot-starter-webの解説 を先に見ておくとスムーズです。
@GetMappingは@RequestMapping(method = GET)の省略形
@GetMapping のソースを開くと、こうなっています(抜粋)。
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@RequestMapping(method = RequestMethod.GET)
public @interface GetMapping {
@AliasFor(annotation = RequestMapping.class)
String[] value() default {};
// path, params, headers, consumes, produces も同様
}
@RequestMapping(method = RequestMethod.GET) がメタアノテーションとして付いていて、value や produces などの属性は @AliasFor でそのまま @RequestMapping に渡されます。つまり次の2つは同じ動きです。
@RequestMapping(value = "/users", method = RequestMethod.GET)
public List<User> findAll() { ... }
@GetMapping("/users")
public List<User> findAll() { ... }
@Target が METHOD だけなので、@GetMapping はクラスに付けられません。クラスのプレフィックスに @RequestMapping を使うのはこのためです。
注意したいのは、@RequestMapping で method を省略すると 全HTTPメソッド に一致してしまう点です。GET用のつもりがDELETEでも呼べてしまうので、メソッドには合成アノテーションを使うのが安全です。
どのアノテーションを使うかの早見表
| HTTPメソッド | アノテーション | 典型的な用途 | 成功時のステータス例 |
|---|---|---|---|
| GET | @GetMapping | 取得 | 200 |
| POST | @PostMapping | 作成 | 201 |
| PUT | @PutMapping | 全体更新 | 200 / 204 |
| PATCH | @PatchMapping | 部分更新 | 200 / 204 |
| DELETE | @DeleteMapping | 削除 | 204 |
ルールは「クラスには @RequestMapping、メソッドには合成アノテーション」です。メソッドに @RequestMapping を使うのは、1つのハンドラで複数のHTTPメソッドを受けたいような例外的な場面くらいですね。
ステータスの返し方は @ResponseStatusの記事 で、4エンドポイントを通しで動かす実装は CRUDチュートリアル で解説しています。
クラスとメソッドのパスはどう結合されるか
@RestController
@RequestMapping("/api/users")
public class UserController {
@GetMapping // GET /api/users
public List<User> findAll() { ... }
@GetMapping("/{id:\\d+}") // GET /api/users/1(数字のみ、後述)
public User findById(@PathVariable Long id) { ... }
@PostMapping(consumes = MediaType.APPLICATION_JSON_VALUE) // POST /api/users
public User create(@RequestBody User user) { ... }
@DeleteMapping("/{id:\\d+}") // DELETE /api/users/1
public void delete(@PathVariable Long id) { ... }
}
クラス側とメソッド側のパスは連結されます。"users" と書いても "/users" と同じ扱いなので、先頭のスラッシュは気にしなくて大丈夫です。メソッド側でパスを省略すると、プレフィックスそのものに一致します。@GetMapping({"/me", "/current"}) のように複数パスを並べることもできます。
一方、consumes と produces は結合ではなく 上書き です。クラスに produces を付けていても、メソッド側で指定するとメソッド側だけが有効になります。params と headers は両方の条件が足し合わされるので、ここは区別して覚えておきましょう。
パスパターンの書き方
Spring Boot 2.6以降は PathPatternParser がデフォルトのパス解析器です。よく使う構文はこのあたりです(クラスのプレフィックスは省略)。
@GetMapping("/{id}") // /1 も /abc も一致
@GetMapping("/{id:\\d+}") // 数字のみ。/abc は404
@GetMapping("/*/summary") // 1セグメント分の任意の文字列
@GetMapping("/files/**") // 残りのパスすべて(末尾でのみ使える)
@GetMapping("/files/{*path}") // 残りのパスを変数 path で受け取る
先ほどの UserController で {id:\\d+} にしたのは、/{id} のままだと /api/users/export のような別のURLにも一致してしまうからです。IDが数字と決まっているなら、絞っておくと事故が減ります。
以前の AntPathMatcher では /a/**/b のように ** を途中に書けましたが、Boot 3の PathPatternParser ではエラーになります。古い記事のパターンをコピペしたときは要注意です。
パス変数の値を引数で受け取る方法は リクエストパラメータの受け取り方 にまとめているので、ここでは割愛します。
Spring Boot 3で末尾スラッシュが一致しなくなった
Boot 2では /api/users/ でアクセスしても /api/users に一致しましたが、Spring Framework 6(Boot 3)からはデフォルトで一致しなくなり、404が返ります。移行直後に「急に404になった」ときは、まずここを疑いましょう。/users.json のような拡張子付きURLで一致させるsuffix pattern matchも、すでに廃止されています。
対処はクライアント側のURLを直すのが基本です。どうしても両方受けたいなら明示的に書きます。
@GetMapping({"", "/"}) // /api/users と /api/users/ の両方
public List<User> findAll() { ... }
末尾スラッシュ一致をグローバルに戻す設定は非推奨で、将来削除される予定なので頼らないほうが無難です。
params・headersで絞り込む
同じパスでも、クエリパラメータやヘッダーでハンドラを分けられます。
@GetMapping(path = "/search", params = "type=admin")
public List<User> searchAdmins() { ... }
@GetMapping(path = "/search", params = "type=member")
public List<User> searchMembers() { ... }
@GetMapping(path = "/report", headers = "X-API-Version=2")
public Report reportV2() { ... }
params = "!debug" のように ! を付けると「そのパラメータがないこと」が条件になります。
条件に合わないとき、headers なら404ですが、params だけが合わない場合は400(UnsatisfiedServletRequestParameterException)になります。パスは合っているのに400、というときは params を見直しましょう。ヘッダーを使ったバージョン分けは バージョニング戦略の記事 で扱っています。
consumesとproducesでContent-Typeを制御する
ここは混同しやすいところですよね。consumes は リクエスト の Content-Type に対する条件で、produces は レスポンス の形式です。produces はリクエストの Accept と照合されます。
@GetMapping(path = "/export", produces = MediaType.APPLICATION_JSON_VALUE)
public List<User> exportJson() { ... }
@GetMapping(path = "/export", produces = "text/csv")
public String exportCsv() { ... }
同じパスでも、Accept: text/csv ならCSV版が呼ばれます。文字列で書くより MediaType の定数を使うほうがタイプミスを防げます(text/csv は定数がないので文字列です)。consumes = "!text/plain" のような否定も書けます。
404・405・415・406をcurlで再現する
ステータスコードを見れば、どの条件で外れたかがだいたい分かります。curl -i でヘッダーごと確認しましょう。
# 404: 末尾スラッシュ(Boot 3)
$ curl -i http://localhost:8080/api/users/
HTTP/1.1 404
# 405: GETとDELETEしかないパスにPOST
$ curl -i -X POST http://localhost:8080/api/users/1
HTTP/1.1 405
Allow: GET,DELETE
# 415: Content-Type忘れ(curl -d はform形式で送る)
$ curl -i -X POST http://localhost:8080/api/users -d '{"name":"taro"}'
HTTP/1.1 415
# 406: producesにないAcceptを要求
$ curl -i http://localhost:8080/api/users/export -H 'Accept: application/xml'
HTTP/1.1 406
| ステータス | 主な原因 | 直し方 |
|---|---|---|
| 404 | パスの打ち間違い、プレフィックス忘れ、末尾スラッシュ、headers不一致 | URLとマッピングを突き合わせる |
| 405 | HTTPメソッドが違う | Allow ヘッダーで受け付けるメソッドを確認 |
| 415 | Content-Typeが consumes や @RequestBody と合わない | -H 'Content-Type: application/json' を付ける |
| 406 | Acceptが produces と合わない | Acceptを直すか produces を追加 |
エラーレスポンスのJSON形式を揃えたいときは 統一的なエラーレスポンスの記事 を参考にしてください。
起動時のAmbiguous mappingを読んで直す
同じパス・同じメソッドを2つのハンドラに付けると、起動時に落ちます。
@GetMapping
public List<User> findAll() { ... }
@GetMapping // コピペで残ったメソッド
public List<User> findAllV2() { ... }
Caused by: java.lang.IllegalStateException: Ambiguous mapping. Cannot map 'userController' method
com.example.demo.UserController#findAllV2()
to {GET [/api/users]}: There is already 'userController' bean method
com.example.demo.UserController#findAll() mapped.
読むのは3か所です。Cannot map の後が登録しようとしたメソッド、to {...} が衝突した条件、There is already の後が登録済みのメソッドです。パスを分けるか、params・headers・produces で条件を分ければ解消します。コピペの残骸なら片方を消しましょう。
ほかの起動エラーも含めた切り分けは 起動しない時の原因切り分け にまとめています。
MockMvcでマッピングのエラーをテストする
マッピングを変えたときに405や415をうっかり生まないよう、回帰テストで固定しておくと安心です。
@WebMvcTest(UserController.class)
class UserControllerMappingTest {
@Autowired
MockMvc mockMvc;
@Test
void postToIdIsNotAllowed() throws Exception {
mockMvc.perform(post("/api/users/1"))
.andExpect(status().isMethodNotAllowed())
.andExpect(header().string("Allow", containsString("GET")));
}
@Test
void createWithTextIsUnsupported() throws Exception {
mockMvc.perform(post("/api/users")
.contentType(MediaType.TEXT_PLAIN).content("taro"))
.andExpect(status().isUnsupportedMediaType());
}
@Test
void exportAsXmlIsNotAcceptable() throws Exception {
mockMvc.perform(get("/api/users/export").accept(MediaType.APPLICATION_XML))
.andExpect(status().isNotAcceptable());
}
}
コントローラーがServiceに依存している場合は、@MockitoBean でモックを用意してください。@WebMvcTest の基本は MockMvcでControllerをテストする記事 で解説しています。
まとめ
@GetMapping などは @RequestMapping(method = ...) の省略形なので、クラスには @RequestMapping、メソッドには合成アノテーションを付ければOKです。
エラーが出たら、404はパス、405はHTTPメソッド、415は consumes、406は produces、起動時の失敗は重複マッピングを疑ってみてください。ステータスコードから逆引きできるようになると、マッピングまわりで迷う時間はかなり減るはずです。
次は リクエストパラメータの受け取り方 や CRUDチュートリアル で、実際のAPIを組み立ててみましょう。