Spring Boot与MyBatis整合开发实战指南

1. Spring Boot与MyBatis整合全景解析作为Java生态中最主流的两个框架Spring Boot和MyBatis的组合堪称企业级开发的黄金搭档。我经历过从早期SSH到SSM的技术演进最终在微服务时代锁定这个组合方案。Spring Boot的自动化配置特性与MyBatis的灵活SQL控制能力形成完美互补——前者解决了传统Spring项目繁琐的配置问题后者则保留了开发者对SQL的精准掌控权。这种组合特别适合需要平衡开发效率与SQL优化需求的场景。比如电商系统中的订单查询模块既需要快速开发迭代又要求针对不同条件组合实现高性能查询。通过MyBatis的动态SQL配合Spring Boot的快速启动能力我们可以在半小时内搭建出具备基础CRUD功能的RESTful API服务。2. 环境准备与项目初始化2.1 创建Spring Boot项目推荐使用Spring Initializrstart.spring.io生成项目骨架。关键依赖选择Spring Web构建RESTful接口MyBatis Framework核心ORM支持MySQL Driver或其他数据库驱动对于IDE的选择IntelliJ IDEA对MyBatis的XML映射文件支持最好能实现方法名与XML的智能跳转。以下是典型的pom.xml依赖配置dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.mybatis.spring.boot/groupId artifactIdmybatis-spring-boot-starter/artifactId version3.0.3/version /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency /dependencies2.2 数据库配置详解在application.yml中配置数据源时有几个关键参数常被忽略但至关重要spring: datasource: url: jdbc:mysql://localhost:3306/demo?useSSLfalseserverTimezoneUTCcharacterEncodingUTF-8 username: root password: 123456 hikari: maximum-pool-size: 20 connection-timeout: 30000 idle-timeout: 600000 max-lifetime: 1800000 mybatis: mapper-locations: classpath:mapper/*.xml configuration: map-underscore-to-camel-case: true default-fetch-size: 100 default-statement-timeout: 30特别注意在生产环境中务必启用SSL连接示例中禁用仅用于开发环境。连接池参数需要根据实际QPS调整过大的连接数反而会导致性能下降。3. MyBatis核心组件集成3.1 实体类与Mapper接口设计实体类设计应遵循JPA规范的同时考虑MyBatis特性。例如用户实体Data NoArgsConstructor AllArgsConstructor public class User { private Long id; private String username; private String email; JsonFormat(pattern yyyy-MM-dd HH:mm:ss) private LocalDateTime createTime; }Mapper接口设计技巧方法命名遵循Spring Data规范findBy/getBy/queryBy复杂查询使用Param注解明确参数名返回集合时使用List而非CollectionMapper public interface UserMapper { Select(SELECT * FROM user WHERE id #{id}) User findById(Param(id) Long id); Insert(INSERT INTO user(username,email) VALUES(#{user.username},#{user.email})) Options(useGeneratedKeys true, keyProperty id) int insert(Param(user) User user); }3.2 XML映射文件深度配置XML映射文件是MyBatis的核心能力所在。动态SQL示例select idsearchUsers resultTypeUser SELECT * FROM user where if testusername ! null and username ! AND username LIKE CONCAT(%,#{username},%) /if if testemail ! null AND email #{email} /if if testcreateTimeStart ! null AND create_time #{createTimeStart} /if /where ORDER BY id DESC LIMIT #{offset}, #{pageSize} /select高级技巧使用 片段复用公共SQL段通过 自定义复杂结果映射用 处理一对多关联查询4. 事务管理与性能优化4.1 声明式事务配置Spring的Transactional注解与MyBatis的整合需要特别注意Service RequiredArgsConstructor public class UserService { private final UserMapper userMapper; Transactional(rollbackFor Exception.class, isolation Isolation.READ_COMMITTED) public void createUser(User user) { userMapper.insert(user); // 其他数据库操作 } }常见陷阱默认只回滚RuntimeException需通过rollbackFor指定其他异常类型同类内方法调用不会触发事务代理AOP失效大事务会导致连接持有时间过长应拆分为小事务4.2 二级缓存与批处理MyBatis二级缓存配置mybatis: configuration: cache-enabled: true然后在Mapper接口添加注解CacheNamespace(eviction LruCache.class, flushInterval 60000, size 1024) public interface UserMapper { //... }批处理优化示例Insert(script INSERT INTO user(username, email) VALUES foreach collectionusers itemuser separator, (#{user.username}, #{user.email}) /foreach /script) void batchInsert(Param(users) ListUser users);5. 生产环境实战经验5.1 多数据源配置大型项目常需要访问多个数据库。配置示例Configuration MapperScan(basePackages com.demo.mapper.primary, sqlSessionTemplateRef primarySqlSessionTemplate) 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(); } // 类似配置secondary数据源... }5.2 监控与诊断集成Spring Boot Actuator监控SQL执行management: endpoints: web: exposure: include: health,metrics,mappings metrics: distribution: percentiles: jdbc: connections: usage: 0.5,0.95关键监控指标jdbc.connections.active活跃连接数http.server.requestsAPI响应时间jdbc.sql.executionSQL执行耗时分布6. 常见问题排查指南6.1 典型异常处理BindingException检查Mapper接口与XML的namespace是否匹配确认方法名与XML中的id一致使用IDEA的MyBatis插件验证映射SQL语法错误开启MyBatis日志logging.level.xxx.mapperDEBUG复制控制台SQL到数据库客户端执行验证连接泄露在应用关闭时检查连接池状态使用Druid的监控页面分析连接获取堆栈6.2 性能调优经验慢SQL优化添加Select注解时使用FOR UPDATE需谨慎大批量查询考虑分页或游标方式复杂关联查询拆分为多个简单查询缓存策略一级缓存作用域为SqlSession二级缓存跨Session但要注意数据一致性考虑使用Redis实现分布式缓存连接池配置spring: datasource: hikari: minimum-idle: 5 maximum-pool-size: 20 leak-detection-threshold: 60000在实际项目中我发现MyBatis的TypeHandler是个被低估的强大功能。比如处理数据库中的JSON字段public class JsonTypeHandlerT extends BaseTypeHandlerT { private final ClassT type; Override public void setNonNullParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) { ps.setString(i, JSON.toJSONString(parameter)); } Override public T getNullableResult(ResultSet rs, String columnName) { return JSON.parseObject(rs.getString(columnName), type); } //...其他重写方法 }然后在字段上使用TableField(typeHandler JsonTypeHandler.class) private UserProfile profile;