1. 为什么MyBatis初始化值得单独拿出来讲

很多做Java后端的兄弟，日常写业务代码时对MyBatis的使用已经滚瓜烂熟——写个Mapper接口，配个XML，Service层注入一下就能跑。但一旦遇到启动报错、Mapper扫描不到、配置不生效这类问题，往往就抓瞎了。我见过太多工作两三年的开发者，面对BindingException: Invalid bound statement这种经典错误时，第一反应是去网上搜，而不是从初始化流程的角度去定位问题。

这个项目标题“MyBatis初始化全流程解析”，说白了就是把MyBatis从零到能用的整个过程拆开揉碎。它解决的核心问题是：让你搞清楚一个Mapper接口到底是怎么变成可执行的SQL调用的。适合谁看？适合那些已经会用MyBatis但想深入理解其内部机制的后端开发者，也适合正在准备面试、需要把框架原理讲清楚的同学。前置知识只需要你用过Spring Boot加MyBatis的常规组合，了解Java反射和动态代理的基本概念就够了。

我个人的经验是，把初始化流程吃透之后，排查MyBatis相关问题的效率至少提升一倍。因为你不再是在黑盒外面猜，而是知道每一步在干什么、哪一步可能出问题。下面我就按照实际源码的执行顺序，把整个初始化链路完整走一遍。

2. 初始化流程的整体设计与核心思路拆解

2.1 从配置文件到SqlSessionFactory的主线逻辑

MyBatis初始化的终极目标只有一个：构建出一个可用的SqlSessionFactory。你可以把SqlSessionFactory理解成一个“SQL会话生产车间”，所有对数据库的操作最终都要通过它创建SqlSession来完成。整个初始化过程，就是围绕如何把这个车间建起来、把里面的设备（配置、映射、插件等）都装配到位。

主线逻辑其实不复杂，用一句话概括：解析配置文件 → 构建Configuration对象 → 用Configuration创建SqlSessionFactory。但魔鬼藏在细节里，这条主线上挂载了大量的分支处理，比如别名注册、类型处理器注册、插件链构建、Mapper映射解析等等。

为什么MyBatis要设计成这样？核心考量是解耦与可扩展。Configuration对象是整个MyBatis运行时的“中央配置仓库”，所有的配置信息、映射信息、插件信息都汇聚到这里。SqlSessionFactory只需要持有这个Configuration，后续创建SqlSession时直接从中读取即可。这种设计让配置解析和运行时使用彻底分离，解析阶段可以专注于把各种来源的配置（XML、注解、API）统一成Configuration，运行阶段则不需要关心配置从哪来。

2.2 两种初始化方式的路径差异

实际项目中，MyBatis的初始化通常有两种路径：

• 传统方式：通过SqlSessionFactoryBuilder读取mybatis-config.xml，手动构建SqlSessionFactory。这种方式在非Spring项目中常见，流程清晰但配置繁琐。
• Spring集成方式：通过SqlSessionFactoryBean配合Spring的容器生命周期完成初始化。这是目前主流做法，也是坑最多的地方，因为多了一层Spring容器的介入。

两者的核心差异在于：传统方式是“我主动调用构建”，Spring集成方式是“Spring容器在启动时触发构建”。后者涉及FactoryBean接口、InitializingBean回调、ApplicationListener事件等一系列Spring机制，理解起来门槛更高，但实际工作中遇到的绝大多数问题都出在这条路径上。

我下面重点以Spring集成方式为主线来拆解，因为这才是大家日常真正在用的。传统方式的流程会在关键节点做对比说明。

2.3 为什么选择这个拆解角度

市面上讲MyBatis初始化的文章不少，但很多要么是直接贴源码逐行念，要么是画个流程图一笔带过。我的拆解角度是以问题为导向：每一步都回答“这一步在干什么、为什么需要这一步、这一步出问题会表现成什么现象”。这样你在读完之后，不仅能理解流程，还能建立起排查问题的直觉。

举个例子，很多人不知道MapperScannerConfigurer和@MapperScan的关系，也不知道为什么有时候Mapper接口明明写了但就是注入不进去。这些问题的答案都藏在初始化流程的某个具体环节里。我会在每个环节都标注出常见的“故障点”，方便你对照排查。

3. 核心组件与关键细节深度解析

3.1 Configuration：整个初始化过程的“中央仓库”

Configuration类是MyBatis初始化的核心载体，你可以把它想象成一个巨大的配置登记簿。在初始化过程中，所有解析出来的信息都会往这个登记簿里写。它内部持有的关键组件包括：

这个类的设计采用了典型的“注册表模式”，每个子注册表负责一类信息的存储和查找。初始化过程本质上就是不断往这些注册表里填充数据的过程。理解这一点很关键，因为当你在排查“某个配置为什么没生效”时，本质上就是在问“这个配置有没有被正确写入对应的注册表”。

注意：Configuration对象在整个应用生命周期内是单例的，一旦初始化完成就不会再变。这意味着如果你在运行时动态修改配置，是不会生效的。这个特性经常被忽略，导致一些开发者试图在运行时改配置却怎么都不起作用。

3.2 XMLConfigBuilder与XMLMapperBuilder的分工

初始化过程中有两个核心的解析器：XMLConfigBuilder负责解析主配置文件，XMLMapperBuilder负责解析Mapper映射文件。它们的分工非常明确：

• XMLConfigBuilder：解析<configuration>下的所有元素，包括<properties>、<settings>、<typeAliases>、<plugins>、<environments>、<mappers>等。它负责搭建Configuration的骨架。
• XMLMapperBuilder：解析单个Mapper XML文件，包括<resultMap>、<sql>、<select>、<insert>等。它负责往骨架里填充具体的SQL映射信息。

两者的协作关系是：XMLConfigBuilder在解析<mappers>元素时，会触发XMLMapperBuilder去解析对应的Mapper文件。这个触发过程是递归的，因为Mapper文件里可能通过<include>引用其他文件，或者通过<package>扫描整个包。

这里有一个容易踩的坑：如果Mapper XML文件的路径配置不对，XMLMapperBuilder根本不会被触发，但也不会报错。结果就是Mapper接口被注册了，但对应的SQL语句没有注册，运行时就会报Invalid bound statement。这个问题的根源就在于初始化流程中XMLMapperBuilder没有被正确调用。

3.3 Mapper接口的注册与代理工厂机制

Mapper接口的注册是初始化流程中最精妙的部分之一。MyBatis并没有为每个Mapper接口生成实现类，而是通过JDK动态代理在运行时生成代理对象。这个机制的初始化过程分为两步：

第一步是注册Mapper接口。在解析<mappers>元素时，MyBatis会把Mapper接口的Class对象和对应的MapperProxyFactory注册到MapperRegistry中。这一步只是登记，还没有创建代理对象。

第二步是创建代理对象。当你通过sqlSession.getMapper(UserMapper.class)获取Mapper时，MapperRegistry会查找对应的MapperProxyFactory，然后通过它创建代理对象。代理对象内部持有SqlSession，所有方法调用都会被拦截并转换为SQL执行。

为什么这么设计？因为Mapper接口的数量可能很多，如果在初始化时就为每个接口创建代理对象，会浪费内存。延迟到实际使用时再创建，既节省资源又灵活。但这也带来一个问题：如果Mapper接口没有被正确注册，getMapper时就会直接抛异常。所以注册这一步是绝对不能出错的。

3.4 插件链的构建时机与顺序问题

插件的初始化发生在Configuration构建的早期阶段。XMLConfigBuilder在解析<plugins>元素时，会通过InterceptorChain.addInterceptor()方法把插件加入拦截器链。这个链是一个ArrayList，插件的执行顺序就是添加顺序。

这里有一个非常重要的细节：插件的顺序会影响最终的执行结果。因为MyBatis的插件是通过动态代理层层包裹的，先添加的插件在最外层，后添加的插件在最内层。执行时，外层插件先拦截，然后调用内层插件，最后才执行真正的目标方法。

我踩过的一个坑是：分页插件和SQL日志插件同时使用时，如果顺序配反了，日志里看到的SQL可能是不带分页的原始SQL，导致排查问题时产生误判。正确的做法是把分页插件放在日志插件的外层，这样日志里能看到最终执行的分页SQL。

提示：在Spring Boot中，如果有多个插件，可以通过@Order注解或者Ordered接口来控制顺序。但要注意，MyBatis本身的InterceptorChain并不感知Spring的Order注解，需要在配置时手动控制添加顺序。

4. 完整初始化流程的实操拆解

4.1 Spring Boot环境下SqlSessionFactory的创建过程

在Spring Boot项目中，MyBatis的初始化入口是MybatisAutoConfiguration这个自动配置类。它会在Spring容器启动时被触发，核心逻辑是创建一个SqlSessionFactoryBean并调用其getObject()方法。

整个流程可以拆解为以下步骤：

1. Spring容器启动，扫描到MybatisAutoConfiguration，触发自动配置。
2. 创建SqlSessionFactoryBean实例，此时会注入数据源、MyBatis配置、插件等依赖。
3. 调用SqlSessionFactoryBean的afterPropertiesSet()方法（因为它实现了InitializingBean接口），开始构建SqlSessionFactory。
4. 构建Configuration对象，这是整个流程的核心步骤。
5. 解析Mapper映射，包括XML文件和注解两种方式。
6. 创建DefaultSqlSessionFactory，持有构建好的Configuration。
7. 将SqlSessionFactory注册到Spring容器，后续Mapper接口的注入都依赖它。

这个过程中，第4步和第5步是最容易出问题的环节。第4步涉及大量配置的解析和注册，任何一处配置错误都可能导致启动失败。第5步涉及Mapper文件的扫描和解析，路径配置、命名规范、XML与接口的对应关系都会影响结果。

4.2 Configuration构建的详细步骤与参数说明

Configuration的构建过程可以细分为以下几个关键步骤，我按照实际执行顺序来梳理：

第一步：加载properties配置。MyBatis会先解析<properties>元素，把键值对加载到Variables中。这些变量可以在后续的配置中用${}引用。在Spring Boot中，通常通过mybatis.configuration-properties来配置。

第二步：加载settings配置。这是最影响运行时行为的配置项集合。几个关键参数需要特别注意：

mapUnderscoreToCamelCase这个参数我强烈建议开启。数据库字段用下划线命名、Java属性用驼峰命名是最常见的组合，开启后就不需要每个字段都写<result>映射了，能省大量配置。

第三步：注册类型别名。解析<typeAliases>元素，把包路径下的类注册为别名。别名默认是类名首字母小写，也可以通过@Alias注解自定义。这一步的坑在于：如果包路径配置错误，不会报错，只是别名注册不上，后续XML中使用别名时会报“找不到别名”的错误。

第四步：注册类型处理器。解析<typeHandlers>元素，注册自定义的类型处理器。MyBatis内置了大量常用的类型处理器，一般不需要自定义。但如果你的项目用了自定义类型（比如枚举、JSON字段），就需要在这里注册。

第五步：构建插件链。解析<plugins>元素，把插件加入InterceptorChain。前面已经讲过顺序问题，这里不再重复。

第六步：构建Environment。解析<environments>元素，创建数据源和事务工厂。在Spring Boot中，数据源通常由Spring管理，MyBatis只是引用它。

第七步：解析Mapper映射。这是最后一步，也是最复杂的一步。根据<mappers>的配置，逐个解析Mapper XML文件或注解。每个Mapper文件都会触发XMLMapperBuilder的解析流程。

4.3 Mapper映射解析的完整链路

Mapper映射解析是初始化流程中最容易出问题的环节，我把它单独拿出来详细拆解。整个链路如下：

1. XMLConfigBuilder解析<mappers>元素，根据配置方式（resource、url、class、package）确定要解析的Mapper。
2. 对于XML方式，调用XMLMapperBuilder.parse()方法，解析Mapper XML文件。
3. XMLMapperBuilder首先解析<cache>元素，如果配置了二级缓存，会创建Cache对象并注册到Configuration中。
4. 然后解析<resultMap>元素，构建ResultMap对象并注册。
5. 接着解析<sql>元素，把SQL片段存入sqlFragments中，供后续<include>引用。
6. 最后解析<select>、<insert>、<update>、<delete>元素，构建MappedStatement并注册到Configuration的mappedStatements中。
7. 对于注解方式，通过MapperAnnotationBuilder解析接口上的@Select、@Insert等注解，构建MappedStatement。
8. 注册Mapper接口，把Mapper接口的Class对象和MapperProxyFactory注册到MapperRegistry中。

这个链路中，第6步和第8步是最关键的。第6步决定了SQL语句能否被执行，第8步决定了Mapper接口能否被注入。两者缺一不可，而且必须对应上。如果XML中namespace写错了，或者Mapper接口的全限定名和XML的namespace不一致，就会导致MappedStatement注册到了错误的位置，运行时找不到。

注意：在Spring Boot中，如果使用@MapperScan注解，它会通过MapperScannerConfigurer扫描指定包下的Mapper接口，并自动注册。但XML文件仍然需要放在正确的位置（默认是和接口同包同名，或者在mybatis.mapper-locations指定的路径下）。如果XML位置不对，接口注册了但SQL没注册，就会出现经典的Invalid bound statement错误。

4.4 实操现场记录：一个典型的初始化日志分析

下面是我在实际项目中抓取的一段MyBatis初始化日志，通过分析这段日志可以直观地看到整个流程的执行顺序：

2024-01-15 10:23:45.123 INFO 12345 --- [main] c.m.c.MybatisAutoConfiguration : MyBatis initialization started 2024-01-15 10:23:45.234 INFO 12345 --- [main] o.m.s.SqlSessionFactoryBean : Property 'configuration' is null, using default 2024-01-15 10:23:45.345 INFO 12345 --- [main] o.m.s.SqlSessionFactoryBean : Loading XML mapper files from classpath*:mapper/**/*.xml 2024-01-15 10:23:45.456 INFO 12345 --- [main] o.m.s.SqlSessionFactoryBean : Parsed mapper file: classpath:mapper/UserMapper.xml 2024-01-15 10:23:45.567 INFO 12345 --- [main] o.m.s.SqlSessionFactoryBean : Parsed mapper file: classpath:mapper/OrderMapper.xml 2024-01-15 10:23:45.678 INFO 12345 --- [main] o.m.s.SqlSessionFactoryBean : SqlSessionFactory created successfully

从日志可以看出，初始化过程分为三个阶段：配置加载、Mapper解析、工厂创建。如果启动失败，日志会停在某个阶段，通过最后一条日志就能定位问题出在哪一步。比如如果停在“Loading XML mapper files”，说明Mapper文件路径配置有问题；如果停在“Parsed mapper file”，说明某个Mapper文件解析失败，需要检查该文件的语法。

我个人的习惯是在开发环境把MyBatis的日志级别调到DEBUG，这样能看到每个MappedStatement的注册过程，排查问题时非常有用。配置方式是在application.yml中添加：

logging: level: org.mybatis: DEBUG com.example.mapper: DEBUG

这样启动时就能看到每个Mapper接口的注册和每个SQL语句的解析过程，任何遗漏都会一目了然。

5. 常见问题与排查技巧实录

5.1 启动阶段高频问题速查表

这张表覆盖了我实际工作中遇到的80%以上的初始化问题。其中Invalid bound statement是最常见的，几乎每个用MyBatis的人都遇到过。这个问题的本质是：Mapper接口被注册了，但对应的MappedStatement没有注册。可能的原因有很多，但排查思路是固定的：先确认XML文件是否被解析，再确认namespace是否匹配，最后确认方法名和id是否一致。

5.2 独家避坑技巧：如何快速定位初始化失败

我总结了一个“三步定位法”，在排查MyBatis初始化问题时非常高效：

第一步：看日志停在哪。启动日志会显示初始化进行到了哪一步，最后一条日志就是问题所在的位置。如果日志级别不够，临时调到DEBUG。

第二步：看Configuration里有什么。如果日志不够明确，可以在SqlSessionFactory创建后加一个断点，查看Configuration对象的内容。重点看mappedStatements的数量和MapperRegistry中注册的接口数量，对比预期值就能发现问题。

第三步：看XML和接口的对应关系。如果前两步都没问题，那就是XML和接口的对应关系出了问题。检查namespace是否等于接口全限定名，检查方法名是否等于SQL的id，检查参数类型和返回类型是否匹配。

这个方法的精髓在于从外到内逐层缩小范围，而不是一上来就翻源码。我见过很多开发者遇到问题直接去读MyBatis源码，结果越读越迷糊。其实大部分问题通过日志和配置检查就能解决，只有极少数深层次的问题才需要读源码。

5.3 一个真实案例：多数据源下的初始化陷阱

之前在一个多数据源项目中，遇到了一个很诡异的问题：主数据源的Mapper正常工作，但从数据源的Mapper总是报Invalid bound statement。排查了很久才发现，问题出在初始化流程上。

这个项目使用了两个SqlSessionFactory，分别对应两个数据源。每个SqlSessionFactory有自己的Configuration和MapperRegistry。问题在于，@MapperScan注解默认只扫描一个包，两个数据源的Mapper接口混在同一个包里，导致部分Mapper被注册到了错误的SqlSessionFactory中。

解决方案是给每个数据源配置独立的@MapperScan，指定不同的包路径：

@Configuration @MapperScan(basePackages = "com.example.mapper.primary", sqlSessionFactoryRef = "primarySqlSessionFactory") public class PrimaryDataSourceConfig { // 主数据源配置 } @Configuration @MapperScan(basePackages = "com.example.mapper.secondary", sqlSessionFactoryRef = "secondarySqlSessionFactory") public class SecondaryDataSourceConfig { // 从数据源配置 }

这个案例的教训是：多数据源场景下，Mapper接口的包路径必须严格隔离。因为每个SqlSessionFactory的初始化是独立的，如果包路径重叠，就会出现Mapper被注册到错误工厂的情况。而且这个问题在启动时不会报错，只有在运行时调用到错误的Mapper时才会暴露，排查起来非常费劲。

提示：多数据源场景下，建议在项目初期就规划好包结构，把不同数据源的Mapper放在不同的包下。如果后期才发现这个问题，重构的成本会很高。

6. 初始化流程中的扩展点与自定义实践

6.1 自定义TypeHandler的注册与生效时机

TypeHandler的注册发生在Configuration构建的早期阶段。如果你有自定义的TypeHandler，需要在这个阶段注册进去，否则后续解析Mapper时找不到对应的处理器。

注册方式有两种：一种是在mybatis-config.xml中配置<typeHandlers>，另一种是在Spring Boot中通过ConfigurationCustomizer接口注册。后者更灵活，推荐使用：

@Bean public ConfigurationCustomizer configurationCustomizer() { return configuration -> { configuration.getTypeHandlerRegistry().register( JsonField.class, new JsonTypeHandler() ); }; }

这里有一个关键细节：TypeHandler的注册必须在Mapper解析之前完成。因为Mapper解析时会根据参数类型和返回类型查找对应的TypeHandler，如果此时还没注册，就会使用默认的处理器，导致类型转换异常。在Spring Boot中，ConfigurationCustomizer的执行时机正好在Mapper解析之前，所以是安全的。

6.2 自定义插件的初始化与顺序控制

插件的初始化同样发生在Configuration构建阶段。在Spring Boot中，可以通过Interceptor接口实现自定义插件，然后注册为Spring Bean，MyBatis会自动把它加入拦截器链。

但这里有一个顺序问题：Spring Bean的加载顺序并不等于插件的添加顺序。MyBatis在构建InterceptorChain时，会按照插件Bean的注入顺序添加。如果顺序不对，可能会影响功能。

控制顺序的方法是实现Ordered接口或使用@Order注解：

@Component @Order(1) public class PaginationInterceptor implements Interceptor { // 分页插件，优先级最高 } @Component @Order(2) public class SqlLogInterceptor implements Interceptor { // SQL日志插件，优先级次之 }

这样分页插件会先被添加，处于拦截器链的外层，日志插件后添加，处于内层。执行时先分页再打日志，日志里能看到分页后的SQL。

6.3 初始化完成后的回调与校验

MyBatis初始化完成后，可以通过SqlSessionFactory获取Configuration对象，做一些自定义的校验。比如检查所有Mapper接口是否都有对应的MappedStatement，或者检查某些关键配置是否生效。

我通常会在项目启动后加一个校验逻辑，遍历所有注册的Mapper接口，确认每个方法都能找到对应的MappedStatement。这样可以在启动阶段就发现配置遗漏，而不是等到运行时才报错：

@Component public class MyBatisStartupValidator implements ApplicationListener<ContextRefreshedEvent> { @Autowired private SqlSessionFactory sqlSessionFactory; @Override public void onApplicationEvent(ContextRefreshedEvent event) { Configuration configuration = sqlSessionFactory.getConfiguration(); Collection<Class<?>> mappers = configuration.getMapperRegistry().getMappers(); for (Class<?> mapper : mappers) { for (Method method : mapper.getMethods()) { String statementId = mapper.getName() + "." + method.getName(); if (!configuration.hasStatement(statementId)) { throw new IllegalStateException("Missing statement: " + statementId); } } } } }

这段代码会在Spring容器启动完成后执行，检查每个Mapper接口的每个方法是否都有对应的MappedStatement。如果有遗漏，直接抛异常阻止启动，避免带着问题上线。这个校验逻辑我强烈建议加上，尤其是大型项目，Mapper数量多，人工检查很容易遗漏。

6.4 初始化性能优化的几个实操建议

当Mapper数量很多时，初始化过程可能会变慢。我做过一个测试，500个Mapper接口加XML文件的项目，初始化时间大约在3-5秒。如果超过10秒，就需要考虑优化了。

优化方向主要有两个：减少XML解析开销和并行化Mapper解析。减少XML解析开销的方法包括：合并小的XML文件、避免使用<include>嵌套过深、减少<resultMap>的复杂度。并行化Mapper解析需要自定义SqlSessionFactoryBean，重写Mapper解析逻辑，用线程池并行解析多个Mapper文件。但这个方法有风险，因为Configuration的注册表不是线程安全的，需要加锁。

我个人的建议是：如果初始化时间在可接受范围内（5秒以内），不要过度优化。因为初始化只发生一次，对运行时性能没有影响。把精力放在运行时优化上，收益更大。

7. 从初始化流程看MyBatis的设计哲学

把整个初始化流程走一遍之后，你会发现MyBatis的设计有几个很鲜明的特点。

第一是“配置即代码”。MyBatis把所有的配置信息都收敛到Configuration对象中，运行时只需要读这个对象。这种设计让配置的解析和使用彻底分离，解析阶段可以很复杂，但运行时很简单。这也是为什么MyBatis的源码读起来，初始化部分比运行时部分复杂得多。

第二是“延迟初始化”。Mapper代理对象不是初始化时创建的，而是使用时才创建。这种设计节省了内存，但也意味着初始化阶段不会暴露所有问题。有些问题只有在运行时才会暴露，比如Mapper接口没有对应的MappedStatement。所以我在前面建议加一个启动校验，就是为了把运行时问题提前到启动阶段暴露。

第三是“扩展点前置”。插件、TypeHandler、别名等扩展点都在初始化阶段注册，运行时不再变化。这种设计保证了运行时的稳定性，但也意味着扩展必须在初始化时完成。如果你在运行时动态添加插件，是不会生效的。

理解这三点，你对MyBatis的很多行为就能想通了。比如为什么修改配置后必须重启应用，为什么插件顺序在启动时就确定了，为什么有些错误在启动时不报运行时才报。这些问题的答案都藏在初始化流程的设计里。

我个人在实际操作中的体会是：把初始化流程当成一个“装配流水线”来理解，每个环节负责装配一个部件，所有部件装配完成后才能出厂。任何一个环节出问题，都会导致最终产品有缺陷。排查问题时，就沿着流水线逐个环节检查，比盲目翻源码高效得多。