SpringBoot常见错误排查手册：20个典型问题与解决方案

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

SpringBoot常见错误排查手册：20个典型问题与解决方案

一、依赖管理问题

1.1 依赖冲突

在Spring Boot项目中，依赖冲突是一个常见的问题。当不同的依赖引入了同一个库的不同版本时，就会产生冲突。

问题表现：项目启动时可能会抛出 NoClassDefFoundError、ClassNotFoundException 等异常。

解决方案：
可以使用 mvn dependency:tree（Maven项目）或 gradle dependencies（Gradle项目）命令查看依赖树，找出冲突的依赖。然后在 pom.xml（Maven）或 build.gradle（Gradle）中排除冲突的依赖。

示例（Maven）：

<dependency>
    <groupId>com.example</groupId>
    <artifactId>example-library</artifactId>
    <version>1.0.0</version>
    <exclusions>
        <exclusion>
            <groupId>conflicting-group</groupId>
            <artifactId>conflicting-artifact</artifactId>
        </exclusion>
    </exclusions>
</dependency>

1.2 依赖缺失

当项目中缺少必要的依赖时，会导致编译错误或运行时异常。

问题表现：编译时提示找不到类，或者运行时抛出 NoClassDefFoundError 异常。

解决方案：检查 pom.xml 或 build.gradle 文件，确保所有必要的依赖都已添加。

示例（Gradle）：

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-web'
    // 其他必要依赖
}

二、配置问题

2.1 配置文件加载失败

Spring Boot 支持多种配置文件格式，如 application.properties、application.yml 等。如果配置文件加载失败，会导致应用无法正常启动。

问题表现：启动时抛出 java.lang.IllegalStateException: Could not locate PropertySource 等异常。

解决方案：

• 检查配置文件的位置和命名是否正确，默认情况下，配置文件应放在 src/main/resources 目录下。
• 检查配置文件的语法是否正确，特别是 application.yml 文件，要注意缩进和冒号的使用。

2.2 配置属性注入失败

当使用 @Value 或 @ConfigurationProperties 注解进行属性注入时，可能会出现注入失败的情况。

问题表现：注入的属性值为 null 或默认值。

解决方案：

• 检查配置文件中属性的名称和格式是否正确。
• 确保 @ConfigurationProperties 注解的类上添加了 @Component 或其他 Spring 组件注解。

示例：

import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

@Component
@ConfigurationProperties(prefix = "myapp")
public class MyAppProperties {
    private String name;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }
}

三、数据库连接问题

3.1 数据库连接失败

当应用程序无法连接到数据库时，会导致数据访问失败。

问题表现：启动时抛出 java.sql.SQLException: Connection refused 等异常。

解决方案：

• 检查数据库服务是否正常启动。
• 检查数据库连接配置，如 spring.datasource.url、spring.datasource.username、spring.datasource.password 等是否正确。

3.2 数据库方言配置错误

在使用 Hibernate 等 ORM 框架时，需要正确配置数据库方言。

问题表现：执行 SQL 语句时可能会抛出 org.hibernate.MappingException: Unknown entity 等异常。

解决方案：检查 spring.jpa.database-platform 属性，确保其与使用的数据库类型匹配。

示例（application.properties）：

spring.jpa.database-platform=org.hibernate.dialect.MySQL8Dialect

四、Web 开发问题

4.1 请求映射错误

在使用 @RequestMapping、@GetMapping 等注解进行请求映射时，可能会出现映射错误的情况。

问题表现：访问 URL 时返回 404 错误。

解决方案：

• 检查请求映射的路径是否正确。
• 确保控制器类上添加了 @RestController 或 @Controller 注解。

示例：

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!";
    }
}

4.2 跨域问题

当前后端分离开发时，可能会遇到跨域问题。

问题表现：浏览器控制台报错 Access to XMLHttpRequest at 'http://example.com/api' from origin 'http://localhost:3000' has been blocked by CORS policy。

解决方案：
可以在控制器类上添加 @CrossOrigin 注解，或者配置全局的跨域处理。

示例（全局配置）：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.cors.CorsConfiguration;
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
import org.springframework.web.filter.CorsFilter;

@Configuration
public class CorsConfig {
    @Bean
    public CorsFilter corsFilter() {
        CorsConfiguration config = new CorsConfiguration();
        config.addAllowedOriginPattern("*");
        config.addAllowedHeader("*");
        config.addAllowedMethod("*");
        config.setAllowCredentials(true);

        UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
        source.registerCorsConfiguration("/**", config);

        return new CorsFilter(source);
    }
}

五、安全问题

5.1 Spring Security 配置错误

在使用 Spring Security 进行安全管理时，可能会出现配置错误的情况。

问题表现：访问受保护的资源时出现 403 或 401 错误。

解决方案：

• 检查 WebSecurityConfigurerAdapter 子类的配置是否正确。
• 确保用户认证和授权的配置符合需求。

示例：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http
           .authorizeRequests()
               .antMatchers("/public/**").permitAll()
               .anyRequest().authenticated()
               .and()
           .formLogin()
               .and()
           .httpBasic();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

5.2 密码加密问题

在进行用户认证时，密码加密是一个重要的环节。如果密码加密方式不正确，会导致认证失败。

问题表现：用户登录时提示密码错误。

解决方案：
确保使用相同的密码加密方式进行密码存储和验证。

示例：

import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;

public class PasswordExample {
    public static void main(String[] args) {
        PasswordEncoder encoder = new BCryptPasswordEncoder();
        String rawPassword = "password";
        String encodedPassword = encoder.encode(rawPassword);

        boolean isMatch = encoder.matches(rawPassword, encodedPassword);
        System.out.println("Password match: " + isMatch);
    }
}

六、日志问题

6.1 日志配置错误

Spring Boot 默认使用 Logback 作为日志框架，但如果日志配置错误，会导致日志输出不符合预期。

问题表现：日志文件未生成，或者日志级别配置无效。

解决方案：

• 检查 logback.xml 或 application.properties 中的日志配置是否正确。
• 确保日志文件的路径和权限设置正确。

示例（application.properties）：

logging.level.root=INFO
logging.file.name=myapp.log

6.2 日志性能问题

在高并发场景下，日志记录可能会影响应用的性能。

解决方案：

• 合理配置日志级别，避免不必要的日志输出。
• 考虑使用异步日志记录，如 Logback 的异步 Appender。

示例（logback.xml）：

<appender name="ASYNC" class="ch.qos.logback.classic.AsyncAppender">
    <appender-ref ref="FILE" />
</appender>

七、缓存问题

7.1 缓存配置错误

在使用 Spring Cache 进行缓存管理时，可能会出现配置错误的情况。

问题表现：缓存未生效，或者缓存数据不一致。

解决方案：

• 检查 @EnableCaching 注解是否添加到主应用类上。
• 确保缓存管理器的配置正确。

示例：

import org.springframework.cache.annotation.EnableCaching;
import org.springframework.context.annotation.Configuration;

@Configuration
@EnableCaching
public class CacheConfig {
    // 缓存管理器配置
}

7.2 缓存击穿问题

当缓存中某个热点数据过期时，大量请求同时访问该数据，会导致请求直接穿透缓存访问数据库，造成数据库压力过大。

解决方案：

• 可以使用分布式锁，确保只有一个请求去更新缓存。
• 设置热点数据永不过期，后台定时更新缓存。

八、定时任务问题

8.1 定时任务未执行

在使用 @Scheduled 注解创建定时任务时，可能会出现任务未执行的情况。

问题表现：定时任务没有按照预定的时间执行。

解决方案：

• 检查 @EnableScheduling 注解是否添加到主应用类上。
• 确保定时任务方法上的 @Scheduled 注解参数配置正确。

示例：

import org.springframework.scheduling.annotation.EnableScheduling;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;

@Component
@EnableScheduling
public class MyScheduledTask {
    @Scheduled(fixedRate = 5000)
    public void task() {
        System.out.println("Task executed");
    }
}

8.2 定时任务并发问题

如果定时任务的执行时间过长，可能会导致任务并发执行，影响系统性能。

解决方案：

• 可以使用 @Async 注解将定时任务异步执行。
• 调整定时任务的执行频率，避免任务重叠。

九、异常处理问题

9.1 全局异常处理器配置错误

在使用全局异常处理器处理异常时，可能会出现配置错误的情况。

问题表现：异常未被正确捕获和处理，返回的错误信息不符合预期。

解决方案：

• 检查全局异常处理器类是否添加了 @RestControllerAdvice 或 @ControllerAdvice 注解。
• 确保异常处理方法的参数和返回值类型正确。

示例：

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(Exception.class)
    public ResponseEntity<String> handleException(Exception e) {
        return new ResponseEntity<>("An error occurred: " + e.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
    }
}

9.2 自定义异常处理问题

在使用自定义异常时，可能会出现异常处理不当的情况。

解决方案：

• 确保自定义异常类继承自 Exception 或其子类。
• 在全局异常处理器中添加对自定义异常的处理方法。

十、部署问题

10.1 打包问题

在使用 Maven 或 Gradle 打包时，可能会出现打包失败的情况。

问题表现：执行 mvn package 或 gradle build 命令时出现错误。

解决方案：

• 检查项目的依赖是否正确，是否存在冲突。
• 检查 pom.xml 或 build.gradle 文件的配置是否正确。

10.2 部署环境问题

当将应用部署到生产环境时，可能会遇到各种环境问题。

问题表现：应用在开发环境正常运行，但在生产环境无法启动或出现异常。

解决方案：

• 检查生产环境的配置文件是否正确，如数据库连接、端口号等。
• 确保生产环境的 Java 版本和依赖与开发环境一致。