Spring Bootの404 Not Foundについて、ControllerのURLとRequestMappingの確認順を解説する記事のアイキャッチ。

実装・エラー解決

Spring Bootの404原因|Controller・URL・context-pathを切り分ける

AIによる要約

Spring Bootの404 Not Foundは、Mappingや静的リソースの未検出に加え、データ未存在をアプリが404へ変換する場合もあるため、Controllerへの到達の有無を分けて確認します。まずブラウザやAPIクライアントが実際に送ったURLとHTTPメソッドを確認し、次にクラスとメソッドのRequestMappingを連結した完成URL、context-path、ControllerのBean登録を確認します。Controllerへ到達した後の例外は通常500であり、GETとPOSTだけが違う場合は405です。エラー画面の見た目ではなく、ステータスコード、アクセスログ、ブレークポイント、MockMvcテストを使って切り分けます。

新人SE
新人SE
Controllerは書いたのに、ブラウザから開くと404になります。どこから確認すればよいですか?
ポンコツSE
ポンコツSE
最初に見るのはJavaコードではなく、実際に送信されたURLとHTTPメソッドです。その後にMappingを連結して比べます。

Spring Bootの画面やAPIを追加した直後に、404 Not FoundやWhitelabel Error Pageが表示されることがあります。新人の現場では「Controllerが動いていない」と考えてServiceやRepositoryまで読み始めがちですが、まずControllerのメソッドへ到達しているかを切り分けます。

確認対象を広げすぎると、単純なURLの1文字違いに長時間使ってしまいます。この記事では、Spring MVCのリクエストがどのControllerへ割り当てられるかを理解し、現場で再現しやすい順番に原因を切り分けます。

この記事のポイント

  • 404はMapping未到達とデータ未存在を分けて確認する
  • クラスとメソッドのMappingを連結して完成URLを確認する
  • GETとPOSTの違いは404ではなく405になることがある
  • Controllerがコンポーネントスキャン対象か確認する
  • context-pathやリバースプロキシ配下のパスを見落とさない
  • MockMvcで正しいURLと誤ったURLの両方をテストする

このController一式で、404・405・400を実行する

Java 17・Maven 3.9系・Spring Boot 3.5.16。架空の利用者ID10を返すAPIです。Controller、Service、JSONの型、起動クラス、設定、テスト、READMEの8ファイルを収録しました。DB・ログインは不要です。

本文のAPI例はこの一式に対応します。画面用のOrderControllerとReportController、プロキシ構成は後述の説明用抜粋であり、このZIPには含めません。

Spring Bootの404 Not Foundとは

HTTP 404は、クライアントが指定した場所に対応するものが見つからないことを表します。Spring MVCでは、URL、HTTPメソッド、パラメータ、ヘッダー、Content-Typeなどを使って、リクエストをControllerのメソッドへ割り当てます。

まず、配布一式のsrc/main/java/info/syachiku/controller404/UserController.javaの全文を見ます。UserServiceをコンストラクタで受け取るので、未定義の変数へ処理を投げている例ではありません。

package info.syachiku.controller404;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users")
public class UserController {
    private final UserService userService;

    public UserController(UserService userService) {
        this.userService = userService;
    }

    @GetMapping("/{id}")
    public UserResponse findById(@PathVariable("id") Long id) {
        return userService.findById(id);
    }
}

完成するURLは/api/users/{id}です。IDが10なら、GETで/api/users/10へアクセスします。/users/10や/api/user/10では一致しません。

404を見たら、まず「Controllerの中で何が失敗したか」ではなく、「そのControllerが選ばれたか」を確認します。

このサンプルのapplication.propertiesにはserver.servlet.context-path=/salesがあります。そのため、実際に呼ぶ完成URLはhttp://127.0.0.1:18027/sales/api/users/10です。ここまでの/api/users/{id}はControllerのMapping部分で、文脈パスを含みません。

依存先と返すJSONも同じZIPにあります。UserServiceはID10だけを返し、それ以外はデータ未存在として404にします。calls()は教材用の到達確認で、実業務用の公開APIではありません。

UserService.javaの全文:検索に到達した回数を記録する
package info.syachiku.controller404;

import java.util.concurrent.atomic.AtomicInteger;
import org.springframework.http.HttpStatus;
import org.springframework.stereotype.Service;
import org.springframework.web.server.ResponseStatusException;

@Service
public class UserService {
    private final AtomicInteger calls = new AtomicInteger();

    public UserResponse findById(Long id) {
        calls.incrementAndGet();
        if (id == 10L) {
            return new UserResponse(10L, "Tanaka");
        }
        throw new ResponseStatusException(HttpStatus.NOT_FOUND, "user not found");
    }

    // 教材の到達確認用。実業務では適切なログや監視を使う。
    public int calls() {
        return calls.get();
    }

    public void resetCalls() {
        calls.set(0);
    }
}
UserResponse.javaの全文:JSONのidとname
package info.syachiku.controller404;

public record UserResponse(Long id, String name) {
}
Application.javaの全文:同じパッケージ配下を起動する
package info.syachiku.controller404;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
pom.xmlの全文:Java・Spring Boot・JUnitの実行設定
<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>controller-404</artifactId>
    <version>1.0.0</version>
    <properties><java.version>17</java.version></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>

最初に実際のURLとHTTPメソッドを確認する

設計書に書かれたURLや、自分が呼んだつもりのURLではなく、実際に送信されたリクエストを確認します。ブラウザなら開発者ツールのNetwork、PostmanなどのAPIクライアントなら履歴、フロントエンドなら通信ログを見ます。

  • ホスト名とポートは正しいか
  • URLの単数形・複数形は合っているか
  • 大文字小文字やハイフンを間違えていないか
  • パス変数を入れ忘れていないか
  • GET、POST、PUT、DELETEは合っているか
  • 末尾へ余計なパスを付けていないか

画面のリンクとControllerを別の担当者が実装している場合、両方がそれぞれ正しそうに見えても、URLの契約がずれていることがあります。レビューでは片側だけでなく、呼び出し元と受け取り側を並べて確認します。

RequestMappingとGetMappingを連結する

SpringのMappingは、クラス単位とメソッド単位に分かれていることがあります。メソッドの@GetMappingだけを見てURLを判断しないでください。

次のOrderControllerは、URLとView名の違いを説明する抜粋です。orderServiceや画面テンプレートは省略しており、配布APIの実行対象には含めません。/admin/ordersと/detail/{orderId}を連結する点を見てください。

@Controller
@RequestMapping("/admin/orders")
public class OrderController {

    @GetMapping("/detail/{orderId}")
    public String detail(
            @PathVariable Long orderId,
            Model model) {
        model.addAttribute("order", orderService.find(orderId));
        return "order/detail";
    }
}

この場合のURLは/admin/orders/detail/{orderId}です。戻り値のorder/detailはThymeleafなどのテンプレート名であり、アクセスURLではありません。URLとView名を混同すると、存在しないパスへアクセスして404になります。

クラスとメソッドのパスを連結できたら、実際に送ったURLの末尾も照合します。GETで末尾の/を付けたときだけ404になるなら、1文字だけ変えたリクエストで確かめます。

関連記事Springの@RequestMappingの使い方|条件指定と405・415・406 末尾の「/」だけを変えたGETの200と404を比べます。URLを揃える方法と、両方を同じメソッドで受け付ける設定を実行できます。 記事を読む

PathVariableの数と位置も確認する

@GetMapping("/{companyId}/users/{userId}")なら、会社IDと利用者IDの両方が必要です。片方をクエリパラメータとして送っても、パスの形が一致しません。

正しい例:
GET /api/companies/10/users/25

誤った例:
GET /api/companies/users/25?companyId=10

404・405・400・500を分けて考える

ステータス代表的な状態最初の確認
404URLに対応するハンドラがないパス、Mapping、Bean登録
405URLはあるがHTTPメソッドが違うGET・POST・PUT・DELETE
400型変換、必須値、JSONなどが不正入力値、Content-Type
500処理中に未処理例外が発生ログ、Caused by、Service・DB

ステータスコードを分けるだけで、読むべき範囲が変わります。404なのにServiceのSQLを調べたり、500なのにURLだけを変更したりすると、調査が遠回りになります。

ControllerがBean登録されているか確認する

URLが正しくても、ControllerクラスがSpringの管理対象でなければMappingは登録されません。代表例は、@Controllerや@RestControllerの付け忘れです。

配布コードでも同じ入口を試せます。検証用コピーのUserControllerから@RestControllerという1行だけを外し、mvn test '-Dtest=UserControllerTest#actualHttpDistinguishesRouteMethodInputAndMissingData'を実行します。Mappingを残していても、H01はstatus=404 service=0になります。この構成ではControllerとして登録されず、検索へ進まないためです。H01・H04・H05・H07の4件が失敗します。アノテーションを戻した後にmvn clean testで全9件を通します。実プロジェクトでどのBeanが登録されたかは、その環境のログや設定から別途確認してください。

次のReportController2例はアノテーションの有無を比較する抜粋です。report/listの画面を動かす教材ではなく、今回のZIPにも含めません。実行するUserControllerは@RestController付きで、起動クラスと同じパッケージ配下です。

// NG: 普通のJavaクラスなのでSpring MVCへ登録されない
public class ReportController {

    @GetMapping("/reports")
    public String list() {
        return "report/list";
    }
}
// OK: SpringのControllerとして登録される
@Controller
public class ReportController {

    @GetMapping("/reports")
    public String list() {
        return "report/list";
    }
}

もう一つ多いのが、起動クラスのパッケージ配下からControllerが外れているケースです。通常の@SpringBootApplicationは、そのクラスが置かれたパッケージを基準にコンポーネントスキャンします。

com.example.app
├── Application.java        // 起動クラス
├── controller              // 通常はスキャン対象
└── service

com.example.external
└── ReportController.java   // 設定次第では対象外

場当たり的にscanBasePackagesを広げる前に、プロジェクトのパッケージ構成と既存Controllerの置き場所へ合わせるのが安全です。

context-pathとプロキシ配下のパスを確認する

ローカルでは動くのに結合環境だけ404になる場合、アプリケーションの前にロードバランサー、Webサーバー、API Gatewayなどが置かれていることがあります。また、Spring Boot側でcontext-pathを設定している場合もあります。

server.address=127.0.0.1
server.port=18027
server.servlet.context-path=/sales

この設定があると、ControllerのMappingが/api/ordersでも、アプリケーションへ直接アクセスするときのURLは/sales/api/ordersになります。環境ごとの設定ファイル、起動引数、環境変数も確認します。

同じアプリへ7通り送ると、どこで止まったかを比較できます。ZIPを展開し、pom.xmlのある場所で次を実行します。初回の依存取得にはネット接続が必要です。18027番が使用中ならREADMEのポート変更手順を使い、他のアプリを終了させないでください。

mvn spring-boot:run

起動ログを確認したら、別の端末Bで上から順に送ります。各レスポンスの先頭行を見ると、200・404・404・405・400・404・404です。最初は{"id":10,"name":"Tanaka"}が返り、POSTのAllowにはGETが入ります。

curl -i http://127.0.0.1:18027/sales/api/users/10
curl -i http://127.0.0.1:18027/sales/api/user/10
curl -i http://127.0.0.1:18027/sales/api/users
curl -i -X POST http://127.0.0.1:18027/sales/api/users/10
curl -i http://127.0.0.1:18027/sales/api/users/abc
curl -i http://127.0.0.1:18027/api/users/10
curl -i http://127.0.0.1:18027/sales/api/users/999
ケースHTTPパス期待ステータスService到達
H01GET/sales/api/users/102001回
H02GET/sales/api/user/104040回
H03GET/sales/api/users4040回
H04POST/sales/api/users/10405 / AllowにGET0回
H05GET/sales/api/users/abc4000回
H06GET/api/users/104040回
H07GET/sales/api/users/9994041回

H02はusersのs、H03はID、H06は/salesが欠けています。H05はパスの形が合ってもabcをLongへ変換できず、Serviceへ進みません。H07は検索したうえでID999が未存在なので404です。404だけを見て「Controllerに未到達」とは断定できません。到達回数は後述のJUnitで照合します。curlだけでは内部の回数は表示されません。

これはアプリへ直接送る確認です。実プロキシによるパスの付け替え、認証フィルター、画面テンプレートの有無まで確認した例ではありません。実機のエラー本文はAcceptやサーバーによって異なるため、本文の文言ではなくステータスと到達を基準にします。終了は端末AでCtrl+Cです。

注意

本番環境の404だけを見てControllerを変更すると、プロキシのパス変換と二重に修正してしまうことがあります。ブラウザから見えるURL、プロキシが転送するURL、Springが受け取るURLを分けて記録してください。

静的ファイル・画面テンプレート・APIを混同しない

同じ404でも、対象が何かで確認場所が違います。

  • API: ControllerのMappingを確認する
  • CSS・JavaScript・画像: src/main/resources/staticなどの配置を確認する
  • Thymeleaf画面: Controllerの戻り値とtemplates配下のファイル名を確認する
  • DB上のデータ: URLは合っていても、未存在を意図的に404へ変換している場合がある

「404だからControllerがない」と決めつけず、レスポンス本文、ログ、対象URLの役割を見ます。データ未存在をResponseStatusException(HttpStatus.NOT_FOUND)へ変換している設計なら、Controllerへ到達した後でも404になります。

MockMvcでMappingを固定する

URLの契約はテストで固定できます。正常なURLが200になることだけでなく、HTTPメソッドや必須パスを間違えた場合のステータスも確認すると、改修時のMapping変更に気づきやすくなります。

配布のsrc/test/java/info/syachiku/controller404/UserControllerTest.javaは、実Tomcatへ送る7件と、同じSpringコンテキストを使うMockMvc2件の計9件です。以下はテストファイルの全文です。clearObservation()で毎回到達回数をリセットし、他のケースの呼び出しを混ぜません。

MockMvcのcontextPath("/sales")は擬似リクエストの設定です。これだけで実サーバーの配備先を確認したことにはならないため、実HTTPのH01とH06でも文脈パスの有無を比べています。

UserControllerTest.javaの全文:7つの実HTTPと2つのMockMvc
package info.syachiku.controller404;

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import com.fasterxml.jackson.databind.ObjectMapper;
import org.junit.jupiter.api.BeforeEach;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.params.ParameterizedTest;
import org.junit.jupiter.params.provider.CsvSource;
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.boot.test.web.server.LocalServerPort;
import org.springframework.test.web.servlet.MockMvc;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@AutoConfigureMockMvc
class UserControllerTest {
    @LocalServerPort
    private int port;
    @Autowired
    private MockMvc mockMvc;
    @Autowired
    private UserService userService;
    @Autowired
    private ObjectMapper objectMapper;

    private final HttpClient client = HttpClient.newHttpClient();

    @BeforeEach
    void clearObservation() {
        userService.resetCalls();
    }

    @ParameterizedTest(name = "{0}: {1} {2} -> {3}, service={4}")
    @CsvSource({
        "H01, GET,  /sales/api/users/10,  200, 1",
        "H02, GET,  /sales/api/user/10,   404, 0",
        "H03, GET,  /sales/api/users,     404, 0",
        "H04, POST, /sales/api/users/10,  405, 0",
        "H05, GET,  /sales/api/users/abc, 400, 0",
        "H06, GET,  /api/users/10,        404, 0",
        "H07, GET,  /sales/api/users/999, 404, 1"
    })
    void actualHttpDistinguishesRouteMethodInputAndMissingData(
            String caseId, String method, String path, int expectedStatus, int expectedCalls)
            throws Exception {
        var request = HttpRequest.newBuilder(URI.create("http://127.0.0.1:" + port + path))
                .header("Accept", "application/json")
                .method(method, HttpRequest.BodyPublishers.noBody()).build();
        var response = client.send(request, HttpResponse.BodyHandlers.ofString());

        System.out.printf("%s %s %s status=%d service=%d%n",
                caseId, method, path, response.statusCode(), userService.calls());

        assertEquals(expectedStatus, response.statusCode(), caseId);
        assertEquals(expectedCalls, userService.calls(), caseId);
        if (expectedStatus == 200) {
            var json = objectMapper.readTree(response.body());
            assertEquals(10L, json.get("id").longValue());
            assertEquals("Tanaka", json.get("name").textValue());
        }
        if (expectedStatus == 405) {
            assertTrue(response.headers().firstValue("Allow").orElse("").contains("GET"));
        }
    }

    @Test
    void mockMvcCallsRegisteredControllerWithExplicitContextPath() throws Exception {
        mockMvc.perform(get("/sales/api/users/{id}", 10L).contextPath("/sales"))
                .andExpect(status().isOk())
                .andExpect(jsonPath("$.id").value(10))
                .andExpect(jsonPath("$.name").value("Tanaka"));
        assertEquals(1, userService.calls());
    }

    @Test
    void mockMvcWrongUrlDoesNotCallService() throws Exception {
        mockMvc.perform(get("/sales/api/user/{id}", 10L).contextPath("/sales"))
                .andExpect(status().isNotFound());
        assertEquals(0, userService.calls());
    }
}

同じ展開フォルダーで実行します。テスト用アプリの起動時に空きポートが割り当てられ、9ケースは同じ起動中のアプリを使います。手動起動用18027番とは別です。

mvn clean test
H01 GET /sales/api/users/10 status=200 service=1
H02 GET /sales/api/user/10 status=404 service=0
H03 GET /sales/api/users status=404 service=0
H04 POST /sales/api/users/10 status=405 service=0
H05 GET /sales/api/users/abc status=400 service=0
H06 GET /api/users/10 status=404 service=0
H07 GET /sales/api/users/999 status=404 service=1
[INFO] Tests run: 9, Failures: 0, Errors: 0, Skipped: 0

さらに検証用コピーだけで、UserControllerの@RequestMapping("/api/users")を/api/userへ変えて実行すると、H01・H02・H04・H05・H07とMockMvc2件、計7件が失敗します。H03とH06は元から未到達なので成功のままです。元へ戻し、全9件が成功することまで確認してください。正とするAPI仕様へ、呼び出し側とControllerのどちらを合わせるかを判断するための比較です。

文字列を手入力する箇所が複数ある場合は、API仕様やフロント側の定数との整合も確認します。ただし、URL定数を共通化しすぎて変更箇所が見えなくなる場合もあるため、既存プロジェクトの方針へ合わせます。

現場で使える404の確認順

  1. NetworkやAPIクライアントで実際のURLとHTTPメソッドを記録する
  2. ステータスが本当に404か確認する
  3. クラスとメソッドのMappingを連結する
  4. context-pathとプロキシの転送パスを加える
  5. Controllerへブレークポイントを置いて到達有無を見る
  6. ControllerがBean登録・スキャンされているか確認する
  7. 静的ファイル、テンプレート、データ未存在を切り分ける
  8. MockMvcで再現する

コードレビューで伝えるコメント例

「URLが間違っています」だけでは、呼び出し側とControllerのどちらを直すべきか分かりません。契約と根拠を含めて伝えます。

画面は/admin/order/detail/10を呼んでいますが、Controllerの完成URLは/admin/orders/detail/10です。API仕様書では複数形のordersになっているため、画面側のリンクを合わせる認識でよいでしょうか。あわせてMockMvcへ正常URLのテストを追加したいです。

この書き方なら、現象、差分、正とする根拠、再発防止が一度に伝わります。

提出前のセルフチェック

レビュー前に確認すること

  • 実際のURLとHTTPメソッドを確認したか
  • クラスとメソッドのMappingを連結したか
  • PathVariableの数と順番が合っているか
  • context-pathを含めたか
  • Controllerへ到達しているか
  • ControllerがBean登録されているか
  • 静的ファイルとView名をURLと混同していないか
  • 404と405・400・500を区別したか
  • 正常URLをMockMvcでテストしたか
  • 環境固有のプロキシ設定を確認したか

Spring MVCを体系的に確認する参考書

404の原因調査では、Controllerのアノテーションだけでなく、リクエストがSpring MVCへ届いてからメソッドへ割り当てられる流れを理解していると判断が速くなります。

書籍「作って学ぶ Spring Boot入門」の表紙
商品画像:Amazon.co.jp
PR Java新人・若手向け

作って学ぶ Spring Boot入門

多田 真敏 (著)

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

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

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

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

この記事とあわせて読みたい

関連記事Spring Bootの@GetMappingと@PostMappingの違い|@RequestMappingとの使い分け URLが同じでもHTTPメソッドが違う場合の設計と405を整理します。 記事を読む 関連記事Spring Bootで400 Bad Requestになる原因|Controllerに値が入らない時の確認順 URLは合っているのに入力変換で失敗する場合の確認順を解説します。 記事を読む 関連記事Spring Bootの@Controllerと@RestControllerの違い|画面とJSONで使い分ける Viewを返すControllerとAPIのURL設計を混同しないための基準です。 記事を読む

まとめ

Spring Bootの404 Not Foundでは、実際に送信されたURLとHTTPメソッドを最初に確認します。クラスとメソッドのMapping、PathVariable、context-pathを組み合わせた完成URLと比較してください。

URLが合っている場合は、ControllerのBean登録、コンポーネントスキャン、プロキシ設定、静的ファイルやテンプレートの配置へ進みます。404、405、400、500を分け、ブレークポイントとMockMvcでControllerへの到達を確認すれば、調査範囲を必要以上に広げずに済みます。

Spring MVCのMapping仕様はSpring Framework公式ドキュメントでも確認できます。

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