解决MyBatis-Spring整合中的sqlSessionFactory注入问题

1. 问题现象与背景分析

最近在使用IntelliJ IDEA开发基于MyBatis的项目时，不少开发者遇到了一个典型的报错信息："Property 'sqlSessionFactory' or 'sqlSessionTemplate' are required"。这个错误通常发生在Spring与MyBatis整合的场景中，当MyBatis的核心组件无法正确注入时抛出。

这个错误看似简单，但背后涉及Spring IoC容器、MyBatis-Spring整合机制以及项目配置的多个环节。我最近在一个企业级项目中就遇到了这个问题，花了近两小时才彻底解决。下面我将详细剖析这个问题的成因、排查思路和多种解决方案。

2. 错误根源深度解析

2.1 核心组件的作用机制

要理解这个错误，首先需要明确sqlSessionFactory和sqlSessionTemplate在MyBatis-Spring整合中的角色：

• SqlSessionFactory：MyBatis的核心工厂类，负责创建SqlSession实例。在Spring环境中，通常通过SqlSessionFactoryBean来配置。

• SqlSessionTemplate：MyBatis-Spring提供的线程安全类，封装了SqlSession的操作，是推荐在Spring中使用的SqlSession实现。

当Spring尝试注入Mapper接口的实现时，它需要这两个组件中的一个来创建实际的代理对象。如果两者都不可用，就会抛出我们看到的错误。

2.2 常见触发场景

根据我的经验，这个问题通常出现在以下几种情况：

1. 配置缺失：忘记在Spring配置中声明SqlSessionFactoryBean或SqlSessionTemplate。

2. 扫描路径问题：Mapper接口的扫描配置不正确，导致Spring无法找到需要注入的Mapper。

3. 依赖冲突：项目中存在多个MyBatis或MyBatis-Spring版本，导致整合出现问题。

4. 注解使用不当：在使用Java配置时，关键注解如@MapperScan或@Bean配置不正确。

3. 解决方案与实操步骤

3.1 XML配置方式修复

对于传统的XML配置项目，以下是完整的解决方案：

xml复制<!-- 配置数据源 -->
<bean id="dataSource" class="org.apache.commons.dbcp2.BasicDataSource">
    <!-- 数据源配置参数 -->
</bean>

<!-- 配置SqlSessionFactory -->
<bean id="sqlSessionFactory" class="org.mybatis.spring.SqlSessionFactoryBean">
    <property name="dataSource" ref="dataSource"/>
    <property name="mapperLocations" value="classpath*:mapper/**/*.xml"/>
    <property name="typeAliasesPackage" value="com.example.model"/>
</bean>

<!-- 配置Mapper扫描 -->
<bean class="org.mybatis.spring.mapper.MapperScannerConfigurer">
    <property name="basePackage" value="com.example.mapper"/>
    <property name="sqlSessionFactoryBeanName" value="sqlSessionFactory"/>
</bean>

关键点说明：

• SqlSessionFactoryBean必须正确引用数据源
• mapperLocations要指向实际的Mapper XML文件位置
• MapperScannerConfigurer的basePackage要包含所有Mapper接口

3.2 Java配置方式修复

对于使用Spring Boot或Java配置的项目，推荐以下方式：

java复制@Configuration
@MapperScan("com.example.mapper")
public class MyBatisConfig {
    
    @Bean
    public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {
        SqlSessionFactoryBean sessionFactory = new SqlSessionFactoryBean();
        sessionFactory.setDataSource(dataSource);
        sessionFactory.setMapperLocations(
            new PathMatchingResourcePatternResolver()
                .getResources("classpath:mapper/**/*.xml"));
        return sessionFactory.getObject();
    }
}

注意事项：

• @MapperScan注解必须指定正确的Mapper接口包路径
• 确保DataSource bean已正确配置
• 如果使用MyBatis-Plus，可以使用MybatisSqlSessionFactoryBean替代

3.3 Spring Boot自动配置问题

在使用Spring Boot时，虽然它提供了MyBatis的自动配置，但某些情况下自动配置可能失效：

1. 检查是否添加了必要的starter依赖：

xml复制<dependency>
    <groupId>org.mybatis.spring.boot</groupId>
    <artifactId>mybatis-spring-boot-starter</artifactId>
    <version>最新版本</version>
</dependency>

2. 确保application.properties中包含必要配置：

properties复制mybatis.mapper-locations=classpath*:mapper/**/*.xml
mybatis.type-aliases-package=com.example.model

3. 如果使用多数据源，需要禁用自动配置：

java复制@SpringBootApplication(exclude = {MybatisAutoConfiguration.class})

4. 高级排查技巧

4.1 诊断Spring容器状态

当问题复杂时，可以通过以下方式检查Spring容器的状态：

1. 在应用启动后，获取ApplicationContext并列出所有Bean：

java复制@Autowired
private ApplicationContext applicationContext;

public void checkBeans() {
    String[] beanNames = applicationContext.getBeanDefinitionNames();
    Arrays.sort(beanNames);
    for (String beanName : beanNames) {
        System.out.println(beanName);
    }
}

2. 特别检查是否存在以下关键Bean：

• sqlSessionFactory
• sqlSessionTemplate
• 你的Mapper接口的代理对象

4.2 日志调试技巧

在application.properties中增加以下日志配置：

properties复制logging.level.org.mybatis=DEBUG
logging.level.org.springframework.jdbc=DEBUG

这可以帮助你看到：

• MyBatis是否成功加载了Mapper XML文件
• SqlSessionFactory的创建过程
• Mapper接口的注册情况

4.3 多模块项目特殊处理

对于多模块项目，常见的坑包括：

1. Mapper接口和XML文件不在同一模块：

• 确保编译后XML文件会被复制到classpath
• 在pom.xml中添加资源过滤配置

2. 模块间依赖关系不正确：

• 包含Mapper接口的模块需要被依赖模块正确引用
• 确保不会出现循环依赖

5. 预防措施与最佳实践

根据我的项目经验，以下措施可以有效避免这类问题：

1. 项目结构标准化：

• 统一Mapper接口和XML文件的存放位置
• 建议使用mapper/目录存放XML，对应包名存放接口

2. 依赖管理：

• 使用BOM或parent POM统一管理MyBatis相关依赖版本
• 定期检查依赖冲突（mvn dependency:tree）

3. 配置检查清单：

• 数据源配置是否正确
• SqlSessionFactory是否引用了正确的数据源
• Mapper扫描路径是否包含所有Mapper接口
• XML文件是否会被正确打包到最终应用中

4. 单元测试验证：

java复制@SpringBootTest
public class MyBatisConfigTest {

    @Autowired
    private ApplicationContext context;

    @Test
    public void testSqlSessionFactoryExists() {
        assertNotNull(context.getBean(SqlSessionFactory.class));
    }

    @Test
    public void testMapperRegistered() {
        assertNotNull(context.getBean(UserMapper.class));
    }
}

6. 相关工具推荐

1. MyBatis Code Helper Pro（IDEA插件）：

• 提供Mapper接口与XML的导航
• 自动生成XML中的SQL语句
• 检测不匹配的方法签名

2. Arthas：

• 动态监控MyBatis SQL执行
• 检查Mapper代理类的实际生成情况

bash复制watch org.apache.ibatis.binding.MapperProxy '*'

3. MyBatis-Plus：

• 简化MyBatis配置
• 提供更强大的CRUD操作
• 内置分页插件等实用功能

7. 典型问题案例

7.1 案例一：XML文件未被加载

现象：配置了MapperScannerConfigurer，但Mapper接口无法注入。

排查过程：

1. 检查编译后的target/classes目录，发现mapper XML文件缺失
2. 检查pom.xml，发现没有配置资源包含
3. 添加以下配置后问题解决：

xml复制<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <includes>
                <include>**/*.xml</include>
            </includes>
        </resource>
    </resources>
</build>

7.2 案例二：多数据源配置冲突

现象：配置了多个数据源后出现该错误。

解决方案：

java复制@Configuration
@MapperScan(basePackages = "com.example.mapper1", 
           sqlSessionFactoryRef = "sqlSessionFactory1")
public class MyBatisConfig1 {
    // 第一个数据源和SqlSessionFactory配置
}

@Configuration
@MapperScan(basePackages = "com.example.mapper2",
           sqlSessionFactoryRef = "sqlSessionFactory2")
public class MyBatisConfig2 {
    // 第二个数据源和SqlSessionFactory配置
}

关键点：

• 每个SqlSessionFactory绑定到特定的数据源
• 每个MapperScan明确指定使用的SqlSessionFactory

8. 性能优化建议

在解决基本问题后，可以考虑以下优化：

1. SqlSessionTemplate配置：

java复制@Bean
public SqlSessionTemplate sqlSessionTemplate(SqlSessionFactory sqlSessionFactory) {
    return new SqlSessionTemplate(sqlSessionFactory, 
        ExecutorType.BATCH); // 使用批量执行器
}

2. 二级缓存配置：

xml复制<settings>
    <setting name="cacheEnabled" value="true"/>
</settings>

<!-- 在Mapper XML中 -->
<cache eviction="LRU" flushInterval="60000" size="512" readOnly="true"/>

3. MyBatis插件：

• 添加性能分析插件
• SQL执行时间监控
• 分页插件优化

9. 常见误区与陷阱

1. 过度依赖自动配置：

• Spring Boot的自动配置并不总是能满足复杂需求
• 生产环境建议显式配置关键组件

2. 版本兼容性问题：

• MyBatis与MyBatis-Spring版本必须匹配
• 与Spring框架版本也有兼容性要求

3. IDEA缓存问题：

• 有时IDEA的缓存会导致配置变更不生效
• 尝试File -> Invalidate Caches / Restart

4. XML中的特殊字符：

xml复制<!-- 错误 -->
WHERE status <> 0

<!-- 正确 -->
WHERE status &lt;&gt; 0

10. 扩展思考

1. 为什么Spring需要这两个组件？
   Spring通过这两个组件将MyBatis集成到自己的IoC容器中。SqlSessionFactory负责创建会话，而SqlSessionTemplate则管理会话的生命周期，使其与Spring的事务管理协同工作。

2. 动态数据源场景如何处理？
   在需要动态切换数据源的场景下，可以考虑：

• 继承AbstractRoutingDataSource
• 自定义SqlSessionFactoryBean
• 使用ThreadLocal保存当前数据源标识

3. MyBatis与JPA混用注意事项：

• 确保事务管理器配置正确
• 避免实体类注解冲突
• 考虑使用Spring Data JPA的MyBatis扩展

在实际项目中遇到这个问题时，建议按照以下步骤排查：

1. 确认基本配置是否存在
2. 检查依赖版本是否兼容
3. 验证资源文件是否被正确打包
4. 查看Spring容器中关键Bean的状态
5. 通过日志分析初始化过程

记住，配置问题往往隐藏在细节中。在我最近处理的一个案例中，问题竟然是由于一个不起眼的空格字符在XML配置文件中导致的路径解析错误。因此，耐心和系统性的排查是解决这类问题的关键。