SpringBoot常见错误排查手册：启动失败到接口404的解决方案

🎓博主介绍：Java、Python、js全栈开发 “多面手”，精通多种编程语言和技术，痴迷于人工智能领域。秉持着对技术的热爱与执着，持续探索创新，愿在此分享交流和学习，与大家共进步。
📖DeepSeek-行业融合之万象视界(附实战案例详解100+)
📖全栈开发环境搭建运行攻略：多语言一站式指南(环境搭建+运行+调试+发布+保姆级详解)
👉感兴趣的可以先收藏起来，希望帮助更多的人

SpringBoot常见错误排查手册：启动失败到接口404的解决方案

一、Spring Boot启动失败问题排查

1. 依赖冲突问题

在Spring Boot项目中，依赖冲突是导致启动失败的常见原因之一。当多个依赖引入了相同库的不同版本时，就可能出现冲突。

1.1 症状表现

启动时抛出 ClassNotFoundException、NoClassDefFoundError 等异常。例如，以下异常信息表明找不到某个类：

java.lang.ClassNotFoundException: com.example.SomeClass

1.2 排查方法

可以使用Maven的 dependency:tree 命令来查看项目的依赖树，找出冲突的依赖。在项目根目录下执行以下命令：

mvn dependency:tree

执行后，会输出项目的依赖树，从中可以看到每个依赖的版本信息。

1.3 解决方案

使用 <exclusions> 标签排除冲突的依赖。例如，如果 spring-boot-starter-web 引入了 log4j 的冲突版本，可以在 pom.xml 中添加如下配置：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.apache.logging.log4j</groupId>
            <artifactId>log4j</artifactId>
        </exclusion>
    </exclusions>
</dependency>

2. 配置文件问题

配置文件错误也可能导致Spring Boot启动失败。

2.1 症状表现

启动时抛出 org.springframework.boot.context.properties.bind.BindException 等异常，提示配置文件绑定失败。

2.2 排查方法

检查配置文件的语法是否正确，特别是YAML文件，要注意缩进和冒号的使用。例如，以下YAML配置是错误的：

server:
port: 8080

正确的配置应该是：

server:
  port: 8080

2.3 解决方案

仔细检查配置文件的语法，确保每个配置项的缩进和格式正确。如果使用的是 application.properties 文件，要注意键值对的格式。

3. 端口被占用问题

当Spring Boot应用程序尝试使用的端口已经被其他程序占用时，启动会失败。

3.1 症状表现

启动时抛出 java.net.BindException: Address already in use 异常。

3.2 排查方法

在Windows系统中，可以使用 netstat -ano | findstr :端口号 命令来查看端口占用情况。例如，查看8080端口的占用情况：

netstat -ano | findstr :8080

在Linux系统中，可以使用 lsof -i :端口号 命令。例如：

lsof -i :8080

3.3 解决方案

可以通过修改Spring Boot应用程序的端口来解决。在 application.properties 中添加如下配置：

server.port=8081

或者在 application.yaml 中添加：

server:
  port: 8081

二、接口404问题排查

1. 控制器映射问题

接口404错误可能是由于控制器的映射配置不正确导致的。

1.1 症状表现

访问接口时返回404状态码，控制台没有明显的错误信息。

1.2 排查方法

检查控制器类和方法的注解是否正确。例如，以下是一个简单的控制器示例：

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

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

确保 @RestController 和 @GetMapping 等注解使用正确，映射路径与访问路径一致。

1.3 解决方案

仔细检查控制器的注解和映射路径，确保路径没有拼写错误。如果使用了 @RequestMapping 注解，要注意其 method 属性的设置。

2. 组件扫描问题

Spring Boot默认会扫描主应用程序类所在包及其子包下的组件。如果控制器类不在扫描范围内，就会导致接口404。

2.1 症状表现

访问接口时返回404状态码，控制器类中的方法没有被调用。

2.2 排查方法

检查主应用程序类的位置，确保控制器类在其所在包或子包下。如果需要指定扫描的包，可以使用 @ComponentScan 注解。例如：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan(basePackages = "com.example.controllers")
public class MyApplication {

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

2.3 解决方案

将控制器类移动到主应用程序类所在包或子包下，或者使用 @ComponentScan 注解指定扫描的包。

3. 过滤器和拦截器问题

过滤器和拦截器可能会拦截请求，导致接口404。

2.1 症状表现

访问接口时返回404状态码，请求没有到达控制器方法。

2.2 排查方法

检查过滤器和拦截器的配置，确保它们不会拦截需要访问的接口。例如，以下是一个简单的拦截器示例：

import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@Component
public class MyInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 可以在这里添加拦截逻辑
        return true;
    }
}

在配置拦截器时，要注意排除不需要拦截的路径：

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Autowired
    private MyInterceptor myInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(myInterceptor)
               .addPathPatterns("/**")
               .excludePathPatterns("/hello");
    }
}

2.3 解决方案

检查过滤器和拦截器的配置，排除不需要拦截的接口路径。