1. 项目概述为什么我们要深挖MyBatis的动态代理如果你用过MyBatis肯定写过类似UserMapper userMapper sqlSession.getMapper(UserMapper.class);这样的代码。然后这个userMapper就能直接调用你在接口里定义的selectUserById方法神奇地执行了对应的SQL。表面上看我们调用的是一个接口但背后却执行了数据库操作。这个“魔法”的核心就是JDK动态代理。很多开发者停留在“会用”的层面知道这么写能工作但一旦遇到复杂场景比如插件拦截、多数据源下Mapper的绑定、或者性能调优时就会感到无力。因为你不清楚这个代理对象是怎么被创建出来的它如何找到对应的SQL又是如何把方法调用转化为一次数据库会话的。理解这个原理不仅仅是应付面试更是为了在遇到诸如“为什么我的插件没生效”、“这个方法调用到底走了哪些流程”这类问题时能快速定位而不是盲目地试错。我自己在早期做性能优化时就踩过坑。当时一个查询方法非常慢我一开始拼命优化SQL语句但收效甚微。后来通过Arthas等工具追踪才发现问题不在SQL本身而是在MyBatis的代理调用链中某个自定义插件进行了不必要的重复解析。如果不明白动态代理的机制我可能永远也找不到这个瓶颈点。所以这篇内容的目标不是重复官方文档而是带你从源码的视角像解构一台精密仪器一样把getMapper这个方法从调用开始到最终返回一个可用的代理对象这中间每一步的齿轮是如何咬合的彻底讲明白。我们会聚焦于MyBatis如何利用JDK动态代理将我们的Mapper接口方法调用桥接到背后的SQL执行引擎上这一核心链路。2. 核心脉络一次Mapper方法调用的全景图在深入代码之前我们先建立高层级的认知。整个过程可以简化为一个核心链条接口定义 - 配置解析 - 代理创建 - 方法拦截 - SQL执行接口定义我们定义一个只有方法声明的Java接口例如UserMapper。配置解析MyBatis启动时会解析mybatis-config.xml和所有的Mapper.xml文件或注解将接口方法与SQL语句建立映射关系并把这些信息保存在一个叫做MapperRegistry的核心注册中心里。代理创建当我们调用sqlSession.getMapper(UserMapper.class)时MyBatis会去MapperRegistry查找该接口对应的“工厂”。这个工厂的终极产品就是一个实现了该接口的动态代理对象。方法拦截代理对象的所有方法调用都会被一个特定的InvocationHandler在MyBatis中是MapperProxy拦截。SQL执行在InvocationHandler的invoke方法里MyBatis完成了最关键的转换它将当前调用的方法Method对象和传递的参数转换成一个唯一的标识然后从配置中取出对应的SQL语句、参数映射等信息最终委托给Executor去执行数据库操作并返回结果。理解了这个链条我们再钻进去看每个环节的源码实现就会清晰很多。下面我们就从起点——配置的加载与注册开始。3. 源码深潜第一步Mapper接口的注册与绑定MyBatis的初始化入口通常是SqlSessionFactoryBuilder.build()方法。它会解析配置文件最终构建出Configuration对象。这个Configuration是MyBatis的“大脑”所有配置信息都汇聚于此。其中管理Mapper接口的核心组件就是MapperRegistry。3.1 MapperRegistryMapper接口的户籍管理处MapperRegistry可以看作一个注册表它的核心数据结构是一个Mapprivate final MapClass?, MapperProxyFactory? knownMappers new HashMap();键Key是我们定义的Mapper接口的Class对象值Value是一个MapperProxyFactory对象。这个工厂就是专门生产该接口动态代理对象的。那么接口是如何被注册进去的呢主要有两种方式1. XML配置扫描 (mappers标签) 在配置文件中通过mappersmapper resource...//mappers或package name.../声明后MyBatis会使用XMLMapperBuilder来解析对应的XML文件。解析到最后会调用MapperRegistry.addMapper()方法。2. 注解接口扫描 如果你使用纯注解方式或Spring Boot自动配置MyBatis会通过ClassPathMapperScanner在MyBatis-Spring中或类似的机制扫描指定包下的接口。对于扫描到的每一个接口同样会调用MapperRegistry.addMapper()。3.2 addMapper()注册的核心逻辑让我们看看MapperRegistry.addMapper(ClassT type)方法做了什么代码经过简化突出主干public T void addMapper(ClassT type) { // 1. 检查必须是接口 if (!type.isInterface()) { throw new BindingException(Type type is not an interface); } // 2. 检查是否已注册 if (hasMapper(type)) { throw new BindingException(Type type is already known to the MapperRegistry.); } boolean loadCompleted false; try { // 3. 将接口Class和对应的MapperProxyFactory放入knownMappers knownMappers.put(type, new MapperProxyFactory(type)); // 4. 关键步骤解析接口无论是通过关联的XML还是注解 MapperAnnotationBuilder parser new MapperAnnotationBuilder(config, type); parser.parse(); loadCompleted true; } finally { if (!loadCompleted) { knownMappers.remove(type); // 解析失败则移除 } } }关键点解析第3步它创建了一个MapperProxyFactoryT实例并以接口Class为键存入Map。注意此时工厂是“空”的它只知道要代理哪个接口但还不知道接口里每个方法对应什么SQL。第4步parser.parse()是重头戏。MapperAnnotationBuilder会去解析这个接口如果存在同名的XML映射文件如UserMapper.xml它会解析其中的select,insert等标签。同时它也会解析接口方法上的Select,Insert等注解。解析的结果是为每一个方法生成一个MappedStatement对象。这个对象包含了该方法的全部执行信息SQL语句、参数类型、返回类型、语句类型SELECT/UPDATE等、缓存配置等。这个MappedStatement会被存入Configuration的另一个Map中其ID通常是“接口全限定名.方法名”例如com.example.mapper.UserMapper.selectUserById。至此注册完成。Configuration里现在有了两套关键信息一是MapperRegistry知道UserMapper.class对应哪个工厂二是有一堆MappedStatement每个都通过唯一ID关联到了一个具体的方法上。实操心得这里常遇到的一个坑是“绑定异常”BindingException。比如提示“Invalid bound statement (not found)”。十有八九就是这一步出了问题要么是XML文件没被扫描到路径错误、资源过滤问题要么是接口方法和XML/注解中的SQL语句ID对不上。理解了这个注册过程你就能迅速定位是工厂没注册进去还是MappedStatement没创建成功。4. 源码深潜第二步动态代理对象的诞生——getMapper()注册完成后我们就可以在运行时获取Mapper的代理实例了。入口就是SqlSession.getMapper()。4.1 调用链追踪通常的调用路径是DefaultSqlSession.getMapper()-Configuration.getMapper()-MapperRegistry.getMapper()。我们直接看最核心的MapperRegistry.getMapper()public T T getMapper(ClassT type, SqlSession sqlSession) { // 1. 从注册表里获取该接口对应的代理工厂 final MapperProxyFactoryT mapperProxyFactory (MapperProxyFactoryT) knownMappers.get(type); if (mapperProxyFactory null) { throw new BindingException(Type type is not known to the MapperRegistry.); } try { // 2. 使用工厂创建代理实例 return mapperProxyFactory.newInstance(sqlSession); } catch (Exception e) { throw new BindingException(Error getting mapper instance. Cause: e, e); } }逻辑很清晰先查工厂再用工厂创建。核心在于MapperProxyFactory.newInstance()。4.2 MapperProxyFactory代理对象的制造车间MapperProxyFactory的代码非常精炼public class MapperProxyFactoryT { private final ClassT mapperInterface; // ... 可能有方法缓存等字段 protected T newInstance(MapperProxyT mapperProxy) { // 使用JDK动态代理创建实例 return (T) Proxy.newProxyInstance(mapperInterface.getClassLoader(), new Class[] { mapperInterface }, mapperProxy); } public T newInstance(SqlSession sqlSession) { // 1. 创建InvocationHandlerMapperProxy final MapperProxyT mapperProxy new MapperProxy(sqlSession, mapperInterface, methodCache); // 2. 调用重载方法创建代理 return newInstance(mapperProxy); } }这就是动态代理创建的核心new MapperProxy(...)创建了一个MapperProxy实例。它就是JDK动态代理中关键的InvocationHandler调用处理器。它持有了当前SqlSession、Mapper接口的Class对象以及一个可选的methodCache用于缓存方法信息提升性能。Proxy.newProxyInstance(...)这是JDK标准库的方法。它接收三个参数ClassLoader通常使用接口自身的类加载器。Class?[] interfaces要代理的接口列表这里就是我们的UserMapper.class。InvocationHandler就是我们上一步创建的MapperProxy实例。这个方法会返回一个实现了指定接口的代理对象。当我们调用代理对象的任何方法时都会转而调用其InvocationHandler即MapperProxy的invoke方法。注意事项这里解释了为什么MyBatis的Mapper必须是接口。因为JDK动态代理的机制就是基于接口的。它无法为没有实现接口的普通类创建代理。这也是MyBatis和一些其他ORM框架如Hibernate在设计上的一个区别。5. 源码深潜第三步魔法发生的地方——MapperProxy的invoke()现在我们拿到了代理对象userMapper。当我们调用userMapper.selectUserById(1)时程序并不会去执行某个具体的实现类而是进入了MapperProxy.invoke()方法。这是整个动态代理原理中最精妙的部分。5.1 invoke方法的主干逻辑MapperProxy实现了InvocationHandler接口它的invoke方法大致流程如下简化版public Object invoke(Object proxy, Method method, Object[] args) throws Throwable { try { // 1. 如果是Object类自带的方法如toString, hashCode等直接调用不走代理逻辑 if (Object.class.equals(method.getDeclaringClass())) { return method.invoke(this, args); } // 2. 判断是否为接口的默认方法Java 8 if (method.isDefault()) { return invokeDefaultMethod(proxy, method, args); } } catch (Throwable t) { throw ExceptionUtil.unwrapThrowable(t); } // 3. 核心获取MapperMethod并执行 final MapperMethod mapperMethod cachedMapperMethod(method); return mapperMethod.execute(sqlSession, args); }流程解析过滤Object方法代理对象本身也是一个Object像toString()、equals()这些方法应该正常执行不需要被MyBatis的SQL逻辑拦截。处理默认方法从Java 8开始接口可以有default方法。对于这些方法MyBatis有特殊的处理逻辑invokeDefaultMethod让其能正常执行。核心转换与执行对于我们的业务方法如selectUserById会进入最后一步。这里先通过cachedMapperMethod获取或创建一个MapperMethod对象然后调用其execute方法。cachedMapperMethod是一个简单的缓存优化避免每次调用都重新创建MapperMethod对象。它的核心是调用new MapperMethod(mapperInterface, method, sqlSession.getConfiguration())。5.2 MapperMethod方法调用的指挥官MapperMethod是一个将Java方法调用转化为MyBatis内部命令的关键对象。它在构造时会做两件至关重要的事情创建SqlCommand根据方法名和接口类型从Configuration中查找对应的MappedStatement。这个MappedStatement的ID就是我们之前提到的“接口全限定名.方法名”。SqlCommand主要保存了SQL语句的类型SELECT, INSERT等和MappedStatement的ID。创建MethodSignature解析方法的参数列表、返回类型等信息。它处理了诸如Param注解、多个参数、集合返回值、Map返回值等复杂情况。有了这两个信息MapperMethod.execute()方法就知道“要执行什么命令”以及“如何解析参数和返回值”。5.3 execute方法路由到具体的SQL操作MapperMethod.execute()方法是一个大型的switch-case语句根据SqlCommand的类型SELECT, INSERT, UPDATE, DELETE等和MethodSignature的返回类型路由到SqlSession的不同方法上。例如对于我们的User selectUserById(Integer id)方法它是一个SELECT语句。返回类型是单个对象 (User)而不是集合或游标。那么execute方法最终会调用sqlSession.selectOne(...)。selectOne方法内部会根据MappedStatement的ID找到完整的SQL信息然后通过Executor执行器去完成参数绑定、SQL执行、结果集映射等一系列复杂操作最终将数据库返回的ResultSet映射成一个User对象并返回。至此一个完整的从接口方法调用到SQL执行的闭环就完成了。常见问题排查技巧当你发现调用Mapper方法返回null但数据库明明有数据时可以沿着这条链路排查MapperMethod层面检查execute方法路由是否正确是不是误走到了selectOne但实际是多个结果会抛异常。或者走到了selectList但返回类型是单个对象可能返回List的第一个元素或null。SqlSession/Executor层面检查SQL是否真的执行了可以通过开启MyBatis日志或使用mybatis-log-free这类插件查看。参数是否绑定正确MappedStatement层面最根本的检查MappedStatement是否正确创建对应的SQL在XML或注解中是否存在且语法正确结果映射 (resultMap或resultType) 是否正确配置这是最常见的问题根源。6. 动态代理机制带来的扩展性与插件原理理解了核心代理链路我们就能明白MyBatis插件Interceptor是如何工作的。插件本质上就是利用JDK动态代理或CGLib在MyBatis的核心组件如Executor、StatementHandler、ParameterHandler、ResultSetHandler外面再包一层代理。6.1 插件拦截点的位置以Executor为例。在Configuration创建Executor实例的时候会调用interceptorChain.pluginAll(executor)。这个方法会遍历所有已配置的插件让每个插件都有机会使用Plugin.wrap(target, interceptor)方法来对目标对象Executor进行包装。Plugin类本身也实现了InvocationHandler。它的wrap方法会检查插件的Intercepts注解如果该插件声明要拦截当前目标对象的方法那么就使用Proxy.newProxyInstance为目标对象创建一个代理。这个代理的InvocationHandler就是Plugin实例。6.2 多层代理的调用链于是调用链变成了MapperProxy.invoke()-MapperMethod.execute()-SqlSession.selectOne()-代理后的Executor.query()-Plugin.invoke()- 执行插件的intercept()方法 -原始Executor.query()- ...可以看到MyBatis自身的Mapper动态代理和其插件的动态代理是两层独立的代理机制。它们协同工作提供了强大的扩展能力。明白这一点对于编写高效、正确的插件至关重要。比如你的插件在intercept方法里需要调用invocation.proceed()来继续执行链这其实就是调用了被代理的原始对象的方法。实操心得插件开发注意事项签名一定要匹配Signature注解里的type类、method方法名、args参数类型必须精确匹配你要拦截的方法否则Plugin.wrap()时会跳过导致插件不生效。理解代理链你的插件只是代理链中的一环。在intercept方法里你可以修改传递给下游的参数也可以修改下游返回的结果。但务必谨慎避免破坏原有的逻辑。性能影响每加一层代理就多一次方法调用和反射开销。虽然单次开销很小但在超高性能要求的场景下需要评估插件带来的影响。7. 从原理到实践解决典型场景问题掌握了源码原理我们就能游刃有余地解决一些实际问题。场景一如何像Arthas那样在运行时查看MyBatis生成的SQLArthas的watch或trace命令能抓到SQL是因为它们通过字节码增强技术在PreparedStatement执行前后植入了监听代码。从原理上讲SQL的最终组装是在StatementHandler特别是PreparedStatementHandler的parameterize和query方法中完成的。一个更简单的方式是使用MyBatis内置的日志功能配置logImpl为STDOUT_LOGGING或集成SLF4JLogback它会将Executor执行过程中的SQL语句和参数打印出来。理解了代理链你就知道这些日志是在Executor被插件代理之前还是之后打印的有助于分析问题。场景二MyBatis-Plus等增强工具是如何工作的MyBatis-PlusMP在保持与MyBatis兼容的同时提供了更多功能。它核心也是基于MyBatis的扩展点。例如自己的MapperProxyMP可能会继承或重新实现MapperProxy在invoke方法中先判断当前调用的方法是否是MP提供的通用方法如selectById,update如果是则走MP自己的逻辑自动组装SQL如果不是则调用父类原生MyBatis的逻辑。这解释了为什么我们用MP的BaseMapper既能调用selectById也能调用自定义的selectUserByName。自己的SqlSession或ConfigurationMP可以通过自定义的SqlSessionFactoryBean在Spring中注入自己增强后的组件。场景三多数据源下Mapper如何正确绑定到不同的SqlSession在动态数据源或读写分离场景中不同的Mapper可能需要不同的SqlSession背后连接不同的数据库。从getMapper的源码我们知道创建代理时传入的sqlSession参数至关重要。在Spring管理下通常每个数据源会对应一个SqlSessionTemplate它实现了SqlSession。Spring的MapperFactoryBean在创建Mapper代理时会注入与之关联的SqlSessionTemplate。因此实现多数据源路由的关键就在于如何让不同的Mapper接口在创建代理时拿到正确的SqlSessionTemplate。这通常通过自定义AbstractRoutingDataSource和扫描路径的巧妙划分来实现。8. 总结与进阶思考通过这次从源码角度的梳理我们可以清晰地看到MyBatis的动态代理开发原理并不神秘它是一套非常经典且优雅的接口绑定与命令模式的应用。启动时注册将Mapper接口与对应的MapperProxyFactory工厂注册到MapperRegistry并解析所有方法生成MappedStatement。运行时代理通过getMapper从工厂获取代理对象工厂使用JDK动态代理创建并绑定MapperProxy作为处理器。调用时转换代理对象的方法调用被MapperProxy拦截它委托给MapperMethod后者根据方法签名和SQL命令类型调用SqlSession的对应方法完成数据库操作。可扩展的架构基于动态代理和拦截器链MyBatis的核心组件可以被插件层层包装提供了极大的灵活性。理解了这个原理你就能精准调试在遇到BindingException、插件不生效、结果映射错误时能快速定位问题层级。深度定制有信心去编写自己的插件或者理解MyBatis-Plus这类第三方工具的工作原理。性能优化知道哪些环节可能有缓存如MapperMethod缓存哪些环节是性能热点如反射调用从而有针对性地进行优化。最后我个人的一个体会是阅读源码不要一开始就陷入每一行代码的细节。像我们今天这样先抓住“动态代理”这个主线理清从getMapper到invoke的核心脉络建立起骨架。然后再根据实际需要去深入血肉比如Executor的执行过程、StatementHandler的参数处理、ResultSetHandler的结果映射等。这样分层分模块地理解效率会高很多也更容易建立起对框架整体的掌控感。