Spring Boot 3.3.0无法识别MVC控制器，请求接口返回404

云原生阿岚

2026-6-22

Spring Boot 3.3.0 接口404问题排查与解决

问题描述

开发基于Spring Boot 3.3.0的应用，实体类存放于主应用包下的entities子包，控制器位于主应用包内的controllers子包。访问接口localhost:8080/account-types/create时返回404错误，错误提示：

There was an unexpected error (type=Not Found, status=404). No static resource account-types/account_type_create.

核心原因

错误提示显示Spring Boot在查找静态资源而非渲染模板，主要原因集中在以下几点：

缺少模板引擎依赖，导致无法识别模板文件
控制器误用@RestController注解，直接返回字符串而非触发模板渲染
控制器未被Spring扫描注册，导致接口映射不存在
模板文件路径/名称与控制器返回的视图名不匹配

解决方案

1. 添加模板引擎依赖

如果使用Thymeleaf（Spring Boot默认推荐的模板引擎），确保依赖已加入项目：
Maven（pom.xml）：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

Gradle（build.gradle）：

implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'

2. 修正控制器注解

确保控制器类使用@Controller而非@RestController——@RestController会将返回值直接作为JSON/文本响应，而@Controller才会触发视图解析器加载模板：

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;

@Controller
public class AccountTypeController {

    @GetMapping("/account-types/create")
    public String showCreateForm() {
        return "account_type_create";
    }
}

3. 确认组件扫描范围

主应用类的@SpringBootApplication注解默认扫描自身所在包及其子包，确保主应用类位于controllers和entities的父包下。例如：
主应用类在com.example.banking，则controllers包应为com.example.banking.controllers，entities包为com.example.banking.entities，保证Spring能扫描到控制器类。

4. 核对模板文件信息

确认account_type_create.html位于src/main/resources/templates目录下，文件名与控制器返回的视图名完全一致（大小写敏感）。

验证方法

重启应用后再次访问接口，若仍报错，查看启动日志中是否有类似以下的控制器注册日志：
Mapped "{[/account-types/create],methods=[GET]}" onto public java.lang.String com.example.banking.controllers.AccountTypeController.showCreateForm()
如果没有这条日志，说明控制器未被扫描注册，需检查包结构或手动添加@ComponentScan指定扫描范围。

内容的提问来源于stack exchange，提问作者sammyg7241

Spring Boot 3.3.0无法识别MVC控制器，请求接口返回404

问题描述 #

核心原因 #

解决方案 #

1. 添加模板引擎依赖 #

2. 修正控制器注解 #

3. 确认组件扫描范围 #

4. 核对模板文件信息 #

验证方法 #