1. SpringBoot3与Mybatis整合全景解析作为Java生态中最主流的两个框架SpringBoot和Mybatis的组合几乎成为企业级开发的标配。最近在将一个老项目迁移到SpringBoot3时我发现官方文档对整合过程的说明比较分散特别是针对JDK17环境的新特性适配部分。本文将完整记录从零开始的整合过程包含我在实际项目中验证过的配置方案和性能优化技巧。与SpringBoot2.x时代相比SpringBoot3在自动配置机制上有若干重要变化最低JDK要求提升到17、Jakarta EE 9的命名空间变更、HikariCP连接池的默认参数调整等。这些变化直接影响Mybatis的整合方式需要特别注意兼容性问题。下面就从项目初始化开始逐步拆解每个关键环节。2. 环境准备与项目初始化2.1 基础环境配置推荐使用IDEA 2022.3或Eclipse 2023-03版本确保IDE对JDK17的完整支持。通过start.spring.io生成项目时务必选择SpringBoot 3.1.0Java 17打包方式根据部署需求选择Jar或War依赖项至少包含Spring Web (用于接口测试)Mybatis Framework对应数据库驱动(如MySQL Connector/J)注意SpringBoot3默认使用Jakarta命名空间这与旧版javax包存在兼容性问题。如果项目中有老代码需要迁移需要全局替换import语句。2.2 依赖管理关键点在pom.xml中需要显式声明mybatis-spring-boot-starter的版本。由于SpringBoot3发布较新建议使用最新稳定版dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version3.0.2/version /dependency对于MySQL连接池SpringBoot3默认集成的是HikariCP 5.0.1其配置参数与旧版有差异。建议在application.yml中添加以下基准配置spring: datasource: url: jdbc:mysql://localhost:3306/demo?useSSLfalseserverTimezoneUTC username: root password: 123456 hikari: maximum-pool-size: 20 minimum-idle: 5 connection-timeout: 30000 idle-timeout: 600000 max-lifetime: 18000003. Mybatis核心配置详解3.1 配置文件定制化在resources目录下创建mybatis-config.xml这是Mybatis的主配置文件。SpringBoot3环境下推荐的最小化配置如下?xml version1.0 encodingUTF-8? !DOCTYPE configuration PUBLIC -//mybatis.org//DTD Config 3.0//EN http://mybatis.org/dtd/mybatis-3-config.dtd configuration settings setting namemapUnderscoreToCamelCase valuetrue/ setting namedefaultFetchSize value100/ setting namejdbcTypeForNull valueNULL/ /settings typeAliases package namecom.example.demo.entity/ /typeAliases /configuration关键参数说明mapUnderscoreToCamelCase开启数据库字段到Java属性的自动驼峰转换defaultFetchSize优化大数据量查询时的内存占用jdbcTypeForNull明确处理null值的JDBC类型3.2 Mapper接口与XML的绑定SpringBoot3强化了注解配置的方式但仍保留XML映射文件的完整支持。建议采用混合模式在启动类添加Mapper扫描注解MapperScan(com.example.demo.mapper) SpringBootApplication public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }Mapper接口示例public interface UserMapper { Select(SELECT * FROM users WHERE id #{id}) User selectById(Long id); Insert(INSERT INTO users(name,age) VALUES(#{name},#{age})) Options(useGeneratedKeys true, keyProperty id) int insert(User user); // 复杂查询使用XML配置 ListUser selectByCondition(UserQuery query); }对应的XML文件(resources/mapper/UserMapper.xml)mapper namespacecom.example.demo.mapper.UserMapper select idselectByCondition resultTypeUser SELECT * FROM users where if testname ! null AND name LIKE CONCAT(%,#{name},%) /if if testminAge ! null AND age #{minAge} /if /where ORDER BY id DESC /select /mapper4. 高级特性整合实战4.1 分页插件集成PageHelper仍然是Mybatis分页的首选方案。在SpringBoot3中需要特殊处理添加依赖dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version1.4.6/version exclusions exclusion groupIdorg.springframework.boot/groupId artifactIdspring-boot-autoconfigure/artifactId /exclusion /exclusions /dependency配置参数pagehelper: helper-dialect: mysql reasonable: true support-methods-arguments: true params: countcountSql使用示例public PageInfoUser queryUsers(int pageNum, int pageSize) { PageHelper.startPage(pageNum, pageSize); ListUser users userMapper.selectAll(); return new PageInfo(users); }4.2 多数据源配置企业级应用常需要连接多个数据库。SpringBoot3下配置多数据源需要主数据源配置Configuration MapperScan(basePackages com.example.mapper.primary, sqlSessionFactoryRef primarySqlSessionFactory) public class PrimaryDataSourceConfig { Bean ConfigurationProperties(spring.datasource.primary) public DataSource primaryDataSource() { return DataSourceBuilder.create().build(); } Bean public SqlSessionFactory primarySqlSessionFactory( Qualifier(primaryDataSource) DataSource dataSource) throws Exception { SqlSessionFactoryBean bean new SqlSessionFactoryBean(); bean.setDataSource(dataSource); bean.setMapperLocations(new PathMatchingResourcePatternResolver() .getResources(classpath:mapper/primary/*.xml)); return bean.getObject(); } }从数据源配置类似注意修改包扫描路径和Bean名称application.yml配置spring: datasource: primary: url: jdbc:mysql://localhost:3306/db1 username: user1 password: pass1 driver-class-name: com.mysql.cj.jdbc.Driver secondary: url: jdbc:mysql://localhost:3306/db2 username: user2 password: pass2 driver-class-name: com.mysql.cj.jdbc.Driver5. 性能优化与问题排查5.1 缓存配置最佳实践Mybatis提供两级缓存在SpringBoot3中建议开启二级缓存settings setting namecacheEnabled valuetrue/ /settings在Mapper接口添加注解CacheNamespace(implementation MybatisRedisCache.class, eviction MybatisRedisCache.class) public interface UserMapper { //... }自定义Redis缓存实现(需添加spring-boot-starter-data-redis依赖)public class MybatisRedisCache implements Cache { private final ReadWriteLock lock new ReentrantReadWriteLock(); private final String id; private final RedisTemplateString, Object redisTemplate; public MybatisRedisCache(String id) { this.id id; this.redisTemplate (RedisTemplateString, Object) SpringContextHolder.getBean(redisTemplate); } // 实现Cache接口方法... }5.2 常见问题解决方案类型处理器找不到org.apache.ibatis.type.TypeException: Could not resolve type alias...解决方法确保在mybatis-config.xml中正确定义了typeAliases或typeHandlers连接池耗尽HikariPool-1 - Connection is not available...调整连接池参数特别是max-lifetime和idle-timeout分页插件失效 检查是否在PageHelper.startPage()之后第一个查询语句才会被分页事务不生效 确保在Service方法上添加Transactional注解并且调用的方法来自外部类6. 测试验证方案6.1 单元测试配置SpringBootTest需要特殊配置来支持Mybatis测试SpringBootTest Transactional Rollback public class UserMapperTest { Autowired private UserMapper userMapper; Test public void testInsert() { User user new User(); user.setName(test); user.setAge(20); int result userMapper.insert(user); assertEquals(1, result); assertNotNull(user.getId()); } }6.2 集成API测试使用TestRestTemplate进行端点测试Test public void testUserAPI() throws Exception { // 创建测试用户 User user new User(apiTest, 25); ResponseEntityUser response restTemplate.postForEntity( /users, user, User.class); // 验证响应 assertEquals(HttpStatus.CREATED, response.getStatusCode()); User created response.getBody(); assertNotNull(created.getId()); // 查询验证 ResponseEntityUser getResponse restTemplate.getForEntity( /users/ created.getId(), User.class); assertEquals(apiTest, getResponse.getBody().getName()); }7. 部署与监控7.1 Actuator健康检查添加依赖dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-actuator/artifactId /dependency配置application.ymlmanagement: endpoints: web: exposure: include: health,info,metrics endpoint: health: show-details: always访问/actuator/health可以查看数据库连接状态7.2 日志监控建议配置SQL日志输出logging: level: org.mybatis: DEBUG com.example.mapper: TRACE对于生产环境可以集成Prometheus监控Bean public MeterRegistryCustomizerPrometheusMeterRegistry configureMetrics() { return registry - registry.config().commonTags(application, demo-app); }8. 项目结构建议最终项目应该保持清晰的层次结构src/ ├── main/ │ ├── java/ │ │ └── com/example/demo/ │ │ ├── config/ # 配置类 │ │ ├── controller/ # 控制器 │ │ ├── entity/ # 实体类 │ │ ├── mapper/ # Mapper接口 │ │ ├── service/ # 业务逻辑 │ │ └── DemoApplication.java │ └── resources/ │ ├── mapper/ # XML映射文件 │ ├── static/ # 静态资源 │ ├── templates/ # 模板文件 │ ├── application.yml # 应用配置 │ └── mybatis-config.xml └── test/ # 测试代码在真实项目开发中我强烈建议将Mybatis的XML文件与Mapper接口放在同一模块目录下可以通过Maven资源过滤实现。同时对于复杂查询使用 片段提高重用性例如sql iduserColumns id, name, age, create_time as createTime /sql select idselectById resultTypeUser SELECT include refiduserColumns/ FROM users WHERE id #{id} /select这种结构既保持了代码的可维护性又能充分利用Mybatis的强大功能。当项目规模扩大时可以考虑按功能模块拆分Mapper文件而不是简单的按实体类划分。