MyBatis-Plus项目中"Property 'sqlSessionFactory' or 'sqlSessionTemplate' are required"错误分析与解决方案

问题背景

在使用MyBatis-Plus框架开发项目时，开发者可能会遇到"Property 'sqlSessionFactory' or 'sqlSessionTemplate' are required"的错误提示。这个错误通常发生在Spring Boot应用启动阶段，表明MyBatis-Plus无法正确初始化Mapper接口所需的SQL会话工厂或模板。

错误原因分析

该错误的根本原因是MyBatis-Plus无法自动配置SQL会话相关的关键组件。在Spring Boot集成MyBatis-Plus的环境中，这通常由以下几种情况导致：

1. 配置缺失：未正确配置MyBatis-Plus的相关属性，特别是mapper-locations路径
2. 版本冲突：项目中存在MyBatis和MyBatis-Plus版本不兼容的情况
3. 自动配置失效：某些自定义配置覆盖了Spring Boot的自动配置
4. 多数据源场景：在多数据源配置中未正确处理SQL会话工厂的创建

解决方案

方案一：基础配置检查

首先确保在application.yml或application.properties中配置了MyBatis-Plus的基本属性：

mybatis-plus:
  mapper-locations: classpath*:mapper/**/*.xml
  type-aliases-package: com.example.model
  configuration:
    map-underscore-to-camel-case: true

特别注意配置项前缀必须是mybatis-plus而非mybatis，这是新手常见的配置错误。

方案二：手动配置SQL会话工厂

当自动配置失效时，可以手动创建必要的Bean：

@Configuration
public class MyBatisConfig {
    
    @Bean
    public DataSource dataSource() {
        // 配置数据源
        DruidDataSource dataSource = new DruidDataSource();
        dataSource.setDriverClassName(driverClassName);
        dataSource.setUrl(url);
        dataSource.setUsername(username);
        dataSource.setPassword(password);
        return dataSource;
    }

    @Bean
    public SqlSessionFactory sqlSessionFactory(DataSource dataSource) throws Exception {
        MybatisSqlSessionFactoryBean factoryBean = new MybatisSqlSessionFactoryBean();
        factoryBean.setDataSource(dataSource);
        
        // 添加分页插件
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor(DbType.MYSQL));
        factoryBean.setPlugins(interceptor);
        
        return factoryBean.getObject();
    }

    @Bean
    public SqlSessionTemplate sqlSessionTemplate(SqlSessionFactory sqlSessionFactory) {
        return new SqlSessionTemplate(sqlSessionFactory);
    }
}

方案三：多数据源场景处理

在多数据源环境下，需要为每个数据源单独配置SQL会话工厂，并使用@Primary注解标记主数据源：

@Configuration
public class MultiDataSourceConfig {

    @Bean
    @Primary
    @ConfigurationProperties(prefix = "spring.datasource.primary")
    public DataSource primaryDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Bean
    @ConfigurationProperties(prefix = "spring.datasource.secondary")
    public DataSource secondaryDataSource() {
        return DataSourceBuilder.create().build();
    }

    @Bean
    @Primary
    public SqlSessionFactory primarySqlSessionFactory(@Qualifier("primaryDataSource") DataSource dataSource) throws Exception {
        return createSqlSessionFactory(dataSource);
    }

    @Bean
    public SqlSessionFactory secondarySqlSessionFactory(@Qualifier("secondaryDataSource") DataSource dataSource) throws Exception {
        return createSqlSessionFactory(dataSource);
    }

    private SqlSessionFactory createSqlSessionFactory(DataSource dataSource) throws Exception {
        MybatisSqlSessionFactoryBean factoryBean = new MybatisSqlSessionFactoryBean();
        factoryBean.setDataSource(dataSource);
        // 其他配置...
        return factoryBean.getObject();
    }
}

最佳实践建议

1. 版本一致性：确保MyBatis、MyBatis-Spring和MyBatis-Plus版本兼容
2. 配置检查：定期检查配置项，特别是从MyBatis迁移到MyBatis-Plus的项目
3. 日志监控：开启DEBUG级别日志，监控MyBatis-Plus的初始化过程
4. 单元测试：为数据访问层编写集成测试，及早发现问题
5. 依赖管理：使用Maven或Gradle的依赖管理功能，避免版本冲突

总结

"Property 'sqlSessionFactory' or 'sqlSessionTemplate' are required"错误是MyBatis-Plus项目中常见的配置问题。通过正确配置、手动创建必要Bean或处理多数据源场景，可以有效解决这个问题。理解MyBatis-Plus的自动配置原理，掌握SQL会话工厂的创建过程，是避免此类问题的关键。