同じGETの経路が二つ登録され、起動時に衝突する問題を示すアイキャッチ

実装・エラー解決

Spring BootのAmbiguous mappingを直す|同じGETが重複して起動しないとき

注文一覧に「未処理の注文だけを表示する」検索を足したところ、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を収録しています。

サンプルZIPをダウンロード GitHubでコード全文と実行手順を見る

起動ログで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 から調べます。

関連記事Spring BootでBeanCreationExceptionが出たら|Caused byと失敗したBeanを確認 起動エラーの原因が別にあるとき、Caused byと失敗したBeanから調べる手順です。 記事を読む

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追加条件なし
同じ登録条件が2件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 /orders2件。ORD-101とORD-102list()
GET /orders?status=OPEN1件。ORD-101search(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入門」の表紙
商品画像:Amazon.co.jp
PR Java新人・若手向け

作って学ぶ Spring Boot入門

多田 真敏 (著)

Spring Bootを、動くWebアプリを作りながら覚える。

Controller、画面、DB連携などを一つのアプリとして実装できます。Java基礎からSpringの現場へ進む橋渡しに向く一冊です。

  • Spring Bootを手を動かして学びたい
  • Webアプリ開発の流れをつかみたい

当サイトはAmazonアソシエイト・プログラムの参加者です。価格・在庫・配送条件はAmazonでご確認ください。

関連記事Springの@RequestMappingの使い方|URL・HTTPメソッドと405・415・406の原因 起動後に405・415・406が返るとき、URL、HTTPメソッド、本文と応答の形式を確かめます。 記事を読む 関連記事Spring Bootで404 Not Foundになる原因|ControllerのURLが合わないときの確認順 起動後に404が返るとき、実際のURLとControllerの登録パスを比べます。 記事を読む

まとめ

起動時の Ambiguous mapping は、ログに出た二つのメソッドと登録条件を突き合わせます。同じ一覧の絞り込みなら一つへまとめ、処理を分けるなら params に排他的な条件を書きます。起動と、各リクエストが意図したメソッドへ届くことを確認します。

-実装・エラー解決
-, ,