1. 从“能用”到“会玩”MyBatis的进阶之路如果你用过MyBatis大概率会觉得它就是个写SQL的框架把XML或者注解里的SQL映射成Java对象简单直接。这没错但如果你只停留在这个层面那可能只发挥了它30%的功力。我见过太多项目MyBatis的配置和用法千篇一律遇到稍微复杂点的场景就手忙脚乱要么是性能瓶颈要么是诡异的Bug最后只能归结于“MyBatis不好用”。其实很多时候问题出在我们自己身上没有真正理解它的设计哲学和那些藏在角落里的“奇巧淫技”。今天我们不聊怎么配置SqlSessionFactory也不说基础的insert、select。我们来深挖一下那些能让你的代码更优雅、性能更高效、排查问题更迅速的MyBatis高阶玩法。这些技巧有些来自官方文档的边角有些是社区实践中的智慧结晶还有一些是我自己踩过坑后总结出来的经验。它们可能不会出现在入门教程里但却是区分“MyBatis使用者”和“MyBatis玩家”的关键。2. 窥探与掌控SQL执行的“黑盒”透明化所有ORM框架的核心价值之一是简化数据库操作但随之而来的代价是SQL执行的“黑盒化”。你发出一条updateById却不知道它最终生成了什么SQL分页查询突然变慢你怀疑是MyBatis分页插件的锅却苦于没有证据。让SQL执行过程变得透明是高效开发和排查问题的第一步。2.1 多维度SQL日志打印不止于控制台大多数人知道在application.yml里加一行logging.level.你的Mapper包名: debug来打印SQL。但这只是基础而且日志混杂在应用日志中难以筛选。第一种集成专用MyBatis Log插件。这不是MyBatis的功能而是IDE如IntelliJ IDEA的插件。它通过拦截JDBC驱动层面的操作将MyBatis最终执行的SQL语句、参数、执行时间以非常清晰的格式在控制台单独输出。它的强大之处在于参数替换直接输出完整的、可拷贝到数据库客户端执行的SQL无需手动拼接参数。执行时间清晰显示每条SQL的执行耗时是定位慢查询的第一现场。独立窗口不与业务日志混杂一目了然。注意此插件依赖于IDE的调试机制在生产环境无效。它本质是一个本地开发调试工具。第二种配置MyBatis内置的日志实现。MyBatis支持多种日志框架SLF4J, Log4J2, Commons Logging等。通过配置可以让MyBatis输出更详细的执行信息包括Statement的创建与关闭有助于发现连接池或Statement未关闭的问题。参数映射详情可以看到每个参数是如何被设置到PreparedStatement中的。结果集映射详情对于复杂的resultMap可以看到每一行数据是如何被填充到对象属性中的。 配置方式通常是在mybatis-config.xml中设置configuration settings !-- 标准日志实现输出执行语句、参数、结果集数量 -- setting namelogImpl valueSTDOUT_LOGGING/ !-- 或者使用SLF4J配合logback-spring.xml调整特定Mapper的日志级别为DEBUG -- !-- setting namelogImpl valueSLF4J/ -- /settings /configuration使用STDOUT_LOGGING简单粗暴所有信息打到控制台。在生产环境更推荐结合logImplSLF4J并在日志配置文件中为org.apache.ibatis或你的Mapper接口设置DEBUG级别这样可以集成到你的ELK等日志系统中。第三种使用P6Spy或类似JDBC代理组件。这是最强大、也最“重”的方式。P6Spy是一个JDBC驱动代理它位于你的应用和真实JDBC驱动之间可以拦截所有数据库操作。你可以配置它输出格式化的SQL包含参数和耗时。记录慢查询超过阈值的SQL。甚至对SQL进行篡改危险操作慎用。 在Spring Boot中集成P6Spy后你需要将数据源URL从jdbc:mysql://...改为jdbc:p6spy:mysql://...并配置spy.properties。这种方式对代码无侵入且在生产环境也可用于监控但会带来轻微的性能开销和部署复杂度。2.2 动态SQL的调试看清if和foreach的真面目MyBatis的动态SQL标签if,choose,foreach,trim等非常方便但调试起来令人头疼。你传了一个空集合它到底有没有生成in语句某个条件为null时整个where子句会不会崩技巧输出BoundSql。在自定义插件或拦截器中可以获取到MappedStatement和运行时参数从而拿到BoundSql对象。BoundSql.getSql()方法返回的就是经过动态SQL解析、参数占位符?替换后的最终SQL字符串。虽然参数值还是?但你可以清晰地看到哪些if条件生效了foreach循环展开成了几个占位符。 一个更简单的临时方法是在Mapper接口方法上打调试断点在IDE的变量查看器中深入查看传入的SqlSession或执行器相关的对象往往也能找到BoundSql的踪迹。理解BoundSql是理解MyBatis执行过程的关键。3. 数据操作的“边界”艺术更新、分页与批处理日常开发中更新、分页查询和批量操作是最容易踩坑的地方。处理不好轻则功能异常重则性能灾难。3.1updateById更新值为null的“陷阱”与“自由”MyBatis-Plus的BaseMapper.updateById方法默认使用的是“非null更新”策略。即当你传入一个实体对象只有不为null的字段才会被包含在SET子句中。这在本意上是好的避免了意外用null覆盖数据库中的已有值。场景用户只想修改昵称前端只传了id和nickname其他字段为null。使用updateById(user)只会生成UPDATE user SET nickname ? WHERE id ?符合预期。问题但有时我们确实需要将某个字段主动更新为null例如清空用户的备注信息。这时updateById就无能为力了因为它会忽略这个null值字段。解决方案使用UpdateWrapper这是MyBatis-Plus提供的更灵活的方式。UpdateWrapperUser updateWrapper new UpdateWrapper(); updateWrapper.eq(id, userId).set(remark, null); // 明确设置字段为null userMapper.update(null, updateWrapper);全局配置或注解策略在实体类字段上使用MyBatis-Plus的TableField注解。public class User { TableField(updateStrategy FieldStrategy.IGNORED) // 忽略策略无论是否为null都参与更新 private String remark; }警告FieldStrategy.IGNORED要慎用因为它意味着这个字段在任何更新操作中都会被纳入SQL容易导致误覆盖。更推荐在需要更新为null的特定业务方法中使用UpdateWrapper进行精细控制。背后的思考这个设计体现了MyBatis-Plus在便捷性和安全性之间的权衡。默认策略保护了数据而将“危险”的操作更新为null暴露为需要显式声明的行为。理解这一点就能根据场景选择正确的工具。3.2 分页查询的“深水区”分页是高频操作也是最容易出性能问题的地方。“全查出来”的误解有人问MyBatis分页怎么设置能全查出来是设置pageNum-1吗这是一个典型的误解。MyBatis的分页逻辑无论是使用PageHelper还是MyBatis-Plus的PaginationInterceptor/MybatisPlusInterceptor都是在SQL执行阶段通过拦截器改写SQL来实现的例如为MySQL加上LIMIT。它并不是一个简单的开关。pageNum和pageSize是业务参数拦截器根据它们计算offset和limit。设置pageNum-1对于拦截器来说是一个非法或无法解析的值通常会导致分页失效或异常。如果你真的需要不分页查询所有数据你应该直接调用普通的selectList方法而不是使用分页对象。大量数据分页的优化经典的LIMIT offset, size在offset非常大时例如LIMIT 1000000, 20MySQL需要先扫描并丢弃前100万行效率极低。优化方案1基于索引的“书签”分页Cursor。适用于顺序翻页场景如无限滚动。查询时记录上一页最后一条记录的ID或时间戳下一页查询条件为WHERE id last_id ORDER BY id LIMIT size。这种方式利用了索引的天然排序速度快如闪电。MyBatis提供了Cursor接口支持游标查询适合处理超大数据集流式读取但并非所有数据库驱动都支持。优化方案2子查询优化。先通过子查询快速定位到所需数据的ID范围再关联回原表取详情。SELECT * FROM your_table t1 JOIN (SELECT id FROM your_table WHERE ... ORDER BY ... LIMIT 1000000, 20) t2 ON t1.id t2.id;优化方案3业务降级。这是最务实的思考。用户真的需要翻到第50000页吗通常不需要。可以限制最大可查询页码或深度或者提供基于日期、分类的筛选来缩小范围而不是一个简单的“下一页”。MyBatis-Plus分页插件的正确配置确保你的分页插件被正确添加到拦截器链中。在最新版本中通常需要配置MybatisPlusInterceptor并为其添加PaginationInnerInterceptor。Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 添加分页拦截器 PaginationInnerInterceptor paginationInnerInterceptor new PaginationInnerInterceptor(DbType.MYSQL); paginationInnerInterceptor.setMaxLimit(1000L); // 设置单页最大记录数防止内存溢出 paginationInnerInterceptor.setOverflow(true); // 当请求页数超过总页数时是否返回首页 interceptor.addInnerInterceptor(paginationInnerInterceptor); // 还可以添加其他拦截器如乐观锁拦截器 return interceptor; } }3.3 批量操作的性能救赎循环调用单条insert或update是性能杀手。MyBatis提供了批量执行器ExecutorType.BATCH。开启批量模式// 方式1在获取SqlSession时指定 SqlSession sqlSession sqlSessionFactory.openSession(ExecutorType.BATCH); UserMapper mapper sqlSession.getMapper(UserMapper.class); for (User user : userList) { mapper.insert(user); } sqlSession.commit(); // 批量提交 sqlSession.close(); // 方式2在Spring管理的SqlSessionTemplate中使用编程式事务或声明式事务配合 Transactional public void batchInsert(ListUser users) { for (User user : users) { userMapper.insert(user); // 注意此处每调一次insert只是将语句添加到批处理队列并未执行 } // 方法结束事务提交时批处理中的语句才会一次性发送到数据库执行 }关键点在BATCH模式下mapper.insert(user)并不会立即执行SQL而是将预编译的语句和参数添加到批处理队列中。在commit()时才会一次性发送到数据库。这大大减少了网络往返和数据库事务开销。批量更新Batch UpdateMyBatis本身不支持像INSERT INTO ... VALUES (),(),()这样的多值语法。批量更新通常有两种方式使用foreach标签动态拼接SQL这在2.2节提到过最终会生成UPDATE table SET ... WHERE id IN (?)或者多条UPDATE ... WHERE id?的语句。对于MySQL可以配置连接参数rewriteBatchedStatementstrueJDBC驱动会尝试将多条结构相同的SQL重写为批处理语句提升性能。使用ExecutorType.BATCH如上面所示循环调用update方法让MyBatis进行批处理。这是更通用和推荐的方式。避坑指南批处理大小并非越大越好。一次性提交数万条SQL可能撑爆数据库的内存或日志。建议每500或1000条提交一次sqlSession.commit()然后清空批处理队列sqlSession.clearCache()不是必须但可用于清理一级缓存。事务批量操作必须放在一个事务中否则每条语句独立提交失去了批处理的意义。连接池确保你的数据库连接池如HikariCP配置了合理的maximumPoolSize因为批处理会话可能会占用连接较长时间。4. 映射与结果的“魔法”4.1resultMap的进阶用法解决“1对多”查询的重复数据问题这是一个经典问题查询一个订单Order及其多个订单项OrderItem使用一条SQL关联查询resultMap配置了collection。结果返回的List中Order对象重复了因为数据库返回的结果集是“订单项”行数。错误示例select idselectOrderWithItems resultMaporderMap SELECT o.*, i.* FROM order o LEFT JOIN order_item i ON o.id i.order_id /select resultMap idorderMap typeOrder id propertyid columnid/ result propertyorderNo columnorder_no/ collection propertyitems ofTypeOrderItem id propertyid columni_id/ !-- 注意别名 -- result propertyproductName columnproduct_name/ /collection /resultMap如果order表和order_item表有同名字段如idMyBatis在映射时会发生覆盖导致数据混乱。正确姿势SQL中使用别名区分这是必须的。SELECT o.id as o_id, o.order_no, i.id as i_id, i.product_name FROM order o LEFT JOIN order_item i ON o.id i.order_idresultMap中引用正确的别名id和result的column属性必须使用SQL中的别名。使用id标签MyBatis使用id标签来标识结果集中唯一的一行数据用于合并相同主键的对象。确保外层Order的id配置正确MyBatis才能自动将多个OrderItem合并到同一个Order对象的集合中。4.2 返回List时size1的诡异情况有时你执行一个预期返回多条记录的查询方法签名是ListYourType但得到的List的size()却是1。你打开这个唯一的元素发现里面的数据也不对劲。可能的原因SQL查询本身只返回一行这是首先要排查的。检查你的WHERE条件是否过于严格。resultMap映射错误最常见如上一点所述在关联查询中如果id标签配置错误或缺失MyBatis就无法正确区分不同的主对象。它可能将多行结果误认为是同一主对象的不同关联部分于是将它们“合并”到了一个对象里导致List里只有一个元素但这个元素里的集合属性可能包含了混乱的数据。务必检查关联查询的resultMap确保主对象的id标签指向能唯一标识该对象的列通常是主键并且使用了正确的别名。4.3 类型处理器TypeHandler的妙用超越基本类型映射MyBatis默认处理Java类型和JDBC类型VARCHAR,INTEGER等的转换。但有些场景需要自定义Java对象与JSON字符串的转换数据库存VARCHARJava实体类中是MapString, Object或一个自定义的Config对象。枚举类型的优雅处理数据库存int编码或varchar描述Java中是枚举。不想在业务代码里手动转换。加密字段入库自动加密出库自动解密。实现一个简单的枚举TypeHandlerMappedTypes({StatusEnum.class}) // 处理的Java类型 MappedJdbcTypes(JdbcType.INTEGER) // 对应的JDBC类型 public class StatusEnumTypeHandler extends BaseTypeHandlerStatusEnum { Override public void setNonNullParameter(PreparedStatement ps, int i, StatusEnum parameter, JdbcType jdbcType) throws SQLException { // 写入数据库时将枚举的code值存入 ps.setInt(i, parameter.getCode()); } Override public StatusEnum getNullableResult(ResultSet rs, String columnName) throws SQLException { // 从数据库读取时根据code值还原为枚举 int code rs.getInt(columnName); return StatusEnum.of(code); } // 重载其他getNullableResult方法... }配置使用在mybatis-config.xml中全局注册。typeHandlers typeHandler handlercom.yourpackage.StatusEnumTypeHandler/ /typeHandlers或者在字段上通过TableFieldMyBatis-Plus或resultMap的typeHandler属性局部指定。// MyBatis-Plus实体类 TableField(typeHandler StatusEnumTypeHandler.class) private StatusEnum status;自定义TypeHandler让数据映射更加清晰和类型安全将转换逻辑收敛到一处业务代码变得干净。5. 插件Interceptor开发深入MyBatis腹地插件是MyBatis最强大的扩展机制。它可以拦截四大核心对象Executor执行器、StatementHandler语句处理器、ParameterHandler参数处理器、ResultSetHandler结果集处理器的方法调用。这意味着你几乎可以干预SQL生命周期的任何一个环节。常见插件应用场景分页拦截Executor或StatementHandler在SQL执行前重写语句添加分页关键字。数据权限过滤拦截StatementHandler在WHERE条件中自动追加权限相关的过滤条件如dept_id ?。SQL性能监控/慢查询日志拦截StatementHandler的query或update方法计算执行时间超过阈值则报警或记录。字段自动填充拦截ParameterHandler的setParameters方法在插入或更新前为create_time、update_time等字段自动赋值。多租户数据隔离类似于数据权限在SQL中自动添加tenant_id ?条件。编写一个简单的SQL执行时间统计插件Intercepts({ Signature(type StatementHandler.class, method query, args {Statement.class, ResultHandler.class}), Signature(type StatementHandler.class, method update, args {Statement.class}) }) Component public class SqlCostTimeInterceptor implements Interceptor { private static final Logger log LoggerFactory.getLogger(SQL_PERF); Override public Object intercept(Invocation invocation) throws Throwable { long startTime System.currentTimeMillis(); try { // 继续执行原方法即执行SQL return invocation.proceed(); } finally { long costTime System.currentTimeMillis() - startTime; StatementHandler statementHandler (StatementHandler) invocation.getTarget(); BoundSql boundSql statementHandler.getBoundSql(); String sql boundSql.getSql(); // 简化处理实际可提取参数等更多信息 if (costTime 200) { // 假设200ms为慢查询阈值 log.warn(Slow SQL detected, cost: {} ms, SQL: {}, costTime, sql); } log.debug(SQL executed, cost: {} ms, costTime); } } Override public Object plugin(Object target) { return Plugin.wrap(target, this); } Override public void setProperties(Properties properties) { // 可以读取配置参数 } }插件配置在Spring Boot中只需将其声明为BeanMyBatis会自动发现并加载它。开发插件的心得谨慎操作插件能力强大但也危险。不要轻易修改BoundSql中的参数或SQL语句除非你很清楚后果。不当的修改可能导致SQL注入或数据错误。性能影响插件会增加方法调用的开销。尽量让插件的逻辑轻量避免在intercept方法中做复杂的IO操作。理解拦截点清楚你拦截的是哪个对象的哪个方法这个方法在SQL执行流程中处于什么位置。例如拦截ParameterHandler.setParameters可以在参数设置到PreparedStatement之前进行修改。6. 缓存的正确打开方式一级与二级缓存MyBatis提供了一级缓存本地缓存SqlSession级别和二级缓存全局缓存namespace级别。用好了是性能利器用错了就是“坑”王。一级缓存Local Cache范围默认开启在同一个SqlSession的生命周期内有效。行为执行查询后结果会被缓存。在同一个SqlSession中再次执行完全相同的SQL和参数会直接返回缓存结果不会访问数据库。失效执行任何INSERT、UPDATE、DELETE语句或调用sqlSession.clearCache()或关闭SqlSession都会清空该会话的一级缓存。坑点在Spring管理的SqlSessionTemplate中通常每次数据库操作都会使用一个独立的SqlSession具体取决于配置的事务隔离级别和SqlSession管理方式。这意味着你以为是同一个会话其实可能不是导致一级缓存表现不符合预期。在大多数Spring MyBatis的Web应用中一级缓存的作用范围很有限不要过度依赖它。二级缓存Second Level Cache范围需要手动在XML Mapper中通过cache/标签开启作用域是整个namespace即一个Mapper接口。序列化缓存的对象必须是可序列化的实现Serializable接口因为缓存可能被存储到磁盘或跨会话共享。脏读风险这是二级缓存最大的问题。如果多个SqlSession或应用实例操作同一张表一个实例更新了数据另一个实例的二级缓存可能还是旧值。因此在读写频繁、对实时性要求高的场景下不建议开启二级缓存。配置策略可以通过cache标签的eviction淘汰策略如LRU、flushInterval刷新间隔、size引用数目等属性进行精细控制。使用建议适用于读远多于写且数据实时性要求不高的场景如配置表、历史数据查询。在分布式环境下需要集成Redis、Ehcache等分布式缓存中间件来替代默认的PerpetualCache否则缓存无法在应用实例间共享。清晰定义缓存的namespace边界避免过大的缓存区域导致难以管理。我的实践对于大部分OLTP业务系统我倾向于关闭二级缓存。数据的实时性和一致性优先级更高。性能瓶颈更应通过数据库索引优化、业务缓存如Redis来解决。一级缓存了解其机制即可不作为核心优化手段。将MyBatis视为一个灵活的SQL映射框架而非缓存框架往往能做出更清晰的设计。7. 那些“冷门”但好用的核心API与技巧7.1 SqlSessionTemplate与SqlSessionManager在Spring集成中我们通常注入的是SqlSessionTemplate它是Spring对MyBatisSqlSession的包装是线程安全的。但你知道它内部是如何管理SqlSession的吗它通过SqlSessionInterceptor拦截器将每个事务方法调用与一个独立的SqlSession绑定事务结束后会自动关闭SqlSession。理解这一点就能明白为什么在非事务方法中连续调用多个Mapper方法可能无法利用一级缓存。SqlSessionManager则是一个更轻量级的、可同时充当工厂和会话的门面类。它允许你显式地获取和关闭SqlSession在某些需要精细控制会话生命周期的复杂场景下比如批量处理中手动控制提交点可能会用到。7.2 动态SQL中的script与SelectProvider对于极度复杂的动态SQL在XML中使用一堆if、choose标签可能使XML变得臃肿难读。这时可以考虑使用script标签内嵌动态SQL或者更彻底地使用SelectProvider注解。SelectProvider允许你指定一个类和方法该方法返回需要执行的SQL字符串。你可以用Java代码来动态拼接SQL利用Java强大的逻辑控制能力循环、条件、字符串处理。public class UserSqlProvider { public String selectUsersByComplexCondition(MapString, Object params) { return new SQL() {{ SELECT(*); FROM(user); if (params.get(name) ! null) { WHERE(name like #{name}); } if (params.get(statusList) ! null) { ListInteger statusList (ListInteger) params.get(statusList); String inClause statusList.stream() .map(String::valueOf) .collect(Collectors.joining(,, (, ))); WHERE(status in inClause); // 注意直接拼接有SQL注入风险此处仅为示例实际应用应使用动态SQL的foreach或Provider方法中的参数绑定 } ORDER_BY(create_time desc); }}.toString(); } } // Mapper接口中 SelectProvider(type UserSqlProvider.class, method selectUsersByComplexCondition) ListUser selectByComplexCondition(MapString, Object params);警告在Provider方法中手动拼接SQL字符串时必须极端警惕SQL注入。对于IN语句应使用MyBatis的foreach标签在XML中或通过ProviderMethodResolver等更安全的方式传递参数列表而不是直接拼接字符串。上面的示例中inClause的构建方式在生产环境中是不安全的。7.3 结果集自动映射的“小聪明”MyBatis的自动映射autoMappingBehavior默认是PARTIAL功能很强大。只要数据库列名下划线风格和Java对象属性名驼峰风格能对应上就不需要写冗长的resultMap。技巧如果你的实体类属性名和数据库列名不完全遵循下划线-驼峰转换规则可以使用Result注解在Mapper方法上做微调而不必定义完整的resultMap。Select(SELECT user_id, user_name, create_time FROM user) Results({ Result(property id, column user_id, id true), Result(property username, column user_name) }) ListUser selectAllUsers();这样既享受了自动映射的便利又处理了特殊的字段映射。玩转MyBatis关键在于理解其“约定大于配置”背后的灵活性边界。它没有试图封装一切而是提供了充足的扩展点和逃生通道。这些“奇巧淫技”本质上都是对MyBatis核心组件生命周期的深入理解和巧妙运用。从打印SQL开始到编写自定义插件结束这条路径上的每一个节点都藏着提升开发效率和系统稳定性的钥匙。别再只把它当做一个简单的SQL映射器了深入进去你会发现一个更强大的工具世界。 MyBatis进阶实战：从SQL日志到插件开发的高阶技巧
1. 从“能用”到“会玩”MyBatis的进阶之路如果你用过MyBatis大概率会觉得它就是个写SQL的框架把XML或者注解里的SQL映射成Java对象简单直接。这没错但如果你只停留在这个层面那可能只发挥了它30%的功力。我见过太多项目MyBatis的配置和用法千篇一律遇到稍微复杂点的场景就手忙脚乱要么是性能瓶颈要么是诡异的Bug最后只能归结于“MyBatis不好用”。其实很多时候问题出在我们自己身上没有真正理解它的设计哲学和那些藏在角落里的“奇巧淫技”。今天我们不聊怎么配置SqlSessionFactory也不说基础的insert、select。我们来深挖一下那些能让你的代码更优雅、性能更高效、排查问题更迅速的MyBatis高阶玩法。这些技巧有些来自官方文档的边角有些是社区实践中的智慧结晶还有一些是我自己踩过坑后总结出来的经验。它们可能不会出现在入门教程里但却是区分“MyBatis使用者”和“MyBatis玩家”的关键。2. 窥探与掌控SQL执行的“黑盒”透明化所有ORM框架的核心价值之一是简化数据库操作但随之而来的代价是SQL执行的“黑盒化”。你发出一条updateById却不知道它最终生成了什么SQL分页查询突然变慢你怀疑是MyBatis分页插件的锅却苦于没有证据。让SQL执行过程变得透明是高效开发和排查问题的第一步。2.1 多维度SQL日志打印不止于控制台大多数人知道在application.yml里加一行logging.level.你的Mapper包名: debug来打印SQL。但这只是基础而且日志混杂在应用日志中难以筛选。第一种集成专用MyBatis Log插件。这不是MyBatis的功能而是IDE如IntelliJ IDEA的插件。它通过拦截JDBC驱动层面的操作将MyBatis最终执行的SQL语句、参数、执行时间以非常清晰的格式在控制台单独输出。它的强大之处在于参数替换直接输出完整的、可拷贝到数据库客户端执行的SQL无需手动拼接参数。执行时间清晰显示每条SQL的执行耗时是定位慢查询的第一现场。独立窗口不与业务日志混杂一目了然。注意此插件依赖于IDE的调试机制在生产环境无效。它本质是一个本地开发调试工具。第二种配置MyBatis内置的日志实现。MyBatis支持多种日志框架SLF4J, Log4J2, Commons Logging等。通过配置可以让MyBatis输出更详细的执行信息包括Statement的创建与关闭有助于发现连接池或Statement未关闭的问题。参数映射详情可以看到每个参数是如何被设置到PreparedStatement中的。结果集映射详情对于复杂的resultMap可以看到每一行数据是如何被填充到对象属性中的。 配置方式通常是在mybatis-config.xml中设置configuration settings !-- 标准日志实现输出执行语句、参数、结果集数量 -- setting namelogImpl valueSTDOUT_LOGGING/ !-- 或者使用SLF4J配合logback-spring.xml调整特定Mapper的日志级别为DEBUG -- !-- setting namelogImpl valueSLF4J/ -- /settings /configuration使用STDOUT_LOGGING简单粗暴所有信息打到控制台。在生产环境更推荐结合logImplSLF4J并在日志配置文件中为org.apache.ibatis或你的Mapper接口设置DEBUG级别这样可以集成到你的ELK等日志系统中。第三种使用P6Spy或类似JDBC代理组件。这是最强大、也最“重”的方式。P6Spy是一个JDBC驱动代理它位于你的应用和真实JDBC驱动之间可以拦截所有数据库操作。你可以配置它输出格式化的SQL包含参数和耗时。记录慢查询超过阈值的SQL。甚至对SQL进行篡改危险操作慎用。 在Spring Boot中集成P6Spy后你需要将数据源URL从jdbc:mysql://...改为jdbc:p6spy:mysql://...并配置spy.properties。这种方式对代码无侵入且在生产环境也可用于监控但会带来轻微的性能开销和部署复杂度。2.2 动态SQL的调试看清if和foreach的真面目MyBatis的动态SQL标签if,choose,foreach,trim等非常方便但调试起来令人头疼。你传了一个空集合它到底有没有生成in语句某个条件为null时整个where子句会不会崩技巧输出BoundSql。在自定义插件或拦截器中可以获取到MappedStatement和运行时参数从而拿到BoundSql对象。BoundSql.getSql()方法返回的就是经过动态SQL解析、参数占位符?替换后的最终SQL字符串。虽然参数值还是?但你可以清晰地看到哪些if条件生效了foreach循环展开成了几个占位符。 一个更简单的临时方法是在Mapper接口方法上打调试断点在IDE的变量查看器中深入查看传入的SqlSession或执行器相关的对象往往也能找到BoundSql的踪迹。理解BoundSql是理解MyBatis执行过程的关键。3. 数据操作的“边界”艺术更新、分页与批处理日常开发中更新、分页查询和批量操作是最容易踩坑的地方。处理不好轻则功能异常重则性能灾难。3.1updateById更新值为null的“陷阱”与“自由”MyBatis-Plus的BaseMapper.updateById方法默认使用的是“非null更新”策略。即当你传入一个实体对象只有不为null的字段才会被包含在SET子句中。这在本意上是好的避免了意外用null覆盖数据库中的已有值。场景用户只想修改昵称前端只传了id和nickname其他字段为null。使用updateById(user)只会生成UPDATE user SET nickname ? WHERE id ?符合预期。问题但有时我们确实需要将某个字段主动更新为null例如清空用户的备注信息。这时updateById就无能为力了因为它会忽略这个null值字段。解决方案使用UpdateWrapper这是MyBatis-Plus提供的更灵活的方式。UpdateWrapperUser updateWrapper new UpdateWrapper(); updateWrapper.eq(id, userId).set(remark, null); // 明确设置字段为null userMapper.update(null, updateWrapper);全局配置或注解策略在实体类字段上使用MyBatis-Plus的TableField注解。public class User { TableField(updateStrategy FieldStrategy.IGNORED) // 忽略策略无论是否为null都参与更新 private String remark; }警告FieldStrategy.IGNORED要慎用因为它意味着这个字段在任何更新操作中都会被纳入SQL容易导致误覆盖。更推荐在需要更新为null的特定业务方法中使用UpdateWrapper进行精细控制。背后的思考这个设计体现了MyBatis-Plus在便捷性和安全性之间的权衡。默认策略保护了数据而将“危险”的操作更新为null暴露为需要显式声明的行为。理解这一点就能根据场景选择正确的工具。3.2 分页查询的“深水区”分页是高频操作也是最容易出性能问题的地方。“全查出来”的误解有人问MyBatis分页怎么设置能全查出来是设置pageNum-1吗这是一个典型的误解。MyBatis的分页逻辑无论是使用PageHelper还是MyBatis-Plus的PaginationInterceptor/MybatisPlusInterceptor都是在SQL执行阶段通过拦截器改写SQL来实现的例如为MySQL加上LIMIT。它并不是一个简单的开关。pageNum和pageSize是业务参数拦截器根据它们计算offset和limit。设置pageNum-1对于拦截器来说是一个非法或无法解析的值通常会导致分页失效或异常。如果你真的需要不分页查询所有数据你应该直接调用普通的selectList方法而不是使用分页对象。大量数据分页的优化经典的LIMIT offset, size在offset非常大时例如LIMIT 1000000, 20MySQL需要先扫描并丢弃前100万行效率极低。优化方案1基于索引的“书签”分页Cursor。适用于顺序翻页场景如无限滚动。查询时记录上一页最后一条记录的ID或时间戳下一页查询条件为WHERE id last_id ORDER BY id LIMIT size。这种方式利用了索引的天然排序速度快如闪电。MyBatis提供了Cursor接口支持游标查询适合处理超大数据集流式读取但并非所有数据库驱动都支持。优化方案2子查询优化。先通过子查询快速定位到所需数据的ID范围再关联回原表取详情。SELECT * FROM your_table t1 JOIN (SELECT id FROM your_table WHERE ... ORDER BY ... LIMIT 1000000, 20) t2 ON t1.id t2.id;优化方案3业务降级。这是最务实的思考。用户真的需要翻到第50000页吗通常不需要。可以限制最大可查询页码或深度或者提供基于日期、分类的筛选来缩小范围而不是一个简单的“下一页”。MyBatis-Plus分页插件的正确配置确保你的分页插件被正确添加到拦截器链中。在最新版本中通常需要配置MybatisPlusInterceptor并为其添加PaginationInnerInterceptor。Configuration public class MybatisPlusConfig { Bean public MybatisPlusInterceptor mybatisPlusInterceptor() { MybatisPlusInterceptor interceptor new MybatisPlusInterceptor(); // 添加分页拦截器 PaginationInnerInterceptor paginationInnerInterceptor new PaginationInnerInterceptor(DbType.MYSQL); paginationInnerInterceptor.setMaxLimit(1000L); // 设置单页最大记录数防止内存溢出 paginationInnerInterceptor.setOverflow(true); // 当请求页数超过总页数时是否返回首页 interceptor.addInnerInterceptor(paginationInnerInterceptor); // 还可以添加其他拦截器如乐观锁拦截器 return interceptor; } }3.3 批量操作的性能救赎循环调用单条insert或update是性能杀手。MyBatis提供了批量执行器ExecutorType.BATCH。开启批量模式// 方式1在获取SqlSession时指定 SqlSession sqlSession sqlSessionFactory.openSession(ExecutorType.BATCH); UserMapper mapper sqlSession.getMapper(UserMapper.class); for (User user : userList) { mapper.insert(user); } sqlSession.commit(); // 批量提交 sqlSession.close(); // 方式2在Spring管理的SqlSessionTemplate中使用编程式事务或声明式事务配合 Transactional public void batchInsert(ListUser users) { for (User user : users) { userMapper.insert(user); // 注意此处每调一次insert只是将语句添加到批处理队列并未执行 } // 方法结束事务提交时批处理中的语句才会一次性发送到数据库执行 }关键点在BATCH模式下mapper.insert(user)并不会立即执行SQL而是将预编译的语句和参数添加到批处理队列中。在commit()时才会一次性发送到数据库。这大大减少了网络往返和数据库事务开销。批量更新Batch UpdateMyBatis本身不支持像INSERT INTO ... VALUES (),(),()这样的多值语法。批量更新通常有两种方式使用foreach标签动态拼接SQL这在2.2节提到过最终会生成UPDATE table SET ... WHERE id IN (?)或者多条UPDATE ... WHERE id?的语句。对于MySQL可以配置连接参数rewriteBatchedStatementstrueJDBC驱动会尝试将多条结构相同的SQL重写为批处理语句提升性能。使用ExecutorType.BATCH如上面所示循环调用update方法让MyBatis进行批处理。这是更通用和推荐的方式。避坑指南批处理大小并非越大越好。一次性提交数万条SQL可能撑爆数据库的内存或日志。建议每500或1000条提交一次sqlSession.commit()然后清空批处理队列sqlSession.clearCache()不是必须但可用于清理一级缓存。事务批量操作必须放在一个事务中否则每条语句独立提交失去了批处理的意义。连接池确保你的数据库连接池如HikariCP配置了合理的maximumPoolSize因为批处理会话可能会占用连接较长时间。4. 映射与结果的“魔法”4.1resultMap的进阶用法解决“1对多”查询的重复数据问题这是一个经典问题查询一个订单Order及其多个订单项OrderItem使用一条SQL关联查询resultMap配置了collection。结果返回的List中Order对象重复了因为数据库返回的结果集是“订单项”行数。错误示例select idselectOrderWithItems resultMaporderMap SELECT o.*, i.* FROM order o LEFT JOIN order_item i ON o.id i.order_id /select resultMap idorderMap typeOrder id propertyid columnid/ result propertyorderNo columnorder_no/ collection propertyitems ofTypeOrderItem id propertyid columni_id/ !-- 注意别名 -- result propertyproductName columnproduct_name/ /collection /resultMap如果order表和order_item表有同名字段如idMyBatis在映射时会发生覆盖导致数据混乱。正确姿势SQL中使用别名区分这是必须的。SELECT o.id as o_id, o.order_no, i.id as i_id, i.product_name FROM order o LEFT JOIN order_item i ON o.id i.order_idresultMap中引用正确的别名id和result的column属性必须使用SQL中的别名。使用id标签MyBatis使用id标签来标识结果集中唯一的一行数据用于合并相同主键的对象。确保外层Order的id配置正确MyBatis才能自动将多个OrderItem合并到同一个Order对象的集合中。4.2 返回List时size1的诡异情况有时你执行一个预期返回多条记录的查询方法签名是ListYourType但得到的List的size()却是1。你打开这个唯一的元素发现里面的数据也不对劲。可能的原因SQL查询本身只返回一行这是首先要排查的。检查你的WHERE条件是否过于严格。resultMap映射错误最常见如上一点所述在关联查询中如果id标签配置错误或缺失MyBatis就无法正确区分不同的主对象。它可能将多行结果误认为是同一主对象的不同关联部分于是将它们“合并”到了一个对象里导致List里只有一个元素但这个元素里的集合属性可能包含了混乱的数据。务必检查关联查询的resultMap确保主对象的id标签指向能唯一标识该对象的列通常是主键并且使用了正确的别名。4.3 类型处理器TypeHandler的妙用超越基本类型映射MyBatis默认处理Java类型和JDBC类型VARCHAR,INTEGER等的转换。但有些场景需要自定义Java对象与JSON字符串的转换数据库存VARCHARJava实体类中是MapString, Object或一个自定义的Config对象。枚举类型的优雅处理数据库存int编码或varchar描述Java中是枚举。不想在业务代码里手动转换。加密字段入库自动加密出库自动解密。实现一个简单的枚举TypeHandlerMappedTypes({StatusEnum.class}) // 处理的Java类型 MappedJdbcTypes(JdbcType.INTEGER) // 对应的JDBC类型 public class StatusEnumTypeHandler extends BaseTypeHandlerStatusEnum { Override public void setNonNullParameter(PreparedStatement ps, int i, StatusEnum parameter, JdbcType jdbcType) throws SQLException { // 写入数据库时将枚举的code值存入 ps.setInt(i, parameter.getCode()); } Override public StatusEnum getNullableResult(ResultSet rs, String columnName) throws SQLException { // 从数据库读取时根据code值还原为枚举 int code rs.getInt(columnName); return StatusEnum.of(code); } // 重载其他getNullableResult方法... }配置使用在mybatis-config.xml中全局注册。typeHandlers typeHandler handlercom.yourpackage.StatusEnumTypeHandler/ /typeHandlers或者在字段上通过TableFieldMyBatis-Plus或resultMap的typeHandler属性局部指定。// MyBatis-Plus实体类 TableField(typeHandler StatusEnumTypeHandler.class) private StatusEnum status;自定义TypeHandler让数据映射更加清晰和类型安全将转换逻辑收敛到一处业务代码变得干净。5. 插件Interceptor开发深入MyBatis腹地插件是MyBatis最强大的扩展机制。它可以拦截四大核心对象Executor执行器、StatementHandler语句处理器、ParameterHandler参数处理器、ResultSetHandler结果集处理器的方法调用。这意味着你几乎可以干预SQL生命周期的任何一个环节。常见插件应用场景分页拦截Executor或StatementHandler在SQL执行前重写语句添加分页关键字。数据权限过滤拦截StatementHandler在WHERE条件中自动追加权限相关的过滤条件如dept_id ?。SQL性能监控/慢查询日志拦截StatementHandler的query或update方法计算执行时间超过阈值则报警或记录。字段自动填充拦截ParameterHandler的setParameters方法在插入或更新前为create_time、update_time等字段自动赋值。多租户数据隔离类似于数据权限在SQL中自动添加tenant_id ?条件。编写一个简单的SQL执行时间统计插件Intercepts({ Signature(type StatementHandler.class, method query, args {Statement.class, ResultHandler.class}), Signature(type StatementHandler.class, method update, args {Statement.class}) }) Component public class SqlCostTimeInterceptor implements Interceptor { private static final Logger log LoggerFactory.getLogger(SQL_PERF); Override public Object intercept(Invocation invocation) throws Throwable { long startTime System.currentTimeMillis(); try { // 继续执行原方法即执行SQL return invocation.proceed(); } finally { long costTime System.currentTimeMillis() - startTime; StatementHandler statementHandler (StatementHandler) invocation.getTarget(); BoundSql boundSql statementHandler.getBoundSql(); String sql boundSql.getSql(); // 简化处理实际可提取参数等更多信息 if (costTime 200) { // 假设200ms为慢查询阈值 log.warn(Slow SQL detected, cost: {} ms, SQL: {}, costTime, sql); } log.debug(SQL executed, cost: {} ms, costTime); } } Override public Object plugin(Object target) { return Plugin.wrap(target, this); } Override public void setProperties(Properties properties) { // 可以读取配置参数 } }插件配置在Spring Boot中只需将其声明为BeanMyBatis会自动发现并加载它。开发插件的心得谨慎操作插件能力强大但也危险。不要轻易修改BoundSql中的参数或SQL语句除非你很清楚后果。不当的修改可能导致SQL注入或数据错误。性能影响插件会增加方法调用的开销。尽量让插件的逻辑轻量避免在intercept方法中做复杂的IO操作。理解拦截点清楚你拦截的是哪个对象的哪个方法这个方法在SQL执行流程中处于什么位置。例如拦截ParameterHandler.setParameters可以在参数设置到PreparedStatement之前进行修改。6. 缓存的正确打开方式一级与二级缓存MyBatis提供了一级缓存本地缓存SqlSession级别和二级缓存全局缓存namespace级别。用好了是性能利器用错了就是“坑”王。一级缓存Local Cache范围默认开启在同一个SqlSession的生命周期内有效。行为执行查询后结果会被缓存。在同一个SqlSession中再次执行完全相同的SQL和参数会直接返回缓存结果不会访问数据库。失效执行任何INSERT、UPDATE、DELETE语句或调用sqlSession.clearCache()或关闭SqlSession都会清空该会话的一级缓存。坑点在Spring管理的SqlSessionTemplate中通常每次数据库操作都会使用一个独立的SqlSession具体取决于配置的事务隔离级别和SqlSession管理方式。这意味着你以为是同一个会话其实可能不是导致一级缓存表现不符合预期。在大多数Spring MyBatis的Web应用中一级缓存的作用范围很有限不要过度依赖它。二级缓存Second Level Cache范围需要手动在XML Mapper中通过cache/标签开启作用域是整个namespace即一个Mapper接口。序列化缓存的对象必须是可序列化的实现Serializable接口因为缓存可能被存储到磁盘或跨会话共享。脏读风险这是二级缓存最大的问题。如果多个SqlSession或应用实例操作同一张表一个实例更新了数据另一个实例的二级缓存可能还是旧值。因此在读写频繁、对实时性要求高的场景下不建议开启二级缓存。配置策略可以通过cache标签的eviction淘汰策略如LRU、flushInterval刷新间隔、size引用数目等属性进行精细控制。使用建议适用于读远多于写且数据实时性要求不高的场景如配置表、历史数据查询。在分布式环境下需要集成Redis、Ehcache等分布式缓存中间件来替代默认的PerpetualCache否则缓存无法在应用实例间共享。清晰定义缓存的namespace边界避免过大的缓存区域导致难以管理。我的实践对于大部分OLTP业务系统我倾向于关闭二级缓存。数据的实时性和一致性优先级更高。性能瓶颈更应通过数据库索引优化、业务缓存如Redis来解决。一级缓存了解其机制即可不作为核心优化手段。将MyBatis视为一个灵活的SQL映射框架而非缓存框架往往能做出更清晰的设计。7. 那些“冷门”但好用的核心API与技巧7.1 SqlSessionTemplate与SqlSessionManager在Spring集成中我们通常注入的是SqlSessionTemplate它是Spring对MyBatisSqlSession的包装是线程安全的。但你知道它内部是如何管理SqlSession的吗它通过SqlSessionInterceptor拦截器将每个事务方法调用与一个独立的SqlSession绑定事务结束后会自动关闭SqlSession。理解这一点就能明白为什么在非事务方法中连续调用多个Mapper方法可能无法利用一级缓存。SqlSessionManager则是一个更轻量级的、可同时充当工厂和会话的门面类。它允许你显式地获取和关闭SqlSession在某些需要精细控制会话生命周期的复杂场景下比如批量处理中手动控制提交点可能会用到。7.2 动态SQL中的script与SelectProvider对于极度复杂的动态SQL在XML中使用一堆if、choose标签可能使XML变得臃肿难读。这时可以考虑使用script标签内嵌动态SQL或者更彻底地使用SelectProvider注解。SelectProvider允许你指定一个类和方法该方法返回需要执行的SQL字符串。你可以用Java代码来动态拼接SQL利用Java强大的逻辑控制能力循环、条件、字符串处理。public class UserSqlProvider { public String selectUsersByComplexCondition(MapString, Object params) { return new SQL() {{ SELECT(*); FROM(user); if (params.get(name) ! null) { WHERE(name like #{name}); } if (params.get(statusList) ! null) { ListInteger statusList (ListInteger) params.get(statusList); String inClause statusList.stream() .map(String::valueOf) .collect(Collectors.joining(,, (, ))); WHERE(status in inClause); // 注意直接拼接有SQL注入风险此处仅为示例实际应用应使用动态SQL的foreach或Provider方法中的参数绑定 } ORDER_BY(create_time desc); }}.toString(); } } // Mapper接口中 SelectProvider(type UserSqlProvider.class, method selectUsersByComplexCondition) ListUser selectByComplexCondition(MapString, Object params);警告在Provider方法中手动拼接SQL字符串时必须极端警惕SQL注入。对于IN语句应使用MyBatis的foreach标签在XML中或通过ProviderMethodResolver等更安全的方式传递参数列表而不是直接拼接字符串。上面的示例中inClause的构建方式在生产环境中是不安全的。7.3 结果集自动映射的“小聪明”MyBatis的自动映射autoMappingBehavior默认是PARTIAL功能很强大。只要数据库列名下划线风格和Java对象属性名驼峰风格能对应上就不需要写冗长的resultMap。技巧如果你的实体类属性名和数据库列名不完全遵循下划线-驼峰转换规则可以使用Result注解在Mapper方法上做微调而不必定义完整的resultMap。Select(SELECT user_id, user_name, create_time FROM user) Results({ Result(property id, column user_id, id true), Result(property username, column user_name) }) ListUser selectAllUsers();这样既享受了自动映射的便利又处理了特殊的字段映射。玩转MyBatis关键在于理解其“约定大于配置”背后的灵活性边界。它没有试图封装一切而是提供了充足的扩展点和逃生通道。这些“奇巧淫技”本质上都是对MyBatis核心组件生命周期的深入理解和巧妙运用。从打印SQL开始到编写自定义插件结束这条路径上的每一个节点都藏着提升开发效率和系统稳定性的钥匙。别再只把它当做一个简单的SQL映射器了深入进去你会发现一个更强大的工具世界。