Spring Boot 3整合MyBatis常见错误与解决方案-代码聚汇网

Spring Boot 3整合MyBatis常见错误与解决方案

Tina 小姐姐

1. 问题现象与背景分析

最近在IntelliJ IDEA中使用Spring Boot 3整合MyBatis时，遇到了一个典型错误："Property 'sqlSessionFactory' or 'sqlSessionTemplate' are required"。这个错误通常发生在Spring容器尝试初始化MyBatis相关Bean时，无法正确注入这两个核心组件之一。根据我的项目经验，这往往意味着MyBatis的自动配置未能按预期工作。

1.1 错误发生的典型场景

这个报错通常出现在以下几种情况：

使用Spring Boot 3.x版本但MyBatis starter版本未同步升级
项目依赖中存在版本冲突
数据源配置不完整或错误
MyBatis的Mapper扫描配置有问题

在控制台看到的完整错误堆栈通常会包含这样的关键信息：

code复制org.springframework.beans.factory.BeanCreationException: 
Error creating bean with name 'xxxMapper' defined in file [xxx.class]:
Invocation of init method failed; nested exception is java.lang.IllegalArgumentException: 
Property 'sqlSessionFactory' or 'sqlSessionTemplate' are required

1.2 核心组件的作用解析

理解这个错误需要先明确几个关键组件的作用：

sqlSessionFactory：MyBatis的核心工厂类，负责创建SqlSession实例。它需要数据源(DataSource)和MyBatis配置信息来初始化。
sqlSessionTemplate：Spring与MyBatis整合的关键类，实现了SqlSession接口，负责管理MyBatis的SqlSession生命周期，并与Spring事务管理集成。
Mapper接口：我们的DAO层接口，运行时由MyBatis动态生成实现类，这些实现类需要依赖sqlSessionTemplate或sqlSessionFactory来执行SQL操作。

2. 问题排查与解决方案

2.1 版本兼容性检查

Spring Boot 3.x基于Spring Framework 6.x，这是一个重大版本升级，带来了不少破坏性变更。根据我的实践，最常见的错误原因就是版本不兼容。

检查步骤：

确认pom.xml中Spring Boot版本：

xml复制<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.1.0</version> <!-- 确保是3.x版本 -->
</parent>

检查MyBatis starter版本：

xml复制<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>3.0.2</version> <!-- 必须使用3.x版本 -->
</dependency>

重要提示：MyBatis Spring Boot Starter 2.x系列不支持Spring Boot 3.x。如果错误地使用了2.2.2等旧版本，就会出现本文讨论的错误。

2.2 完整配置示例

一个能正常工作的基础配置应该包含以下内容：

数据源配置(application.yml)：

yaml复制spring:
  datasource:
    url: jdbc:mysql://localhost:3306/your_db
    username: root
    password: your_password
    driver-class-name: com.mysql.cj.jdbc.Driver

Mapper扫描配置：

java复制@MapperScan("com.example.mapper") // 替换为你的Mapper接口所在包
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

必要的依赖：

xml复制<dependencies>
    <!-- Spring Boot Starter -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
    </dependency>
    
    <!-- MyBatis Starter -->
    <dependency>
        <groupId>org.mybatis.spring.boot</groupId>
        <artifactId>mybatis-spring-boot-starter</artifactId>
        <version>3.0.2</version>
    </dependency>
    
    <!-- JDBC Driver -->
    <dependency>
        <groupId>com.mysql</groupId>
        <artifactId>mysql-connector-j</artifactId>
        <scope>runtime</scope>
    </dependency>
</dependencies>

2.3 常见配置错误排查

如果版本正确但仍然报错，可以检查以下几个方面：

数据源配置是否正确：
- 确保spring.datasource下的url、username、password正确
- 测试数据源是否能正常连接
Mapper扫描是否生效：
- 确认@MapperScan注解的包路径正确
- 检查Mapper接口是否添加了@Mapper注解(如果没使用@MapperScan)
依赖冲突检查：
- 执行mvn dependency:tree查看依赖树
- 检查是否有不同版本的mybatis或mybatis-spring共存
MyBatis配置是否正确：
- 检查是否有mybatis.mapper-locations配置(如果需要XML映射文件)
- 确认mybatis.configuration下的配置项正确

3. 高级问题分析与解决

3.1 多数据源场景下的特殊处理

当项目需要配置多个数据源时，需要手动配置sqlSessionFactory和sqlSessionTemplate：

java复制@Configuration
public class MyBatisConfig {
    
    @Bean(name = "dataSource1")
    @ConfigurationProperties(prefix = "spring.datasource.one")
    public DataSource dataSource1() {
        return DataSourceBuilder.create().build();
    }
    
    @Bean(name = "sqlSessionFactory1")
    public SqlSessionFactory sqlSessionFactory1(@Qualifier("dataSource1") DataSource dataSource) throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dataSource);
        // 其他配置...
        return sessionFactory.getObject();
    }
    
    @Bean(name = "sqlSessionTemplate1")
    public SqlSessionTemplate sqlSessionTemplate1(@Qualifier("sqlSessionFactory1") SqlSessionFactory sqlSessionFactory) {
        return new SqlSessionTemplate(sqlSessionFactory);
    }
}

然后在Mapper接口上使用@Qualifier指定使用哪个sqlSessionTemplate：

java复制@Mapper
public interface UserMapper {
    @Qualifier("sqlSessionTemplate1")
    List<User> findAll();
}

3.2 自定义SqlSessionFactory配置

如果需要自定义MyBatis的行为，可以通过配置SqlSessionFactoryBean来实现：

java复制@Bean
public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {
    SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
    sessionFactory.setDataSource(dataSource);
    
    // 配置类型别名包
    sessionFactory.setTypeAliasesPackage("com.example.model");
    
    // 配置插件
    sessionFactory.setPlugins(new Interceptor[]{new MyBatisInterceptor()});
    
    // 配置映射文件位置
    sessionFactory.setMapperLocations(new PathMatchingResourcePatternResolver()
            .getResources("classpath:mapper/*.xml"));
    
    // 其他配置
    org.apache.ibatis.session.Configuration configuration = new org.apache.ibatis.session.Configuration();
    configuration.setMapUnderscoreToCamelCase(true);
    sessionFactory.setConfiguration(configuration);
    
    return sessionFactory.getObject();
}

4. 疑难问题排查技巧

4.1 调试自动配置过程

Spring Boot的自动配置过程可以通过以下方式调试：

在application.properties中添加：

code复制debug=true

启动时会输出自动配置报告，搜索"MybatisAutoConfiguration"查看是否生效
检查条件评估报告，了解为什么自动配置没有生效

4.2 常见错误与解决方案

错误：No qualifying bean of type 'javax.sql.DataSource'
- 原因：没有配置数据源或配置不正确
- 解决：检查spring.datasource配置，确保数据库驱动存在
错误：Invalid bound statement (not found)
- 原因：Mapper接口方法与XML映射文件不匹配
- 解决：检查mybatis.mapper-locations配置，确保XML文件位置正确
错误：Failed to determine a suitable driver class
- 原因：没有配置数据库驱动或配置错误
- 解决：添加对应的JDBC驱动依赖，如mysql-connector-j

4.3 日志分析技巧

配置以下日志级别可以更好地排查问题：

yaml复制logging:
  level:
    org.mybatis: DEBUG
    org.springframework.jdbc: DEBUG
    org.springframework.transaction: DEBUG

关键日志信息：

"Creating a new SqlSession" - 表示MyBatis正在创建会话
"SqlSession [xxx] was not registered for synchronization" - 事务同步问题
"JDBC Connection [xxx] will not be managed by Spring" - 连接管理问题

5. 最佳实践与经验分享

5.1 版本选择建议

根据我的项目经验，推荐以下版本组合：

Spring Boot 3.1.x + MyBatis Starter 3.0.x (生产环境推荐)
Spring Boot 3.0.x + MyBatis Starter 3.0.x (稳定组合)
避免使用SNAPSHOT版本，除非有特定需求

5.2 性能优化建议

批量操作优化：

java复制@Autowired
private SqlSessionTemplate sqlSessionTemplate;

public void batchInsert(List<User> users) {
    sqlSessionTemplate.execute(batch -> {
        UserMapper mapper = batch.getMapper(UserMapper.class);
        for (User user : users) {
            mapper.insert(user);
        }
        return null;
    });
}

二级缓存配置：

xml复制<cache eviction="LRU" flushInterval="60000" size="512" readOnly="true"/>

连接池配置：

yaml复制spring:
  datasource:
    hikari:
      maximum-pool-size: 20
      connection-timeout: 30000
      idle-timeout: 600000
      max-lifetime: 1800000

5.3 开发效率提升技巧

IDEA插件推荐：
- MyBatisX - 提供Mapper接口与XML的跳转支持
- MyBatis Log Plugin - 将MyBatis日志还原为完整SQL
- Free MyBatis Tool - 快速生成Mapper和XML
代码生成器配置：

xml复制<plugin>
    <groupId>org.mybatis.generator</groupId>
    <artifactId>mybatis-generator-maven-plugin</artifactId>
    <version>1.4.1</version>
    <configuration>
        <configurationFile>src/main/resources/generatorConfig.xml</configurationFile>
        <overwrite>true</overwrite>
    </configuration>
</plugin>

动态SQL编写技巧：

xml复制<select id="findByCondition" resultType="User">
    SELECT * FROM user
    <where>
        <if test="name != null">
            AND name = #{name}
        </if>
        <if test="age != null">
            AND age = #{age}
        </if>
    </where>
</select>

在实际项目中遇到"Property 'sqlSessionFactory' or 'sqlSessionTemplate' are required"错误时，建议按照以下步骤排查：首先检查版本兼容性，然后验证数据源配置，接着确认Mapper扫描设置，最后检查是否有依赖冲突。大多数情况下，问题出在版本不匹配或基础配置缺失上。