1. 项目概述Spring Boot 整合 MyBatis 是 Java 后端开发中最常见的组合之一这个组合能够快速构建数据访问层实现高效的数据库操作。作为一名长期使用这个技术栈的开发者我见过太多初学者在整合过程中踩坑今天我就把整个流程掰开揉碎从环境搭建到 CRUD 实现一步步带你走通全流程。这个教程特别适合以下人群刚接触 Spring Boot 和 MyBatis 的新手想系统学习 MyBatis 整合的开发人员需要快速搭建项目原型的工程师我们将从最基础的 Maven 依赖配置开始到完整的 CRUD 实现每个步骤都会详细说明确保你跟着做就能成功。2. 环境准备与项目搭建2.1 创建 Spring Boot 项目首先使用 Spring Initializr 创建一个基础项目。我推荐使用 IntelliJ IDEA 的创建向导选择以下配置Project: Maven ProjectLanguage: JavaSpring Boot: 最新稳定版目前是 3.xPackaging: JarJava: 17在依赖选择界面勾选Spring Web (即使我们不做 Web 项目也建议选上)MyBatis FrameworkMySQL Driver提示即使你使用其他数据库也可以先选 MySQL后续再替换驱动依赖2.2 配置数据库连接创建完成后打开 application.properties 文件或 application.yml我推荐使用 yml 格式添加数据库配置spring: datasource: url: jdbc:mysql://localhost:3306/your_database?useSSLfalseserverTimezoneUTC username: root password: your_password driver-class-name: com.mysql.cj.jdbc.Driver这里有几个关键点需要注意useSSLfalse 表示不使用 SSL 连接serverTimezoneUTC 设置时区避免时区问题新版本 MySQL 驱动类名是 com.mysql.cj.jdbc.Driver2.3 添加必要的依赖虽然 Initializr 已经帮我们添加了基础依赖但为了更好的开发体验我建议在 pom.xml 中添加以下依赖dependency groupIdorg.projectlombok/groupId artifactIdlombok/artifactId optionaltrue/optional /dependency dependency groupIdcom.alibaba/groupId artifactIddruid-spring-boot-starter/artifactId version1.2.8/version /dependencyLombok 可以简化实体类的编写Druid 是一个优秀的数据库连接池比默认的 HikariCP 提供更多监控功能。3. MyBatis 核心配置3.1 配置 MyBatis 扫描路径在 application.yml 中添加 MyBatis 配置mybatis: mapper-locations: classpath:mapper/*.xml type-aliases-package: com.example.demo.model configuration: map-underscore-to-camel-case: true关键配置说明mapper-locations: 指定 XML 映射文件的位置type-aliases-package: 实体类所在包这样在 XML 中可以直接使用类名而不需要全限定名map-underscore-to-camel-case: 自动将下划线命名转为驼峰命名解决数据库字段名和 Java 属性名不一致的问题3.2 添加 MapperScan 注解在主启动类上添加 MapperScan 注解指定 Mapper 接口所在的包SpringBootApplication MapperScan(com.example.demo.mapper) public class DemoApplication { public static void main(String[] args) { SpringApplication.run(DemoApplication.class, args); } }这个注解会扫描指定包下的所有接口并将它们注册为 MyBatis 的 Mapper。4. 实现 CRUD 操作4.1 创建实体类假设我们有一个用户表 user先创建对应的实体类Data public class User { private Long id; private String username; private String password; private String email; private Date createTime; private Date updateTime; }使用了 Lombok 的 Data 注解自动生成 getter/setter 等方法。4.2 创建 Mapper 接口创建 UserMapper 接口public interface UserMapper { int insert(User user); User selectById(Long id); ListUser selectAll(); int update(User user); int delete(Long id); }4.3 创建 XML 映射文件在 resources/mapper 目录下创建 UserMapper.xml?xml version1.0 encodingUTF-8 ? !DOCTYPE mapper PUBLIC -//mybatis.org//DTD Mapper 3.0//EN http://mybatis.org/dtd/mybatis-3-mapper.dtd mapper namespacecom.example.demo.mapper.UserMapper resultMap idBaseResultMap typeUser id columnid propertyid jdbcTypeBIGINT/ result columnusername propertyusername jdbcTypeVARCHAR/ result columnpassword propertypassword jdbcTypeVARCHAR/ result columnemail propertyemail jdbcTypeVARCHAR/ result columncreate_time propertycreateTime jdbcTypeTIMESTAMP/ result columnupdate_time propertyupdateTime jdbcTypeTIMESTAMP/ /resultMap insert idinsert useGeneratedKeystrue keyPropertyid INSERT INTO user (username, password, email, create_time, update_time) VALUES (#{username}, #{password}, #{email}, now(), now()) /insert select idselectById resultMapBaseResultMap SELECT * FROM user WHERE id #{id} /select select idselectAll resultMapBaseResultMap SELECT * FROM user /select update idupdate UPDATE user SET username #{username}, password #{password}, email #{email}, update_time now() WHERE id #{id} /update delete iddelete DELETE FROM user WHERE id #{id} /delete /mapper4.4 测试 CRUD 操作创建一个测试类来验证我们的实现SpringBootTest class UserMapperTest { Autowired private UserMapper userMapper; Test void testCRUD() { // 创建 User user new User(); user.setUsername(test); user.setPassword(123456); user.setEmail(testexample.com); userMapper.insert(user); System.out.println(Inserted user id: user.getId()); // 查询单个 User dbUser userMapper.selectById(user.getId()); System.out.println(Queried user: dbUser); // 更新 dbUser.setUsername(updated); userMapper.update(dbUser); // 查询所有 ListUser users userMapper.selectAll(); System.out.println(All users: users); // 删除 userMapper.delete(user.getId()); } }5. 高级特性与最佳实践5.1 动态 SQLMyBatis 提供了强大的动态 SQL 功能可以在 XML 中使用 if、choose、foreach 等标签构建动态查询select idselectByCondition resultMapBaseResultMap SELECT * FROM user where if testusername ! null AND username #{username} /if if testemail ! null AND email #{email} /if /where /select5.2 批量操作使用 foreach 标签实现批量插入insert idbatchInsert useGeneratedKeystrue keyPropertyid INSERT INTO user (username, password, email, create_time, update_time) VALUES foreach collectionlist itemuser separator, (#{user.username}, #{user.password}, #{user.email}, now(), now()) /foreach /insert5.3 事务管理Spring Boot 中默认已经配置了事务管理只需要在 Service 层方法上添加 Transactional 注解即可Service public class UserService { Autowired private UserMapper userMapper; Transactional public void createUser(User user) { userMapper.insert(user); // 其他数据库操作 } }6. 常见问题与解决方案6.1 Mapper 接口无法注入可能原因忘记在主类上添加 MapperScanMapper 接口没有放在被扫描的包下XML 文件位置不正确解决方案确认 MapperScan 配置正确检查接口包路径确认 application.yml 中的 mapper-locations 配置正确6.2 数据库字段和实体类属性映射失败可能原因字段名和属性名不一致且没有开启驼峰映射数据库字段类型和 Java 类型不匹配解决方案在 application.yml 中配置 map-underscore-to-camel-case: true在 resultMap 中明确指定字段和属性的映射关系6.3 XML 中的 SQL 语句报错可能原因SQL 语法错误参数占位符写法错误特殊字符未转义解决方案先在数据库客户端测试 SQL 语句参数使用 #{param} 格式对于特殊字符如 、 等使用 CDATA 包裹select idselectById resultMapBaseResultMap ![CDATA[ SELECT * FROM user WHERE id #{id} ]] /select7. 性能优化建议7.1 使用二级缓存MyBatis 提供了一级缓存默认开启和二级缓存。二级缓存可以跨 SqlSession 共享cache evictionLRU flushInterval60000 size512 readOnlytrue/在对应的 Mapper XML 中添加上述配置即可开启二级缓存。7.2 合理使用批量操作对于大量数据操作使用批量插入/更新可以显著提高性能Transactional public void batchInsertUsers(ListUser users) { userMapper.batchInsert(users); }7.3 优化 SQL 语句避免使用 SELECT *只查询需要的字段select idselectSomeFields resultMapBaseResultMap SELECT id, username, email FROM user /select8. 项目结构建议一个良好的项目结构可以提高代码的可维护性推荐如下结构src/main/java com.example.demo config/ # 配置类 controller/ # 控制器 service/ # 服务层 mapper/ # Mapper接口 model/ # 实体类 util/ # 工具类 src/main/resources mapper/ # XML映射文件 application.yml # 配置文件9. 扩展功能9.1 使用 MyBatis-PlusMyBatis-Plus 是 MyBatis 的增强工具提供了更多便捷功能添加依赖dependency groupIdcom.baomidou/groupId artifactIdmybatis-plus-boot-starter/artifactId version最新版本/version /dependencyMapper 接口继承 BaseMapperpublic interface UserMapper extends BaseMapperUser { // 自定义方法 }无需编写基础 CRUD 的 XMLMyBatis-Plus 会自动提供实现9.2 多数据源配置在实际项目中可能需要连接多个数据库添加多个数据源配置spring: datasource: primary: url: jdbc:mysql://localhost:3306/db1 username: root password: 123456 secondary: url: jdbc:mysql://localhost:3306/db2 username: root password: 123456创建配置类配置多个数据源和事务管理器10. 开发工具推荐MyBatisX: IntelliJ IDEA 插件提供 Mapper 接口和 XML 的跳转支持MyBatis Code Helper Pro: 代码生成插件MyBatis Log Plugin: 将 MyBatis 日志中的 SQL 还原为可执行语句11. 实际开发中的经验分享关于 XML 和注解的选择简单查询可以使用注解方式复杂查询建议使用 XML 方式项目统一用一种风格不要混用关于事务的使用事务注解应该加在 Service 层默认传播行为是 REQUIRED只读查询可以添加 Transactional(readOnly true)关于分页查询可以使用 PageHelper 插件或者使用 MyBatis-Plus 的分页功能关于 SQL 注入防护永远不要拼接 SQL 语句使用 #{} 而不是 ${} 进行参数传递对用户输入进行校验12. 测试策略单元测试测试 Mapper 层的各个方法集成测试测试 Service 层的业务逻辑性能测试测试批量操作的性能示例测试类SpringBootTest Transactional class UserServiceTest { Autowired private UserService userService; Test void testCreateUser() { User user new User(); user.setUsername(testuser); user.setPassword(testpass); user.setEmail(testexample.com); User created userService.createUser(user); assertNotNull(created.getId()); assertEquals(testuser, created.getUsername()); } }13. 部署注意事项生产环境数据库配置使用连接池配置设置合理的超时时间启用 SSL 连接MyBatis 配置优化开启缓存配置懒加载设置默认的语句超时时间监控配置配置 Druid 监控配置慢 SQL 日志14. 持续学习资源官方文档Spring Boot: https://spring.io/projects/spring-bootMyBatis: http://www.mybatis.org/mybatis-3MyBatis-Spring: http://www.mybatis.org/spring推荐书籍《MyBatis 从入门到精通》《Spring Boot 实战》在线课程Spring 官方教程MyBatis 视频教程15. 总结与个人体会经过多年的 MyBatis 使用经验我认为以下几点特别重要理解 MyBatis 的工作原理比记住具体配置更重要合理的项目结构能大大提升开发效率动态 SQL 是 MyBatis 最强大的功能之一性能优化应该从项目开始就考虑而不是后期补救在实际项目中我通常会先设计好数据库表结构使用工具生成基础实体类和 Mapper根据业务需求编写复杂的 SQL 语句在 Service 层组合多个 Mapper 的操作最后一个小技巧对于复杂的查询我习惯先在数据库客户端写好 SQL 并测试通过再移植到 MyBatis 的 XML 中这样可以减少调试时间。