1. 项目概述从“能用”到“用好”的必经之路上一篇文章我们聊了SpringBoot整合MyBatis的基础搭建把架子搭起来了能跑通一个简单的查询。但说实话那只是万里长征第一步离“常用”和“好用”还差得远。在实际项目里我们面对的是动态变化的查询条件、需要批量处理的数据、必须严格管理的数据库事务以及那些稍不留神就会踩进去的“坑”。比如最近奇安信的安全扫描报告里因为MyBatis动态SQL使用不当导致的SQL注入漏洞可不少见。所以这篇我们就来深挖那些真正高频、核心的用法把整合从“跑起来”升级到“跑得稳、跑得快”。我的核心目标是不罗列API文档而是结合我这些年趟过的坑带你理解在SpringBoot项目里MyBatis那些“常用”功能背后的设计逻辑、最佳实践和避坑指南。我们会重点覆盖动态SQL的“#{}”与“${}”的天壤之别、事务管理的正确姿势、批量操作的性能优化以及如何优雅地处理复杂参数。这些内容无论是应对日常开发、代码审查还是面试中的“八股文”都能让你心里更有底。2. 动态SQL在灵活与安全之间走钢丝动态SQL是MyBatis的招牌功能它让XML映射文件活了起来。但正如网络热词里提到的“mybatis 动态sql 使用${}”和“奇安信安全扫描报sql注入漏洞”这里恰恰是最容易出安全问题的地方。很多人知道要用#{}但未必真正理解为什么以及在什么情况下不得不面对${}。2.1#{}与${}的本质区别预编译与字符串拼接这是MyBatis面试几乎必问的问题但光背答案没用得理解背后的数据库操作原理。#{}是预编译占位符。MyBatis在处理时会将其转换为JDBC的PreparedStatement中的?然后对参数进行安全地设置。例如SELECT * FROM user WHERE name #{name}最终执行的SQL类似于SELECT * FROM user WHERE name ?参数‘张三’会被安全地传递进去。数据库驱动会对参数进行转义从根本上杜绝了SQL注入。这是绝对首选的方式。${}是字符串替换。MyBatis会直接将参数值替换到SQL语句中是纯粹的字符串拼接。例如SELECT * FROM ${tableName} ORDER BY ${orderBy}如果tableName来自用户输入且未经验证用户传入user; DROP TABLE user; --拼接后的SQL将变成灾难。所以${}的使用必须极度谨慎仅能用于非用户输入、可信任的场景如动态表名、动态列名ORDER BY字段。避坑经验我团队曾有一次低级失误在模糊查询时写了WHERE name LIKE ‘%${keyword}%’结果被安全扫描揪出高危漏洞。立刻改为WHERE name LIKE CONCAT(‘%’, #{keyword}, ‘%’)或使用bind标签。永远对用户输入保持警惕把${}视为“危险工具”用时必须三思。2.2 核心动态SQL标签实战详解MyBatis提供了一系列标签来构建动态SQL理解它们的组合使用能应对90%的复杂查询场景。if标签基础的条件分支这是最常用的标签用于根据条件是否成立来包含某段SQL。select idselectUsers resultTypeUser SELECT * FROM user WHERE 11 if testname ! null and name ! ‘’ AND name #{name} /if if testage ! null AND age #{age} /if /select这里的11是个小技巧为了避免第一个条件前的AND没有WHERE承接而导致语法错误。但这不是最优解后面我们会看到更好的方案。choose,when,otherwise标签类似Java的switch-case用于实现多选一的逻辑。select idfindActiveUser resultTypeUser SELECT * FROM user WHERE state ‘ACTIVE’ choose when testtitle ! null AND title #{title} /when when testgender ! null AND gender #{gender} /when otherwise AND is_guest 1 /otherwise /choose /selecttrim,where,set标签智能处理SQL片段它们用于解决11这种不优雅的写法以及更新语句中的逗号问题。where标签会智能地处理WHERE子句。如果标签内包含的内容有返回值它会插入WHERE如果标签内内容以AND或OR开头它会将它们去除。select idselectUsers resultTypeUser SELECT * FROM user where if testname ! null AND name #{name} /if if testage ! null AND age #{age} /if /where /select这样如果所有if条件都不满足WHERE关键字不会出现如果第一个满足的条件前有AND也会被自动去掉。比11干净多了。set标签用于更新语句功能类似会智能地处理末尾的逗号。update idupdateUser UPDATE user set if testname ! nullname #{name},/if if testage ! nullage #{age},/if if testemail ! nullemail #{email},/if /set WHERE id #{id} /update即使最后一个if生效set标签也会去掉语句末尾多余的逗号。trim是where和set的底层实现更灵活可以自定义前缀、后缀以及要覆盖的字符串。!-- 等价于 where -- trim prefixWHERE prefixOverridesAND |OR ... /trim !-- 等价于 set -- trim prefixSET suffixOverrides, ... /trimforeach标签处理集合遍历实现IN查询和批量操作这是另一个高频且强大的标签常用于IN查询和批量插入。!-- IN查询参数为ListString -- select idselectUsersInIds resultTypeUser SELECT * FROM user WHERE id IN foreach itemid collectionidList open( separator, close) #{id} /foreach /select这里的collection属性值对应Mapper接口方法中的参数名。如果是单个List或数组参数默认可以用list或array。但最佳实践是使用Param注解明确指定避免混淆。!-- 批量插入 -- insert idbatchInsertUsers INSERT INTO user (name, age) VALUES foreach itemuser collectionuserList separator, (#{user.name}, #{user.age}) /foreach /insert批量插入能极大减少数据库网络交互次数提升性能。但要注意单条SQL语句有长度限制受数据库配置max_allowed_packet等参数影响如果集合过大需要在业务层进行分批次处理。2.3 复杂参数传递与Param注解当Mapper接口方法需要多个参数或者参数是复杂对象、集合时如何正确地在XML中引用它们多参数情况如果不做处理MyBatis默认会按照param1, param2, …或者arg0, arg1, …来引用。但这可读性极差。// Mapper接口 User selectByCondition(String name, Integer age);!-- 不推荐的做法 -- select idselectByCondition resultTypeUser SELECT * FROM user WHERE name #{param1} AND age #{param2} /select正确做法是使用Param注解User selectByCondition(Param(“userName”) String name, Param(“userAge”) Integer age);select idselectByCondition resultTypeUser SELECT * FROM user WHERE name #{userName} AND age #{userAge} /select这样XML中的引用就清晰明了了。传递复杂对象如MapListUser selectByMap(Param(“params”) MapString, Object map);select idselectByMap” resultType“User” SELECT * FROM user where if test“params.name ! null”AND name #{params.name}/if if test“params.minAge ! null”AND age #{params.minAge}/if /where /select注意在test条件中访问Map的键需要带上参数名params作为前缀。3. 事务管理Spring与MyBatis的协同作战在SpringBoot中事务管理通常由Spring统一接管MyBatis本身并不管理事务。理解这一点至关重要。Spring通过Transactional注解提供了声明式事务管理其本质是基于AOP的动态代理。3.1Transactional注解的正确使用姿势在Service层添加注解事务的边界应该定义在业务逻辑层Service而不是数据访问层DAO/Mapper。Service public class UserService { Autowired private UserMapper userMapper; Transactional(rollbackFor Exception.class) // 指定所有异常都回滚 public void createUser(User user) { userMapper.insert(user); // 其他数据库操作... // 如果这里抛出异常上面的insert操作会被回滚 } }关键属性解析rollbackFor/noRollbackFor: 指定哪些异常触发/不触发回滚。强烈建议显式设置rollbackFor Exception.class因为默认只在抛出运行时异常RuntimeException和错误Error时回滚受检异常Exception不会触发回滚这常常是坑点。propagation: 事务传播行为。常用的是REQUIRED默认如果当前没有事务就新建一个如果有就加入和REQUIRES_NEW无论当前有没有都新建一个事务新事务与旧事务独立。isolation: 事务隔离级别默认为数据库的默认级别。在需要处理脏读、幻读等问题时调整。readOnly: 标记为只读事务优化查询性能。3.2 事务失效的常见坑点及排查事务不生效是开发中的高频问题以下是几个主要原因注解添加位置错误Transactional只能应用到public方法上。应用到private、protected或default方法上Spring的代理机制无法生效。同时自调用失效是经典大坑在同一个类中一个非事务方法A调用另一个有Transactional注解的方法B事务不会生效。因为代理对象调用的是原始对象的方法绕过了代理。Service public class OrderService { public void placeOrder(Order order) { // 其他逻辑... this.deductInventory(order.getProductId(), order.getQuantity()); // 事务失效 } Transactional public void deductInventory(Long productId, Integer quantity) { inventoryMapper.reduceStock(productId, quantity); } }解决方案将事务方法放到另一个Service中或者通过AopContext.currentProxy()获取当前代理对象来调用需要开启expose-proxy。异常被“吃掉”如果在事务方法中捕获了异常并且没有重新抛出Spring就无法感知到异常自然不会回滚。Transactional public void updateUser(User user) { try { userMapper.update(user); int i 1 / 0; // 抛出运行时异常 } catch (Exception e) { log.error(“更新失败”, e); // 没有 throw e 事务不回滚 } }解决方案在catch块中根据业务决定是记录日志后抛出异常或者手动回滚TransactionAspectSupport.currentTransactionStatus().setRollbackOnly()。数据库引擎不支持使用MySQL的MyISAM引擎是不支持事务的必须使用InnoDB引擎。非运行时异常未配置回滚如前所述默认只回滚RuntimeException和Error。实操心得排查事务问题我习惯先看日志。开启Spring事务调试日志logging.level.org.springframework.transaction.interceptorTRACE。它会打印事务的开启、提交、回滚信息一目了然。另外在复杂的业务流中理清事务边界比技术细节更重要避免大事务拖垮数据库。4. 高级特性与性能优化实战掌握了基础和事务我们来看看如何让MyBatis用得更高效、更优雅。4.1 批量操作大幅提升数据吞吐效率单条插入在数据量大的时候是性能杀手。MyBatis提供了几种批量操作的方式。方式一foreach标签拼接SQL前面已经展示过这是最直观的方式。但需要注意SQL长度限制通常建议每批次处理500-1000条。方式二ExecutorType.BATCH会话模式这是更高效的批量操作方式。它利用JDBC的addBatch()和executeBatch()方法在同一个数据库会话中预编译一次SQL然后多次执行。Autowired private SqlSessionTemplate sqlSessionTemplate; public void batchInsert(ListUser userList) { // 获取一个批处理模式的SqlSession SqlSession session sqlSessionTemplate.getSqlSessionFactory().openSession(ExecutorType.BATCH); UserMapper mapper session.getMapper(UserMapper.class); try { for (User user : userList) { mapper.insert(user); } // 一次性提交所有批处理命令 session.commit(); session.clearCache(); // 可选清除本地的缓存 } catch (Exception e) { session.rollback(); throw e; } finally { session.close(); } }注意在BATCH模式下insert、update、delete操作不会立即返回受影响的行数通常返回-2147482646需要等session.commit()之后才会真正执行。select操作不受此模式影响。方式三整合MyBatis-Plus等增强框架MyBatis-Plus的Service层提供了saveBatch等方法内部已经优化了批量逻辑使用起来更方便但底层原理依然是上述两种之一。4.2 结果集映射resultMap的深度应用当数据库字段名和Java实体类属性名不一致或者查询涉及关联一对一、一对多时就需要用到resultMap。基础字段映射resultMap id“UserResultMap” type“User” id property“id” column“user_id”/ !-- 主键映射 -- result property“userName” column“name”/ result property“userAge” column“age”/ /resultMap select id“selectUser” resultMap“UserResultMap” SELECT user_id, name, age FROM user WHERE id #{id} /select复杂关联映射一对一一对多这是体现MyBatis对象关系映射能力的地方。!-- 一个订单对应一个用户一对一 -- resultMap id“OrderWithUserResultMap” type“Order” id property“id” column“order_id”/ result property“orderNo” column“order_no”/ !-- association 处理一对一关联 -- association property“user” javaType“User” id property“id” column“user_id”/ result property“userName” column“user_name”/ /association /resultMap !-- 一个用户有多个订单一对多 -- resultMap id“UserWithOrdersResultMap” type“User” id property“id” column“id”/ result property“userName” column“name”/ !-- collection 处理一对多关联 -- collection property“orderList” ofType“Order” id property“id” column“order_id”/ result property“orderNo” column“order_no”/ /collection /resultMap使用关联映射时SQL通常需要使用JOIN查询。要警惕“N1查询问题”如果主查询返回N条记录而每条记录又触发一次子查询去获取关联数据就会产生N1次数据库查询性能极差。MyBatis的association和collection通过一次性的JOIN查询需要写复杂的SQL可以避免此问题也可以配合Select注解和额外的select语句实现懒加载或分步查询需根据数据量和业务场景权衡。4.3 插件Interceptor与分页MyBatis的插件机制允许你在执行过程中的某些点称为“拦截点”进行拦截和增强。最经典的插件应用就是分页。使用PageHelper分页插件这是国内最流行的MyBatis分页插件与SpringBoot整合极其简单。添加依赖以5.x版本为例dependency groupIdcom.github.pagehelper/groupId artifactIdpagehelper-spring-boot-starter/artifactId version最新版本/version /dependency在Service或Controller中直接使用Service public class UserService { public PageInfoUser getUsersByPage(int pageNum, int pageSize) { // 关键紧跟在查询语句前调用 PageHelper.startPage(pageNum, pageSize); ListUser userList userMapper.selectAll(); // 这是一个普通的查询方法 return new PageInfo(userList); } }PageHelper会在startPage方法调用后的第一个MyBatis查询语句上自动加上分页逻辑如MySQL的LIMIT。它返回的PageInfo对象包含了分页详情总记录数、总页数、当前页等和数据列表。注意PageHelper.startPage()必须紧挨着Mapper查询方法调用中间不能有其它数据库查询否则分页可能会被错误地应用到其它查询上。这是一个需要严格遵守的约定。5. 生产环境下的配置、监控与排错项目上线后如何保证MyBatis的稳定运行和高效排查问题5.1 精细化配置application.yml除了最基本的数据源配置以下配置对性能和稳定性很有帮助mybatis: configuration: map-underscore-to-camel-case: true # 自动将下划线字段映射为驼峰属性强烈建议开启 default-fetch-size: 100 # 控制JDBC结果集每次获取的行数影响大结果集查询的内存占用 default-statement-timeout: 30 # 语句执行超时时间秒 log-impl: org.apache.ibatis.logging.stdout.StdOutImpl # 开发时开启打印SQL到控制台 mapper-locations: classpath:mapper/*.xml # 指定XML映射文件位置 type-aliases-package: com.example.demo.entity # 配置实体类别名包XML中可直接用类名5.2 SQL执行监控与慢查询日志在生产环境我们需要知道每条SQL的执行情况。开启MyBatis SQL日志配置logging.level.com.example.demo.mapperDEBUG将包路径换成你的Mapper接口所在包可以在日志中看到执行的SQL和参数。但生产环境慎用DEBUG级别数据量大。使用Druid连接池的监控功能Druid提供了强大的SQL监控和防火墙功能可以统计执行次数、最慢SQL、事务时间等是生产环境监控的利器。结合数据库自身的慢查询日志在MySQL等数据库中配置long_query_time记录执行时间过长的SQL这是性能调优的根本。5.3 常见问题排查思路BindingException: Parameter ‘xxx’ not found这是最常见的错误之一。根本原因是XML中#{}或${}里的属性名在传入的参数对象中找不到。检查点确认Mapper接口方法的参数是否有Param注解XML中引用的名称是否与注解值一致。如果参数是对象检查属性名是否拼写正确注意大小写。使用Map传参时检查Key是否一致。Invalid bound statement (not found)Mapper接口方法与XML中的SQL语句ID无法绑定。检查点首先确认mybatis.mapper-locations配置的路径是否包含了你的XML文件。其次检查XML文件中的namespace是否完全对应Mapper接口的全限定名。最后检查方法名是否与XML中的id一致。Maven项目还要检查pom.xml中是否配置了resources标签来包含XML文件否则打包时可能丢失。查询结果映射失败部分字段为null检查点首先确认是否开启了map-underscore-to-camel-case。如果没开数据库字段user_name无法自动映射到Java属性userName。其次检查resultMap是否正确配置或者实体类属性名与查询返回的列名是否匹配。可以使用AS在SQL中为列起别名。整合其他组件时的配置冲突如网络热词中提到的“flowable-ui覆盖了mybatis的配置”当项目引入多个框架时可能会发生配置被覆盖或冲突。例如Flowable、Spring Security等框架可能也配置了DataSource或TransactionManager。解决思路仔细查看启动日志是否有关于“Overriding bean definition”的警告。通常需要在一个主配置类上使用Primary注解来指定当存在多个同类型Bean时优先使用哪一个。或者通过排除自动配置类来避免冲突例如SpringBootApplication(exclude {SomeAutoConfiguration.class})。从安全地编写动态SQL到稳妥地管理事务再到高效地进行批量操作和复杂映射最后到生产环境的配置与排错这些内容构成了SpringBoot整合MyBatis从入门到熟练的核心知识体系。掌握它们意味着你不仅能完成功能更能写出健壮、高效、易于维护的代码。在实际开发中多思考SQL的性能多利用日志进行排查多关注社区的最佳实践这些习惯会让你在使用MyBatis时更加得心应手。