注文一覧に「未処理の注文だけを表示する」検索を足したところ、Spring Bootが起動しなくなりました。ログには BeanCreationException と、その原因の Ambiguous mapping。一覧と検索でJavaのメソッド名も引数も違いますが、両方が同じ GET /orders を登録していました。
まず起動ログから、競合した二つのハンドラーとマッピング条件を探します。検索が一覧の絞り込みなら、一つのハンドラーで受け取れます。入口を分ける理由があるなら、マッピングの params にパラメータの有無を明記します。
この記事でわかること
- 起動ログのどこから、重複したGETと二つのメソッドを探すか
@RequestParamの必須設定と、@GetMappingのparamsの違い- 同じURLのまま直す2案と、選ばれるハンドラーを確認するテスト
記事と同じコードを実行する
ZIPを展開し、JDK 17とMaven 3.9系で mvn test を実行します。起動失敗の再現、二つの修正版、MockMvcのテスト、pom.xml、READMEを収録しています。
起動ログでAmbiguous mappingと二つのハンドラーを探す
ログの上にある BeanCreationException は、Beanの初期化に失敗したことを示します。原因をたどって Ambiguous mapping を見つけたら、直後のマッピングと二つのメソッドを読みます。この例では {GET [/orders]}、登録しようとした search(String)、すでに登録されていた list() が出ます。
起動失敗時の原因ログ(実行結果の抜粋)
java.lang.IllegalStateException: Ambiguous mapping. Cannot map 'info.syachiku.mappingfixture.BrokenMappingTest$BrokenOrdersController' method
info.syachiku.mappingfixture.BrokenMappingTest$BrokenOrdersController#search(String)
to {GET [/orders]}: There is already 'info.syachiku.mappingfixture.BrokenMappingTest$BrokenOrdersController' bean method
info.syachiku.mappingfixture.BrokenMappingTest$BrokenOrdersController#list() mapped.SpringがControllerのマッピングを組み立てる起動時に発生するため、GETを送る前に止まります。別のプロジェクトで読むなら、ログに出たクラス名とメソッド名を検索し、クラスの @RequestMapping とメソッドの指定を合わせたパスを比べます。BeanCreationException の原因が別にある場合は、失敗したBeanと Caused by から調べます。
Javaの引数と@RequestParamだけではマッピング条件が変わらない
GET /ordersが重複するメソッド(抜粋)
@GetMapping("/orders")
String list() {
return "list";
}
@GetMapping("/orders")
String search(@RequestParam(name = "status", required = false) String status) {
return "search " + status;
}一覧の list() と検索の search(String) は、Javaのメソッドとしては区別できます。Spring MVCが起動時に登録する条件は、どちらも同じGET、同じ /orders、追加の条件なしです。/orders?status=OPEN のパスも /orders で、status はクエリパラメータです。
@RequestParam(name = "status", required = false) は、選ばれたメソッドの引数へ値を渡すための指定です。値がない場合を許せますが、これを付けただけでは、どのメソッドを選ぶかの条件にはなりません。パスとHTTPメソッド以外に params、headers、consumes、produces などの条件を付ける方法もあります。ここでは全条件が一致するため、登録が衝突します。
list()GET /orders追加条件なしsearch(String)GET /orders追加条件なしAmbiguous mapping一覧の絞り込みなら、一つのハンドラーで受け取る
CombinedOrdersController.java(全文)
package info.syachiku.orders;
import java.util.List;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
@ConditionalOnProperty(name = "orders.mapping", havingValue = "combined", matchIfMissing = true)
class CombinedOrdersController {
private final OrderCatalog catalog;
CombinedOrdersController(OrderCatalog catalog) {
this.catalog = catalog;
}
@GetMapping("/orders")
List<OrderCatalog.Order> findOrders(@RequestParam(name = "status", required = false) String status) {
return catalog.find(status);
}
}この注文APIは、一覧と検索で返すJSONの形が同じです。status がなければ全件を返し、OPEN があれば一致する注文に絞ります。GET /orders の登録は一つにして、パラメータの有無による絞り込みは共通の OrderCatalog へ渡します。
処理を分けるなら、paramsで有無を明示する
ParameterOrdersController.java(全文)
package info.syachiku.orders;
import java.util.List;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
@RestController
@ConditionalOnProperty(name = "orders.mapping", havingValue = "params")
class ParameterOrdersController {
private final OrderCatalog catalog;
ParameterOrdersController(OrderCatalog catalog) {
this.catalog = catalog;
}
@GetMapping(path = "/orders", params = "!status")
List<OrderCatalog.Order> list() {
return catalog.find(null);
}
@GetMapping(path = "/orders", params = "status")
List<OrderCatalog.Order> search(@RequestParam("status") String status) {
return catalog.find(status);
}
}params = "!status" は status というキーがないリクエストに一致します。params = "status" はキーがあるリクエストに一致します。同じGETとパスでも条件は排他的なので、一覧と検索を別々に登録できます。
?status= は、値が空でもキーがあるため検索側へ進みます。このサンプルでは空文字に一致する注文がなく、空の配列を返します。空を入力エラーとする要件なら、検索側の入力検証を決め、空のリクエストもテストします。
二つの修正案で、同じURLと結果を維持する
| リクエスト | HTTP 200の結果 | paramsで分けたとき |
|---|---|---|
GET /orders | 2件。ORD-101とORD-102 | list() |
GET /orders?status=OPEN | 1件。ORD-101 | search(String) |
GET /orders?status= | 0件 | search(String) |
配布ZIPは二つの方法を同じURLで比較できるよう、orders.mapping でControllerを一つずつ有効にします。combined が統合版、params が条件付き版です。この設定はサンプルで比較するために用意したもので、実際に直すときは要件に合うControllerを選びます。
OrderCatalog.java(全文)
package info.syachiku.orders;
import java.util.List;
import org.springframework.stereotype.Component;
@Component
class OrderCatalog {
private static final List<Order> ORDERS = List.of(
new Order("ORD-101", "OPEN"),
new Order("ORD-102", "CLOSED"));
List<Order> find(String status) {
if (status == null) {
return ORDERS;
}
return ORDERS.stream().filter(order -> order.status().equals(status)).toList();
}
record Order(String number, String status) {
}
}OrdersApp.java(全文)
package info.syachiku.orders;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication(proxyBeanMethods = false)
public class OrdersApp {
public static void main(String[] args) {
SpringApplication.run(OrdersApp.class, args);
}
}起動できることと、選ばれたハンドラーを別々に確認する
ZIPを展開し、pom.xml のあるフォルダで mvn test を実行します。JDK 17、Maven 3.9系、Spring Boot 3.5.16、JUnit Jupiter 5.12.2で確認しました。再現用の BrokenMappingTest は、同じマッピングを持つControllerだけをテスト用のWebコンテキストに登録し、意図した起動失敗とログの内容を確かめます。正常にテストが通っても、再現用のエラーログは出ます。
BrokenMappingTest.java(全文)
package info.syachiku.mappingfixture;
import org.junit.jupiter.api.Test;
import org.springframework.boot.autoconfigure.EnableAutoConfiguration;
import org.springframework.boot.test.context.runner.WebApplicationContextRunner;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Import;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import static org.junit.jupiter.api.Assertions.assertInstanceOf;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
class BrokenMappingTest {
@Test
void duplicateGetMappingsFailDuringStartup() {
new WebApplicationContextRunner()
.withUserConfiguration(BrokenApp.class)
.run(context -> {
Throwable failure = context.getStartupFailure();
assertNotNull(failure);
while (failure.getCause() != null) {
failure = failure.getCause();
}
assertInstanceOf(IllegalStateException.class, failure);
String message = failure.getMessage();
assertTrue(message.contains("Ambiguous mapping"), message);
assertTrue(message.contains("{GET [/orders]}"), message);
assertTrue(message.contains("#list()"), message);
assertTrue(message.contains("#search(String)"), message);
System.out.println(failure);
});
}
@Configuration(proxyBeanMethods = false)
@EnableAutoConfiguration
@Import(BrokenOrdersController.class)
static class BrokenApp {
}
@RestController
static class BrokenOrdersController {
@GetMapping("/orders")
String list() {
return "list";
}
@GetMapping("/orders")
String search(@RequestParam(name = "status", required = false) String status) {
return "search " + status;
}
}
}修正版は @SpringBootTest で起動し、MockMvcでHTTPステータス、選ばれたメソッド名、JSONの件数を比べます。統合版では3リクエストとも findOrders、条件付き版ではパラメータなしだけ list、キーがある2件は search です。実際のサーバーポートを開かず、Spring MVCの処理を通します。
CombinedOrdersHttpTest.java(全文)
package info.syachiku.orders;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.handler;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@SpringBootTest(properties = "orders.mapping=combined")
@AutoConfigureMockMvc
class CombinedOrdersHttpTest {
@Autowired
private MockMvc mvc;
@Test
void listsAllWithoutStatus() throws Exception {
mvc.perform(get("/orders"))
.andExpect(status().isOk())
.andExpect(handler().methodName("findOrders"))
.andExpect(jsonPath("$.length()").value(2))
.andExpect(jsonPath("$[0].number").value("ORD-101"))
.andExpect(jsonPath("$[1].number").value("ORD-102"));
}
@Test
void findsOpenOrdersWhenStatusIsPresent() throws Exception {
mvc.perform(get("/orders").param("status", "OPEN"))
.andExpect(status().isOk())
.andExpect(handler().methodName("findOrders"))
.andExpect(jsonPath("$.length()").value(1))
.andExpect(jsonPath("$[0].number").value("ORD-101"));
}
@Test
void emptyStatusIsPresentAndMatchesNoOrders() throws Exception {
mvc.perform(get("/orders").param("status", ""))
.andExpect(status().isOk())
.andExpect(handler().methodName("findOrders"))
.andExpect(jsonPath("$.length()").value(0));
}
}ParameterOrdersHttpTest.java(全文)
package info.syachiku.orders;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.web.servlet.MockMvc;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.handler;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
@SpringBootTest(properties = "orders.mapping=params")
@AutoConfigureMockMvc
class ParameterOrdersHttpTest {
@Autowired
private MockMvc mvc;
@Test
void listsAllWithoutStatus() throws Exception {
mvc.perform(get("/orders"))
.andExpect(status().isOk())
.andExpect(handler().methodName("list"))
.andExpect(jsonPath("$.length()").value(2))
.andExpect(jsonPath("$[0].number").value("ORD-101"))
.andExpect(jsonPath("$[1].number").value("ORD-102"));
}
@Test
void findsOpenOrdersWhenStatusIsPresent() throws Exception {
mvc.perform(get("/orders").param("status", "OPEN"))
.andExpect(status().isOk())
.andExpect(handler().methodName("search"))
.andExpect(jsonPath("$.length()").value(1))
.andExpect(jsonPath("$[0].number").value("ORD-101"));
}
@Test
void emptyStatusIsPresentAndMatchesNoOrders() throws Exception {
mvc.perform(get("/orders").param("status", ""))
.andExpect(status().isOk())
.andExpect(handler().methodName("search"))
.andExpect(jsonPath("$.length()").value(0));
}
}pom.xml(全文)
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>3.5.16</version>
<relativePath/>
</parent>
<groupId>info.syachiku</groupId>
<artifactId>spring-ambiguous-mapping-sample</artifactId>
<version>1.0.0</version>
<properties>
<java.version>17</java.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-test</artifactId>
<scope>test</scope>
<exclusions>
<exclusion>
<groupId>org.mockito</groupId>
<artifactId>mockito-core</artifactId>
</exclusion>
<exclusion>
<groupId>org.mockito</groupId>
<artifactId>mockito-junit-jupiter</artifactId>
</exclusion>
</exclusions>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
</plugins>
</build>
</project>通常実行は7件成功します。別の場所に展開し、ParameterOrdersController.java の二つの params を削除して、どちらも @GetMapping("/orders") に変えると、条件付き版のコンテキストが起動できません。この状態ではHTTPを送る前に3件がエラーになります。再現後は条件を戻します。
修正版とparamsを削除した場合の実行結果
配布ZIPの mvn test
[INFO] Tests run: 7, Failures: 0, Errors: 0, Skipped: 0
paramsを削除した版の mvn test
[ERROR] Tests run: 7, Failures: 0, Errors: 3, Skipped: 0レビューでは、検索のために入口を二つにする理由を確認する
レビューコメント例「一覧と検索で同じ GET /orders を使い、返すJSONも同じなら、一つのハンドラーで絞り込みを受け取れます。分ける理由があるなら、status の有無をマッピングに書き、空の値を送ったときもどちらに入るかテストしましょう。」
起動できるのにリクエストで404・405・415・406が返る場合は、実際に届いたURLやHTTPメソッド、本文や応答の形式を調べます。今回のログは、その前の起動時に二つの登録条件が重なったことを示します。
提出前に、登録条件と3通りのリクエストを照合する
- ログから二つのクラス・メソッドと、最終的なHTTPメソッド・パスを特定した。
- 一覧と検索を一つの操作として扱えるかを、URLと応答の契約から決めた。
- 条件で分ける場合は、条件が重ならず、空の値の扱いも決めた。
- 修正後にコンテキストが起動し、パラメータなし・あり・空で、期待したハンドラーと結果になる。
Controllerがリクエストを受け取る流れを学びたい場合は、『作って学ぶ Spring Boot入門』の7.6節「コントローラークラス作成の基本」が参考になります。書籍はSpring Boot 4対応で、この記事の実行例はSpring Boot 3.5.16です。購入前に自分のプロジェクトの版を確認してください。
作って学ぶ Spring Boot入門
Spring Bootを、動くWebアプリを作りながら覚える。
Controller、画面、DB連携などを一つのアプリとして実装できます。Java基礎からSpringの現場へ進む橋渡しに向く一冊です。
- Spring Bootを手を動かして学びたい
- Webアプリ開発の流れをつかみたい
当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。
この記事とあわせて読みたい
まとめ
起動時の Ambiguous mapping は、ログに出た二つのメソッドと登録条件を突き合わせます。同じ一覧の絞り込みなら一つへまとめ、処理を分けるなら params に排他的な条件を書きます。起動と、各リクエストが意図したメソッドへ届くことを確認します。


