Spring Boot外部定义的RestController无法访问，求助问题原因

首次使用Java和Spring Boot跟随教程开发，在com.example.demo.user包下创建了UserController类并定义接口，代码如下：

package com.example.demo.user;

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

import java.util.List;

@RestController
@RequestMapping(path = "/api/v1/user")
public class UserController {
    @GetMapping("/")
    public List<User> hello() {
        User myUser = new User(5000, 1, 1);
        return List.of(myUser);
    }
}

User包中还包含带getter、setter和构造方法的User类。启动类DemoApplication.java与User包处于同一层级（包路径com.example.demo），代码如下：

package com.example.demo;

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

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

预期访问http://localhost:8080/api/v1/user/能得到[User]格式的响应，但实际返回404 Not Found。当把接口定义在DemoApplication.java中时，代码如下，接口可正常工作：

package com.example.demo;

import com.example.demo.user.User;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import java.util.List;

@SpringBootApplication
@RestController
@RequestMapping(path = "/api/v1/user")
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
    @GetMapping("/")
    public List<User> hello() {
        User myUser = new User(5000, 1, 1);
        return List.of(myUser);
    }
}

排查方向与原因 #

核心问题出在Spring Boot的组件扫描范围：@SpringBootApplication注解包含@ComponentScan，默认仅扫描启动类所在包及其所有子包下的组件（包括@RestController标记的控制器）。你的UserController在com.example.demo.user子包，理论上应该被扫描到，但可能存在以下异常情况：

• 项目结构错误：确认UserController文件路径是src/main/java/com/example/demo/user/UserController.java，而非src/test/java或其他非源码目录，否则不会被Spring加载。
• 编译失败：检查IDE的编译输出目录（如target/classes），确认UserController.class已生成。如果存在语法错误、依赖缺失等问题导致编译失败，Spring容器无法识别该控制器。
• 自定义扫描范围覆盖：如果启动类额外添加了@ComponentScan并指定了特定包，可能覆盖默认扫描规则，导致子包未被包含。
• 注解导入错误：确保UserController上的@RestController是org.springframework.web.bind.annotation.RestController，而非其他同名注解。

解决方法 #

1. 核对项目结构，确保控制器位于正确的源码目录下，且编译正常。
2. 若扫描范围确实存在问题，可在启动类显式指定扫描包：

   @SpringBootApplication(scanBasePackages = "com.example.demo")
   

   或指定具体的类：

   @SpringBootApplication(scanBasePackageClasses = {DemoApplication.class, UserController.class})
   

内容的提问来源于stack exchange，提问作者Arda Cüce