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とマッピングを突き合わせる
405HTTPメソッドが違うAllow ヘッダーで受け付けるメソッドを確認
415Content-Typeが consumes や @RequestBody と合わない-H 'Content-Type: application/json' を付ける
406Acceptが 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を組み立ててみましょう。