1. 项目概述为什么我们要深入MyBatis源码如果你是一名Java后端开发者那么MyBatis几乎是你绕不开的一个技术组件。无论是面试中被问及“#{}和${}的区别”还是在工作中排查一个诡异的SQL执行问题抑或是想定制一个符合自己业务场景的插件最终你都会发现仅仅停留在API的使用层面是远远不够的。我最初接触MyBatis时也只是满足于能写出正确的XML映射文件直到有一次线上出现了一个因动态SQL拼接错误导致的全表查询性能瞬间雪崩。当时对着日志里那串陌生的、被MyBatis处理后的SQL我束手无策只能凭感觉瞎猜。那次教训让我下定决心必须把MyBatis这层“黑盒”打开看看。“mybatis源码学习”这个标题听起来像是一个庞大的工程容易让人望而生畏。但它的核心价值非常明确理解MyBatis如何将我们编写的接口、XML与JDBC这个底层标准连接起来从而获得在复杂场景下排错、优化乃至定制的主动权。这不是为了炫技而是为了在关键时刻你能清晰地知道问题出在SqlSession的哪一次调用是Executor的哪个环节或是StatementHandler对参数做了怎样的处理。学习它的源码就像是拿到了数据库访问层的“电路图”从此不再是凭经验“盲修”。2. 核心架构与执行流程总览在深入代码细节之前我们必须先建立起对MyBatis整体架构的宏观认知。MyBatis的核心设计遵循了职责分离的原则其主干流程可以概括为通过配置初始化一系列核心对象然后通过SqlSession这个门面驱动一条职责明确的执行链来处理我们的数据库操作请求。2.1 核心组件职责解析MyBatis的运转依赖于几个核心组件它们像齿轮一样紧密咬合SqlSessionFactory这是整个MyBatis的“兵工厂”。它的唯一职责就是生产SqlSession对象。SqlSessionFactory在应用启动时通过解析mybatis-config.xml全局配置文件和所有的Mapper.xml文件构建出一个包含了所有配置信息环境、数据源、事务管理器、映射关系等的Configuration对象。这个初始化过程非常关键它决定了后续所有操作的行为基础。SqlSession这是面向开发者的核心API门面。你可以把它理解为一次数据库会话或一次工作单元。我们所有调用Mapper接口的方法最终都会被委托到某个SqlSession实例的具体方法上如selectOne,insert,update等。它本身并不直接执行SQL而是将请求派发给真正的执行器。Executor执行器是MyBatis的“大脑”负责整个SQL执行过程的调度。它主要处理缓存、事务以及将数据库操作委托给StatementHandler。MyBatis内置了几种执行器比如简单执行器SimpleExecutor每次请求都创建新的Statement、可重用执行器ReuseExecutor复用Statement和批处理执行器BatchExecutor。一级缓存也叫本地缓存就存在于Executor的实现中。StatementHandler它是与JDBCStatement对象打交道的“双手”。它负责创建Statement对象、对SQL语句进行参数化即把#{}替换为?并设置参数、执行SQL以及将JDBC返回的ResultSet映射成Java对象。我们常用的插件Plugin就是通过拦截StatementHandler以及ParameterHandler,ResultSetHandler来实现功能的。ParameterHandler参数处理器专门负责将我们传入的Java参数按照映射规则设置到PreparedStatement的占位符?中。这里处理的就是#{}和${}的差异所在。ResultSetHandler结果集处理器它的任务是将Statement执行后返回的ResultSet根据我们在Mapper.xml中定义的resultMap或resultType转换成一个或多个Java对象。MappedStatement这是一个非常重要的内部对象。它是对Mapper XML文件中一个SQL语句节点如select、insert的完全解析和封装。里面包含了该SQL的ID、SQL源码、参数类型、返回类型、执行类型SELECT/INSERT等、以及相关的SqlSource和ResultMap等信息。可以把它看作是MyBatis内部执行一条SQL的“作战指令”。注意理解这些组件的职责和协作关系是后续调试和阅读源码的基础。当遇到问题时你可以快速定位可能是哪个“齿轮”出了状况。例如SQL执行慢但日志中SQL本身没问题可能需要看Executor的缓存或StatementHandler的创建策略参数传递错误则首要关注ParameterHandler。2.2 一次查询请求的完整旅程让我们跟随一次最简单的sqlSession.selectOne(com.example.UserMapper.selectById, 1)调用看看请求是如何流转的入口与路由SqlSession接收到调用请求它首先会根据传入的Statement ID如com.example.UserMapper.selectById从全局Configuration对象中获取到对应的MappedStatement对象。这个对象包含了执行这条SQL所需的一切元信息。执行器调度SqlSession将获取到的MappedStatement和参数对象交给当前会话关联的Executor实例。Executor会先查询自己维护的一级缓存如果开启且是SELECT操作如果缓存命中则直接返回避免数据库访问。SQL准备与参数化如果缓存未命中Executor会创建一个新的StatementHandler实例同时也会创建对应的ParameterHandler和ResultSetHandler。StatementHandler会从MappedStatement中获取SqlSource。SqlSource负责根据传入的参数动态地如果SQL是动态的或静态地生成最终的、可被JDBC执行的SQL字符串。对于#{}此时会被替换为?生成PreparedStatement。参数绑定StatementHandler调用ParameterHandler。ParameterHandler利用MappedStatement中关于参数类型的元数据TypeHandler将我们传入的Java对象例如Integer类型的1设置到PreparedStatement对应的?占位符上。执行与结果映射StatementHandler执行PreparedStatement获得ResultSet。随后ResultSetHandler登场它遍历ResultSet的每一行根据MappedStatement中定义的ResultMap调用相应的TypeHandler将数据库字段值填充到目标Java对象如User对象的属性中。返回与缓存映射得到的对象被返回给Executor。Executor可能会将其存入一级缓存如果配置允许然后最终通过SqlSession返回给调用者。这个过程清晰地展示了MyBatis如何将高层接口调用逐步分解、转化最终通过JDBC与数据库交互并将结果逆向转换回来。源码学习的很多工作就是深入这个流程的每一个环节看它们具体如何实现。3. 核心源码模块深度解析掌握了主干流程我们就可以有针对性地深入几个最核心、也最常被问及的模块进行剖析。3.1 配置解析与初始化一切的起点MyBatis的启动始于SqlSessionFactoryBuilder.build()方法。它接受一个输入流指向我们的配置文件并委托给XMLConfigBuilder来解析。// 简化的解析过程示意 public SqlSessionFactory build(InputStream inputStream) { // 1. 创建配置解析器 XMLConfigBuilder parser new XMLConfigBuilder(inputStream, environment, properties); // 2. 解析XML生成Configuration对象 Configuration config parser.parse(); // 3. 使用Configuration构建SqlSessionFactory return new DefaultSqlSessionFactory(config); }XMLConfigBuilder.parse()方法会按顺序解析配置文件的所有部分properties加载外部属性用于后续的占位符替换。settings解析全局设置如缓存、懒加载、日志实现等这些设置会直接影响核心组件的行为。typeAliases为Java类型设置简称方便在映射文件中使用。plugins这里是插件机制初始化的关键。MyBatis会使用Java动态代理将配置的拦截器Interceptor包装到目标组件Executor,StatementHandler等上。environments解析数据源DataSource和事务管理器TransactionFactory。mappers这是重头戏。解析器会根据这里注册的Mapper接口或XML文件路径去加载具体的SQL映射信息。Mapper的加载过程尤其重要对于XML方式会使用XMLMapperBuilder来解析Mapper.xml文件。解析每一个select|insert|update|delete节点创建对应的MappedStatement对象并以namespace.id为Key存入Configuration的MapString, MappedStatement中。对于接口方式MyBatis会使用MapperAnnotationBuilder来解析接口上的注解如Select同样生成MappedStatement。同时MyBatis会为每个Mapper接口创建一个动态代理对象MapperProxy并将其注册到Configuration中。当我们从SqlSession获取Mapper接口实例时返回的就是这个代理对象。这也是为什么我们调用接口方法就能执行SQL的根本原因。实操心得在阅读这部分源码时可以重点关注Configuration这个类。它像一个中央仓库存放了MyBatis运行时的所有配置元数据。很多高级特性如插件、对象工厂、类型处理器注册中心都在这里管理。理解它的结构对后续理解其他模块如何获取配置至关重要。3.2 SQL解析与动态SQL生成MyBatis的强大特性之一就是动态SQL。在MappedStatement中SQL的来源被抽象为SqlSource接口。其核心实现类DynamicSqlSource负责处理包含if,where,foreach等标签的动态SQL。解析过程分为两步脚本解析在初始化阶段XMLScriptBuilder会将XML节点树解析成一个由SqlNode对象组成的混合树。例如一个if标签对应一个IfSqlNodeforeach对应一个ForEachSqlNode。这些SqlNode构成了描述SQL如何动态生成的“脚本”。运行时应用当执行SQL时DynamicSqlSource.getBoundSql()方法被调用。它会创建一个DynamicContext对象其中包含了传入的参数对象。然后遍历SqlNode树每个SqlNode根据当前参数上下文判断自己是否应该生效并将生效部分的SQL片段追加到DynamicContext中。最终拼接出一个完整的、静态的SQL字符串。// 简化的动态SQL应用过程 public BoundSql getBoundSql(Object parameterObject) { DynamicContext context new DynamicContext(configuration, parameterObject); // rootSqlNode 是解析后的 SqlNode 树根节点 rootSqlNode.apply(context); // 从context中获取拼接好的SQL字符串 String sql context.getSql(); // ... 后续处理参数映射 return new BoundSql(configuration, sql, parameterMappings, parameterObject); }这里有一个关键点最终生成的SQL字符串中所有#{}占位符已经被替换成了?而${}则被直接替换为对应的参数值字符串拼接。#{}对应的参数信息参数名、Java类型、JDBC类型等会被收集到BoundSql的parameterMappings列表中供后续的ParameterHandler使用。注意事项动态SQL的解析和应用是在每次执行时都可能发生的除非使用缓存。对于极其复杂的动态SQL这可能带来微小的性能开销。在超高并发场景下如果SQL模式固定可以考虑将其简化为静态SQL或利用MyBatis的二级缓存来避免重复解析。3.3 参数处理与结果映射TypeHandler的核心作用这是MyBatis实现ORM对象关系映射的关键而背后的功臣是TypeHandler类型处理器。参数处理 (ParameterHandler) 当PreparedStatement需要设置参数时ParameterHandler会根据BoundSql中的parameterMappings为每一个映射找到对应的TypeHandler。// 简化版的参数设置逻辑 for (ParameterMapping mapping : parameterMappings) { TypeHandler typeHandler mapping.getTypeHandler(); Object value ... // 从参数对象中取出当前映射对应的值 typeHandler.setParameter(ps, i, value, mapping.getJdbcType()); }TypeHandler接口定义了如何将Java类型如String,Integer,Date甚至是自定义的枚举与JDBC类型VARCHAR,INTEGER,TIMESTAMP相互转换。MyBatis为所有常见类型提供了内置实现。例如StringTypeHandler会调用ps.setString()。结果映射 (ResultSetHandler) 处理结果集时逻辑类似但更复杂。ResultSetHandler会遍历结果集的每一行然后根据ResultMap的描述为每一列找到对应的TypeHandler从ResultSet中获取值并设置到目标对象的属性中。// 简化版的结果映射逻辑 while (rs.next()) { Object resultObject createResultObject(...); // 创建结果对象实例 for (ResultMapping mapping : resultMap.getPropertyResultMappings()) { String property mapping.getProperty(); TypeHandler typeHandler mapping.getTypeHandler(); Object value typeHandler.getResult(rs, columnName); // 使用反射或元对象将value设置到resultObject的property属性上 MetaObject.forObject(resultObject).setValue(property, value); } resultList.add(resultObject); }MetaObject这是MyBatis提供的一个反射工具类它封装了复杂的反射操作可以安全、高效地读写对象的属性包括私有属性、通过Getter/Setter支持嵌套属性如user.address.city的访问。它在结果映射和参数提取中广泛使用。避坑技巧自定义TypeHandler是处理特殊数据类型的利器比如将数据库中的VARCHAR字段映射为Java枚举或者将JSON字符串映射为Map或实体对象。实现时除了实现setParameter和getResult方法别忘了在配置文件中注册它或者在映射文件中通过typeHandler属性指定。3.4 插件机制原理与自定义实现MyBatis的插件Plugin机制基于Java动态代理和责任链模式提供了强大的扩展能力。它可以拦截四大核心组件的方法调用Executor,StatementHandler,ParameterHandler,ResultSetHandler。实现原理定义拦截器你需要实现Interceptor接口重写intercept方法在这里编写你的拦截逻辑。使用Intercepts和Signature注解指定你要拦截哪个接口的哪个方法。Intercepts({ Signature(type StatementHandler.class, method prepare, args {Connection.class, Integer.class}) }) public class MyPlugin implements Interceptor { Override public Object intercept(Invocation invocation) throws Throwable { // 1. 前置处理例如修改SQL StatementHandler handler (StatementHandler) invocation.getTarget(); BoundSql boundSql handler.getBoundSql(); String sql boundSql.getSql(); // ... 对sql进行修改 // 2. 执行原方法 Object result invocation.proceed(); // 3. 后置处理 return result; } }代理包装在MyBatis初始化时Configuration的pluginElement方法会读取所有配置的拦截器。当创建上述四大组件的实例时会调用InterceptorChain.pluginAll()方法。这个方法会遍历所有拦截器对目标对象进行层层包装。// 简化流程 public Object pluginAll(Object target) { for (Interceptor interceptor : interceptors) { target interceptor.plugin(target); // 通常调用Plugin.wrap方法 } return target; // 返回的是被代理链层层包裹后的对象 }Plugin.wrap()方法会使用JDK动态代理创建一个实现了目标接口的代理对象。这个代理对象的InvocationHandler就是Plugin类本身。当代理对象的方法被调用时会先进入Plugin.invoke()它判断该方法是否被拦截器声明拦截如果是则调用拦截器的intercept方法否则直接调用原方法。经典应用场景分页插件拦截StatementHandler.prepare方法在原始SQL上拼接LIMIT ?, ?或类似的数据库方言分页语句。SQL执行性能监控拦截StatementHandler.query/update方法记录SQL执行开始和结束时间计算耗时并打印或上报。数据权限过滤拦截StatementHandler.prepare或ParameterHandler相关方法在SQL的WHERE条件中自动追加数据权限过滤条件。MyBatis-Plus等增强工具其核心功能大多基于插件机制实现。实操心得编写插件时要特别注意代理链的顺序。多个插件会按配置顺序形成代理链。在intercept方法中务必调用invocation.proceed()来将调用传递到链中的下一个拦截器或最终的目标方法否则执行链会在此中断。另外修改BoundSql中的SQL字符串需要谨慎因为它是不可变对象通常需要利用反射来修改其内部字段这存在一定的兼容性风险。4. 高级特性与内部机制剖析除了主干流程MyBatis还有一些高级特性和内部机制理解它们能让你更全面地掌握这个框架。4.1 一级缓存与二级缓存一级缓存本地缓存作用域SqlSession级别。同一个SqlSession内执行相同的查询第二次会直接返回缓存的对象。实现位置在BaseExecutor中有一个localCache字段PerpetualCache类型。生命周期与SqlSession共存亡。当执行insert,update,delete操作或调用sqlSession.clearCache()或关闭SqlSession时缓存会被清空。注意点一级缓存默认开启且无法关闭。在分布式或Web应用中由于SqlSession通常与一次请求绑定如集成Spring后作用域可能是request一级缓存的作用有限且可能因为脏读问题带来麻烦例如一个请求内先查后改再查可能读到旧数据。二级缓存作用域Mappernamespace级别跨SqlSession共享。开启条件需要在全局配置中设置cacheEnabledtrue默认为true并在具体的Mapper XML文件中使用cache/标签。实现原理当开启二级缓存后Executor会被一个CachingExecutor装饰。查询时CachingExecutor先查询二级缓存命中则返回未命中则委托给真正的Executor如SimpleExecutor去数据库查询并将结果存入二级缓存。更新操作增删改会清空其所在namespace的二级缓存。序列化要求由于缓存对象可能被序列化到磁盘或传输到其他节点取决于缓存实现如Redis因此被缓存的对象必须实现Serializable接口。脏读风险二级缓存是应用层缓存当多个应用实例或直接操作数据库时极易导致数据不一致。在生产环境中使用需要非常谨慎通常只用于极少修改的静态数据。4.2 懒加载延迟加载MyBatis的懒加载是针对关联查询association,collection的优化。它的核心思想是只有当真正访问到关联对象的属性时才去执行额外的SQL查询来加载数据。实现机制在查询主对象时MyBatis返回的并不是一个普通的实体对象而是一个该实体对象的动态代理对象由Javassist或CGLib创建。这个代理对象中持有了一个ResultLoader结果加载器里面包含了加载关联对象所需的所有信息SQL、参数等。当你调用代理对象的Getter方法如user.getOrderList()时拦截器会触发调用ResultLoader去数据库执行查询并将结果加载回来。配置要点在association或collection标签中设置fetchTypelazy。全局配置lazyLoadingEnabled需要为true。还需要配置aggressiveLazyLoading侵略性延迟加载为false否则任何方法调用都会触发所有懒加载属性的加载。注意事项懒加载在带来性能好处的同时也引入了“N1查询问题”的风险如果在循环中访问懒加载属性。同时由于产生了代理对象在序列化、类型判断如instanceof时可能会遇到意外情况。在事务边界外访问懒加载属性会失败因为SQL执行需要数据库连接。4.3 日志模块与SQL追踪MyBatis没有直接实现日志而是提供了一个桥接接口org.apache.ibatis.logging.Log它整合了多种第三方日志框架SLF4J, Log4j2, Log4j, Commons Logging, JDK Logging。其采用“静态代理动态加载”的模式在初始化时会按优先级顺序尝试加载各个日志框架的实现类使用第一个成功的。打印SQL日志 我们通常配置的日志级别是DEBUG。当Log的实现类如Slf4jImpl在DEBUG级别下MyBatis的核心组件通常是BaseExecutor和StatementHandler会在关键节点打印日志。BaseExecutor在创建缓存Key、查询数据库前会打印SQL语句此时参数还是?。真正的参数替换后的SQL需要借助插件如MyBatis Log Free或开启StatementHandler的详细日志才能看到。使用Arthas等工具追踪SQL 有时候日志没打出来或者想动态查看可以使用Arthas。其原理是通过Java Agent技术进行字节码增强。例如你可以使用trace命令跟踪org.apache.ibatis.executor.statement.PreparedStatementHandler的query方法从而看到SQL执行耗时和参数信息。这比修改配置重启应用要灵活得多。5. 常见问题排查与调试技巧理论学习最终要服务于实践。下面是我在多年使用和源码阅读中总结的一些典型问题排查思路。5.1 SQL执行相关异常排查问题现象可能原因排查思路与工具BindingException: Parameter ‘xxx’ not found1. Mapper方法参数未使用Param注解且参数名在编译后丢失变成arg0, arg1。2.#{}或${}中的属性名拼写错误。3. 参数本身为null。1. 检查接口方法确认多参数时使用了Param。2. 开启MyBatis的日志到TRACE级别查看ParameterHandler设置参数时的具体映射信息。3. 使用调试工具在DefaultParameterHandler.setParameters()方法打断点查看parameterMappings和实际参数值。SQL语句在日志中显示正确但执行报语法错误1. SQL中存在需要转义的特殊字符如,在XML中未正确转义。2. 动态SQL拼接在某种参数条件下产生非法语法如WHERE AND。1. 检查XML中的SQL将替换为lt;替换为gt;。2.关键步骤将MyBatis日志级别设为DEBUG查看BoundSql.getSql()返回的最终SQL字符串复制到数据库客户端执行验证。查询结果映射失败部分字段为null1. 数据库字段名与Java属性名未遵循命名映射规则下划线转驼峰未开启。2.ResultMap配置错误或未指定。3. 对应的TypeHandler缺失或异常。1. 确认全局配置mapUnderscoreToCamelCase是否开启。2. 检查ResultMap的column与property对应关系。3. 在ResultSetHandler处理结果集的位置打断点查看从ResultSet取出的值是否正确。执行update返回影响行数始终为1或不对1. 可能是MyBatis的默认Executor类型问题。SimpleExecutor每次都会提交。2. 事务未正确管理。1. 确认在获取SqlSession时使用的ExecutorType。2. 检查事务是否由Spring等框架管理确保操作在同一个事务内。5.2 性能问题分析与优化建议N1查询问题这是ORM框架的通病。表现为查询一个列表1次查询然后遍历列表访问每个元素的懒加载关联属性N次查询。解决方案尽量使用collection或association标签进行联表查询一次性通过JOIN取出所有数据。虽然结果映射ResultMap会复杂一些但能从根本上消除N1问题。动态SQL解析开销极其复杂的动态SQL多层嵌套if,foreach会在每次执行时解析带来CPU开销。优化建议对于执行频率极高且模式固定的SQL考虑将其拆分为多条静态SQL通过业务逻辑判断来调用。或者利用MyBatis的二级缓存需谨慎缓存解析后的BoundSql。大批量数据操作使用foreach进行批量插入时如果数据量巨大如数万条拼接的SQL会非常长可能导致数据库报文超限或内存占用过高。优化方案改用BatchExecutor。在获取SqlSession时指定ExecutorType.BATCH然后在循环中多次调用insert方法最后统一执行sqlSession.flushStatements()和提交事务。这样会将多个操作打包成一个JDBC批处理效率高很多。日志输出开销在生产环境开启DEBUG日志会打印所有SQL产生大量IO影响性能。建议使用日志框架的配置将MyBatis的日志级别控制在INFO或WARN。需要排查问题时可以动态调整特定Mapper的日志级别或使用Arthas等在线诊断工具进行临时追踪。5.3 源码调试环境搭建与实践指南“纸上得来终觉浅绝知此事要躬行。” 要真正理解源码必须动手调试。准备源码从MyBatis的GitHub仓库克隆代码或直接下载Release版本的源码包。建议选择一个稳定的版本如3.5.x。构建与引入使用Maven或Gradle将源码项目安装到本地仓库mvn clean install -DskipTests。然后在你自己的测试项目中将MyBatis依赖的scope改为compile并引入其源码模块如果使用IDE可以直接关联源码路径。创建最小化测试案例编写一个最简单的、不依赖Spring的MyBatis程序。包含mybatis-config.xml、一个Mapper接口、一个Mapper.xml、一个POJO和一个包含main方法的测试类。这个案例是你调试的“沙盒”。设置断点从你熟悉的入口开始例如SqlSessionFactoryBuilder.build()DefaultSqlSession.selectOne()MapperProxy.invoke()这是Mapper接口方法调用的入口CachingExecutor.query()如果你配置了缓存调试与观察跟踪配置解析单步跟进XMLConfigBuilder.parse()观察Configuration对象如何被一步步填充。跟踪一次查询从MapperProxy.invoke()开始一步步跟进观察请求如何经过SqlSession-Executor-StatementHandler-ParameterHandler-Database-ResultSetHandler的完整链条。观察动态SQL在DynamicSqlSource.getBoundSql()方法设断点传入不同的参数观察SqlNode树如何被求值最终SQL如何生成。理解插件机制在Plugin.invoke()和你的自定义插件的intercept方法设断点观察代理链的调用顺序。这个过程可能会比较耗时但每理清一个流程你对MyBatis的理解就会加深一层。当你再遇到问题时脑海中就能清晰地浮现出代码执行的路径图排查起来自然得心应手。