SpringBoot3整合MyBatisPlus启动报错解决方案-代码聚汇网

SpringBoot3整合MyBatisPlus启动报错解决方案

YM酱

1. 问题现象与背景分析

最近在SpringBoot3项目中整合MyBatisPlus时，遇到了一个典型的启动报错："Bean named 'ddlApplicationRunner' is expected to be of type 'org.sprin..."。这个错误看似简单，但背后涉及SpringBoot的自动配置机制、Bean类型检查以及MyBatisPlus的初始化流程等多个技术点。

从错误信息可以明确两点关键信息：

Spring容器中存在名为'ddlApplicationRunner'的Bean
但实际类型与预期类型不匹配

这个错误通常发生在项目启动阶段，此时Spring正在初始化各种自动配置的Bean。ddlApplicationRunner是SpringBoot数据访问层自动配置中的一个关键组件，负责执行数据库初始化脚本（DDL）。当它与MyBatisPlus的初始化流程产生冲突时，就会出现类型不匹配的问题。

2. 错误根源深度解析

2.1 SpringBoot自动配置机制

SpringBoot的自动配置是其核心特性之一。在启动时，它会根据classpath下的jar包自动配置各种Bean。对于数据访问层，关键的自动配置类包括：

DataSourceAutoConfiguration：数据源自动配置
DataSourceTransactionManagerAutoConfiguration：事务管理器配置
MybatisPlusAutoConfiguration：MyBatisPlus特有的自动配置

当这些自动配置类同时生效时，就可能产生Bean定义冲突。特别是MyBatisPlusAutoConfiguration会注册自己的DataSourceInitializer，这与SpringBoot默认的ddlApplicationRunner功能重叠。

2.2 MyBatisPlus初始化流程

MyBatisPlus在启动时会执行以下关键步骤：

初始化SqlSessionFactory
配置MyBatisPlus的全局配置（如分页插件、乐观锁等）
执行SQL脚本（如果配置了schema.sql或data.sql）

问题就出在第3步 - MyBatisPlus尝试用自己的方式执行DDL脚本，而SpringBoot也通过ddlApplicationRunner尝试做同样的事情，导致冲突。

2.3 类型不匹配的具体原因

深入查看错误堆栈，会发现Spring期望ddlApplicationRunner是org.springframework.boot.autoconfigure.jdbc.DataSourceInitializer类型，但实际获取到的可能是MyBatisPlus自定义的某个实现类。这种类型不匹配通常由以下原因导致：

Bean定义重复：两个自动配置类都定义了同名但不同类型的Bean
加载顺序问题：后加载的配置覆盖了先前的Bean定义
依赖冲突：不同版本的jar包导致类加载混乱

3. 解决方案与实操步骤

3.1 方案一：禁用SpringBoot默认的DDL执行

在application.properties中添加：

properties复制spring.sql.init.mode=never

或者在application.yml中：

yaml复制spring:
  sql:
    init:
      mode: never

这个配置会显式禁用SpringBoot默认的数据库初始化行为，让MyBatisPlus完全接管DDL执行。

注意：这种方式适用于你希望完全使用MyBatisPlus管理数据库初始化的情况。如果你还需要使用SpringBoot的schema.sql/data.sql机制，则不适合此方案。

3.2 方案二：排除冲突的自动配置

通过@SpringBootApplication注解排除冲突的自动配置类：

java复制@SpringBootApplication(exclude = {
    DataSourceAutoConfiguration.class,
    DataSourceTransactionManagerAutoConfiguration.class
})
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

这种方案更彻底，但需要手动配置数据源和事务管理器。适合对SpringBoot和MyBatisPlus有较深理解的开发者。

3.3 方案三：统一初始化方式

如果你希望保持SpringBoot的初始化方式，可以禁用MyBatisPlus的自动初始化：

在application.properties中：

properties复制mybatis-plus.global-config.db-config.schema=classpath:schema.sql
mybatis-plus.global-config.db-config.data=classpath:data.sql
mybatis-plus.global-config.db-config.auto-run=false

这样MyBatisPlus就不会尝试执行DDL，完全由SpringBoot的ddlApplicationRunner处理。

4. 完整排查流程与验证

4.1 诊断步骤

首先检查完整的错误堆栈，确认冲突的具体类和位置
使用--debug模式启动应用，查看自动配置报告
```
bash复制java -jar your-app.jar --debug
```
在日志中搜索"ddlApplicationRunner"，查看它的定义位置
检查依赖树，确认是否有冲突的依赖版本
```
bash复制mvn dependency:tree
```

4.2 依赖版本检查

确保使用兼容的版本组合：

SpringBoot 3.x
MyBatisPlus 3.5.x+

在pom.xml中应该类似这样：

xml复制<dependency>
    <groupId>com.baomidou</groupId>
    <artifactId>mybatis-plus-boot-starter</artifactId>
    <version>3.5.3.1</version>
</dependency>

4.3 配置验证

启动应用后，检查以下关键点：

数据源是否成功初始化
MyBatisPlus的mapper接口是否被正确扫描
控制台是否有SQL执行日志

5. 高级场景与定制方案

5.1 自定义DataSourceInitializer

如果需要更精细的控制，可以实现自定义的DataSourceInitializer：

java复制@Bean
public DataSourceInitializer customDataSourceInitializer(DataSource dataSource) {
    ResourceDatabasePopulator populator = new ResourceDatabasePopulator();
    populator.addScript(new ClassPathResource("schema.sql"));
    populator.addScript(new ClassPathResource("data.sql"));
    
    DataSourceInitializer initializer = new DataSourceInitializer();
    initializer.setDataSource(dataSource);
    initializer.setDatabasePopulator(populator);
    return initializer;
}

5.2 多数据源场景

在多数据源配置下，需要特别注意初始化顺序：

java复制@Primary
@Bean
public DataSourceInitializer primaryDataSourceInitializer(
    @Qualifier("primaryDataSource") DataSource dataSource) {
    // 主数据源初始化配置
}

@Bean
public DataSourceInitializer secondaryDataSourceInitializer(
    @Qualifier("secondaryDataSource") DataSource dataSource) {
    // 次数据源初始化配置
}

6. 常见问题与解决方案

6.1 问题一：配置不生效

现象：按照上述方案配置后，错误仍然出现。

排查步骤：

确认配置文件的加载顺序（application.properties > application.yml）
检查是否有@Profile注解影响了配置加载
使用IDE的"Find Usages"功能搜索ddlApplicationRunner

解决方案：
在启动类上添加：

java复制@EnableAutoConfiguration(excludeName = {
    "org.springframework.boot.autoconfigure.jdbc.DataSourceInitializerInvoker"
})

6.2 问题二：SQL脚本执行失败

现象：错误解决后，SQL脚本没有执行或执行报错。