Mybatis-plus源码解读-自动装配与加载流程

原创已于 2025-08-21 16:05:44 修改 · 1.6k 阅读

28 ·

CC 4.0 BY-SA版权

文章标签：

#mybatis #mybatis-plus #自动装配与加载 #Sql注入器原理解析 #BaseMapper加载流程

于 2025-08-21 09:38:11 首次发布

Mybatis 源码解读专栏收录该内容

10 篇文章

订阅专栏

技术栈深潜计划：原理解析&编程技巧深度探索征文活动 10w+人浏览 85人参与

作者源码阅读笔记主要采用金山云文档记录的，所有的交互图和代码阅读笔记都是记录在云文档里面，本平台的文档编辑实在不方便，会导致我梳理的交互图和文档失去原来的格式，所以整理在文档里面，供大家阅读交流

【金山文档 | WPS云文档】 Mybatis-plus 自动装配与加载流程

相关重要类介绍说明

MybatisPlusAutoConfiguration 自动装配类

MyBatis-Plus 的 MybatisPlusAutoConfiguration 是 Spring Boot 自动配置的核心类，负责集成 MyBatis-Plus 的核心功能到 Spring Boot 项目中

核心作用

自动装配基础组件

自动创建 SqlSessionFactory（通过 MybatisSqlSessionFactoryBean 实现），并注入 MyBatis-Plus 的全局配置（如分页插件、性能分析插件）
注册 MapperScannerConfigurer，扫描指定包路径下的 Mapper 接口，支持 @MapperScan 注解的显式配置或默认路径扫描

‌条件化加载

通过 @ConditionalOnClass 和 @ConditionalOnSingleCandidate 注解确保仅在类路径存在 SqlSessionFactory 且数据源唯一时激活配置

名称	描述	默认值
properties	MyBatis-Plus 的 `MybatisPlusAutoConfiguration` 类通过 `MybatisPlusProperties` 绑定配置文件属性内联配置（如 `application.yml`）优先级高于 `mybatis-config.xml` 若同时配置 `mapperLocations` 和 `@MapperScan`，两者会合并扫描
interceptors	用于管理和加载 MyBatis-Plus 内置插件的核心配置项通过 `MybatisPlusInterceptor` 代理类统一管理，拦截 SQL 执行生命周期（如 `Executor#query、StatementHandler#prepare`）在 Spring Boot 启动时，`MybatisPlusAutoConfiguration` 自动从容器中收集所有 `InnerInterceptor` 类型的 Bean，注入到 `MybatisPlusInterceptor` 的 `interceptors` 集合中
typeHandlers	用于管理类型处理器（`TypeHandler`），负责 Java 类型与数据库类型的自动转换
languageDrivers	用于管理 MyBatis 的 ‌SQL 方言驱动‌（`LanguageDriver`），它决定了 MyBatis 如何解析和构建动态 SQL 语句
resourceLoader	`resourceLoader` 字段是 Spring 框架提供的资源加载器（`ResourceLoader`），主要用于处理 MyBatis 相关资源的加载与路径解析
databaseIdProvider	`databaseIdProvider` 字段用于支持多数据库厂商的 SQL 方言适配。过识别数据库厂商名称（如 `mysql`、`oracle`）动态匹配对应的 SQL 语句。与 MyBatis 原生机制兼容，支持在 Mapper XML 中通过 `databaseId` 属性标记不同数据库的 SQL 语句
configurationCustomizers	用于对 MyBatis 原生配置（`Configuration`）进行深度定制 `configurationCustomizers` 是 `List<ConfigurationCustomizer>` 集合，通过回调接口 `ConfigurationCustomizer` 允许开发者在 MyBatis `Configuration` 初始化后注入自定义逻辑典型场景：动态修改缓存策略、添加插件、覆盖默认类型处理器等在 `SqlSessionFactory` 构建过程中，`MybatisPlusAutoConfiguration` 会遍历所有注册的 `ConfigurationCustomizer`，依次调用其 `customize()` 方法，传入原生 `Configuration` 对象
sqlSessionFactoryBeanCustomizers	用于深度定制 `SqlSessionFactoryBean` 的扩展点典型场景：动态修改数据源、添加自定义 VFS 实现、覆盖 MyBatis 原生配置等在 `SqlSessionFactory` 构建前，`MybatisPlusAutoConfiguration` 会遍历所有注册的 `SqlSessionFactoryBeanCustomizer`，依次调用其 `customize()` 方法，传入 `MybatisSqlSessionFactoryBean` 实例
mybatisPlusPropertiesCustomizers	用于动态定制 `MybatisPlusProperties` 配置的扩展点典型场景：覆盖 `application.yml` 中的默认配置（如 `map-underscore-to-camel-case`）、动态调整全局策略（如主键生成器）等在 `MybatisPlusAutoConfiguration` 初始化阶段（`afterPropertiesSet` 方法），会遍历所有注册的定制器，对 `MybatisPlusProperties` 进行二次加工
applicationContext	`applicationContext` 字段是 Spring 应用上下文的核心引用注意事项 ‌执行顺序依赖 ‌需确保 `applicationContext` 注入早于 `SqlSessionFactory` 的构建，否则扩展组件可能无法生效 ‌循环引用风险 ‌避免在自定义组件中直接通过 `applicationContext` 获取 `SqlSessionFactory`，可能导致 Spring 容器初始化死锁 ‌与原生 MyBatis 协同 ‌若同时使用 `mybatis-config.xml`，需注意配置优先级（`applicationContext` 的配置会覆盖 XML 中的同名项）

‌MybatisSqlSessionFactoryBean类

MybatisSqlSessionFactoryBean 是 MyBatis-Plus 提供的核心工厂类，用于替代 MyBatis 原生的 SqlSessionFactoryBean，专为简化 MyBatis-Plus 特性集成而设计

核心作用

自动增强 Mapper 接口

继承 BaseMapper 的接口无需手动编写 SQL，自动生成 CRUD 方法实现（如 selectById、insert）
支持逻辑删除、乐观锁等注解驱动的功能扩展

全局配置集成

通过 globalConfig 属性注入 MyBatis-Plus 的全局策略（如主键生成规则、字段自动填充处理器）

‌简化 XML 配置

自动扫描 mapperLocations 路径下的 XML 文件，并与 Mapper 接口动态绑定

‌实现机制

‌继承与扩展

继承 MyBatis 原生的 SqlSessionFactoryBean，重写 buildSqlSessionFactory() 方法，在初始化阶段注入 MyBatis-Plus 特有配置
示例：自动加载分页插件（PaginationInnerInterceptor）

‌与 Spring 整合

作为 FactoryBean 实现类，通过 Spring 容器管理 SqlSessionFactory 生命周期，直接依赖 Spring 的 DataSource

‌多数据源场景

需为每个数据源单独创建 MybatisSqlSessionFactoryBean 实例

名称	描述	默认值
RESOURCE_PATTERN_RESOLVER	主要用于解析和加载 MyBatis 的映射文件（Mapper XML）资源是 `ResourcePatternResolver` 类型，由 Spring 提供，用于支持 Ant 风格路径匹配（如 `classpath:mapper//.xml`）的资源扫描核心作用：动态加载类路径下的 Mapper XML 文件，并将其绑定到对应的 Mapper 接口
METADATA_READER_FACTORY	主要用于支持注解驱动的 Mapper 接口扫描和元数据解析 `METADATA_READER_FACTORY` 是 `MetadataReaderFactory` 类型，默认初始化为 `CachingMetadataReaderFactory` 实例核心作用‌：解析类路径下的 Mapper 接口或实体类的元数据（如注解信息、类名等），支持动态加载和缓存优化为 MyBatis-Plus 的注解扫描（如 `@MapperScan`）提供底层支持，避免重复解析类元数据，提升启动性能
configLocation	`configLocation` 是 `MybatisSqlSessionFactoryBean` 中用于指定 MyBatis 原生配置文件路径的关键属性核心功能 ‌加载原生 MyBatis 配置通过 `configLocation` 可指定 MyBatis 的全局配置文件（如 `mybatis-config.xml`） ‌与 Spring 配置的协作关系数据源与事务管理由 Spring 控制‌：`configLocation` 中配置的 `environments` 或 `dataSource` 会被忽略，实际数据源以 `SqlSessionFactoryBean` 注入的 Spring 数据源为准 ‌‌配置合并优先级‌：Spring 通过属性（如 `typeAliasesPackage`）设置的配置会覆盖 `configLocation` 中同名项
configuration	用于直接注入 MyBatis 核心配置对象（`org.apache.ibatis.session.Configuration`）的关键属性与 `configLocation` 互斥：`configuration` 和 `configLocation` 不能同时设置，两者优先级相同，若同时存在会抛出异常
mapperLocations	`mapperLocations` 是 `MyBatisSqlSessionFactoryBean` 中用于指定 ‌MyBatis SQL 映射文件（Mapper XML）位置‌的关键属性。 `mapperLocations` 确保接口对应的 XML 被加载核心作用加载 SQL 映射文件指定 XML 文件路径，MyBatis 解析这些文件后将 SQL 语句与 Mapper 接口方法绑定，实现 SQL 执行逻辑 ‌动态 SQL 支持支持在 XML 中编写动态 SQL（如 `<if>`、`<foreach>` 等标签），提升 SQL 灵活性 ‌
dataSource	数据库连接源
transactionFactory	`transactionFactory` 是 `MybatisSqlSessionFactoryBean` 中用于自定义事务管理策略的重要字段与 Spring 事务的协作机制 PlatformTransactionManager：Spring 事务管理器，通过 `transactionFactory` 桥接 MyBatis 操作；（声明式事务（`@Transactional`）） DataSourceTransactionManager：基于数据源的事务管理，需与 `SpringManagedTransactionFactory` 配合；（JDBC 本地事务） JtaTransactionManager：分布式事务支持，需自定义 `transactionFactory` 实现；（XA 分布式事务）
configurationProperties	用于‌动态配置 MyBatis 全局参数‌的重要字段
sqlSessionFactoryBuilder	默认MybatisSqlSessionFactoryBuilder 关键设计原则：‌Builder模式实现配置与构建的解耦‌，允许灵活扩展配置加载方式
sqlSessionFactory	负责生成 MyBatis 的核心操作入口生成的 `SqlSessionFactory` 是线程安全的单例对象（final修饰），应用生命周期内只需创建一次初始化触发时机：Spring 容器启动时通过 `afterPropertiesSet()` 方法自动完成构建，包含以下步骤：合并 XML 与 Java 配置注册类型处理器/别名解析映射文件与接口
environment	用于‌指定 MyBatis 运行环境‌的关键配置字段通过该字段可配置多套数据库环境（如开发/测试/生产环境），每个环境包含独立的数据源和事务管理器最终生成的 `SqlSessionFactory` 仅使用其中一个环境配置，默认加载 `environments` 标签的 `default` 属性指定环境
failFast	用于‌强制验证配置完整性‌的关键字段	当 `failFast=true`（默认值）时，在应用启动阶段会‌立即验证所有配置项‌（如映射文件、别名配置等）的合法性。若发现错误（如 XML 语法错误或资源路径无效），将直接抛出异常终止启动
plugins	用于‌扩展 MyBatis 核心功能‌的关键配置字段基础功能定位 ‌拦截器机制该字段接收 `Interceptor[]` 数组，允许通过动态代理拦截 MyBatis 四大核心组件的方法调用 `Executor`（SQL执行器） `StatementHandler`（SQL语法构建器） `ParameterHandler`（参数处理器） `ResultSetHandler`（结果集处理器） ‌典型应用场景实现分页、SQL监控、字段加密、乐观锁等通用功能增强‌
typeHandlers	用于‌处理 Java 类型与 JDBC 类型转换‌的核心配置字段
typeHandlersPackage	是 MyBatis-Spring 集成中用于‌批量注册自定义类型处理器‌的核心配置属性
defaultEnumTypeHandler	用于‌统一配置枚举类型默认处理器‌的重要字段
typeAliases	用于‌简化 Java 类型全限定名‌的核心配置字段
typeAliasesPackage	是 MyBatis 与 Spring 整合时用于‌批量配置类型别名‌的核心属性
typeAliasesSuperType	用于‌限定类型别名扫描范围‌的重要配置属性
scriptingLanguageDrivers	用于‌配置脚本语言驱动‌的重要属性
defaultScriptingLanguageDriver	是 MyBatis 与 Spring 整合时用于‌指定默认脚本语言驱动‌的关键配置属性
databaseIdProvider	是 MyBatis 与 Spring 整合时用于‌支持多数据库厂商兼容‌的核心配置属性
vfs	配置虚拟文件系统(Virtual File System)‌的重要属性
cache	用于‌配置 MyBatis 缓存行为‌的核心属性
objectFactory	用于‌自定义 MyBatis 对象实例化过程‌的重要配置属性
objectWrapperFactory	用于‌自定义对象包装行为‌的重要配置属性
applicationContext	用于‌与 Spring 应用上下文集成‌的重要属性
globalConfig	用于‌配置 MyBatis-Plus 全局行为‌的核心属性

MybatisSqlSessionFactoryBuilder 扩展类

MyBatis-Plus 的 MybatisSqlSessionFactoryBuilder 是 MyBatis 原生SqlSessionFactoryBuilder 的扩展类，主要用于构建支持 MyBatis-Plus 特性的 SqlSessionFactory 实例。

核心作用

增强的工厂构建器

继承自 MyBatis 原生的 SqlSessionFactoryBuilder，在构建 SqlSessionFactory 时注入 MyBatis-Plus 的全局配置（如分页插件、性能分析插件等）
通过 MybatisSqlSessionFactoryBean 间接调用，实现与 Spring 的无缝集成

‌与 MyBatis-Plus 的协作‌

在 MybatisPlusAutoConfiguration 中初始化，通过 build() 方法生成包含 MP 特性的 SqlSessionFactory
支持自动加载 MyBatis-Plus 的 XMLMapperBuilder，解析自定义注解（如 @TableName）

MybatisXMLMapperBuilder 类

MybatisXMLMapperBuilder 是 MyBatis-Plus 框架中用于解析 Mapper XML 文件的核心组件，它在原生 MyBatis 的 XMLMapperBuilder 基础上进行了功能增强

核心作用

‌XML 映射文件解析

负责将 Mapper XML 文件中的 SQL 语句、参数映射、结果映射等配置转换为 MyBatis 内部对象结构

‌动态 SQL 支持

增强了对 MyBatis-Plus 特有动态 SQL 语法的解析能力‌

‌注解集成

支持解析 MyBatis-Plus 特有的注解配置（如 @TableField 等）

‌‌解析流程

1. 解析 namespace → 2. 处理缓存配置 → 3. 解析 resultMap → 
4. 解析 SQL 片段 → 5. 增强解析 CRUD 节点

MybatisConfiguration 类

MybatisConfiguration 是 MyBatis-Plus 对原生 MyBatis Configuration 类的扩展实现

核心作用

全局配置容器

继承自 MyBatis 原生 Configuration 类，作为 MyBatis-Plus 增强功能的配置中心

‌功能扩展入口

通过重写父类方法实现 MyBatis-Plus 特有功能（如逻辑删除、自动填充等）的集成‌

名称	描述	默认值
mybatisMapperRegistry	该字段在 MybatisConfiguration 中替换了原生 Configuration 的 MapperRegistry‌
caches	核心功能管理 Mapper 级别的二级缓存实例支持通过缓存装饰器实现缓存功能扩展与 MyBatis-Plus 的缓存增强机制集成与原生实现的差异增强缓存配置在 MyBatis-Plus 中可以通过 `mybatis-plus.configuration.cache-enabled` 配置全局开启/关闭二级缓存 ‌Redis 集成支持 MyBatis-Plus 提供了与 Redis 集成的缓存实现，可通过配置替换默认的 PerpetualCache ‌‌多租户缓存隔离 ‌在 MyBatis-Plus 的多租户场景下，会对缓存 key 进行特殊处理实现租户隔离
resultMaps	用于管理结果映射
parameterMaps	用于管理参数映射
keyGenerators	用于管理主键生成策略
sqlFragments	sqlFragments 字段是用于管理 SQL 片段
mappedStatements	核心功能管理 Mapper 接口方法与 SQL 语句的映射关系缓存已解析的 SQL 语句和执行计划作为 MyBatis 执行 SQL 操作的核心入口点与原生实现的差异增强的 CRUD 操作 MyBatis-Plus 会自动注入基础的 CRUD 操作对应的 MappedStatement，减少手动配置 ‌Lambda 支持通过 Lambda 表达式生成的查询条件会转换为标准的 MappedStatement‌ ‌性能优化对大量 MappedStatement 的内存占用进行了优化处理‌

MybatisMapperRegistry mapper注册器

MybatisMapperRegistry 是 MyBatis-Plus 扩展自 MyBatis 原生 MapperRegistry 的核心组件，负责管理 Mapper 接口与代理工厂的注册和绑定关系

‌核心作用

负责注册和管理所有 Mapper 接口的动态代理实现
支持 MyBatis-Plus 特有的 SQL 方法注入机制
实现 BaseMapper 通用方法的动态注册

与原生实现的差异

增强注册逻辑

重写了 addMapper 方法，在注册时会自动注入 MyBatis-Plus 的通用 CRUD 方法

‌SQL 注入器集成

通过该字段与 SqlInjector 配合实现动态 SQL 方法注入

‌‌扩展点支持‌

支持通过 GlobalConfig 配置自定义的 Mapper 注册逻辑

工作流程

初始化阶段

MybatisConfiguration 构造时会创建 MybatisMapperRegistry 实例

‌Mapper 注册过程

1. 解析 Mapper 接口方法
2. 注入 BaseMapper 通用方法
3. 处理自定义 SQL 注入器方法
4. 生成 MapperProxy 动态代理

执行阶段

通过 MapperProxy 调用具体方法时，会委托给注册器中对应的 MappedStatement

名称	描述	默认值
config	存储了对 MyBatis 核心配置对象的引用
knownMappers	knownMappers 是 MyBatis-Plus 核心组件 MybatisMapperRegistry 中的关键数据结构，负责管理 Mapper 接口与代理工厂的映射关系

MybatisMapperAnnotationBuilder 类

MybatisMapperAnnotationBuilder 是 MyBatis-Plus 扩展自 MyBatis 原生 MapperAnnotationBuilder 的核心组件，负责解析 Mapper 接口上的注解并构建对应的 SQL 映射

核心作用

注解解析增强

支持 @TableName、@TableField 等 MyBatis-Plus 特有注解

‌SQL 注入扩展

自动注入 BaseMapper 中的通用 CRUD 方法

‌‌与 MybatisMapperRegistry 协同

作为 MybatisMapperRegistry 的解析器，完成 Mapper 接口的最终注册

Lambda 表达式支持

为方法生成支持 Lambda 表达式的 SQL 构建逻辑

工作流程

初始化阶段

MybatisMapperRegistry 创建 MybatisMapperAnnotationBuilder 实例并传入配置和 Mapper 接口类

‌解析过程

1. 解析接口上的类级别注解
2. 逐个解析接口方法
3. 构建对应的 MappedStatement
4. 注册到 Configuration 中

SQL 注入

在解析过程中会自动注入 BaseMapper 的通用方法实现

与原生实现的差异

‌方法注入机制

原生仅解析已有方法，MyBatis-Plus 会额外注入通用方法

‌SQL 优先级调整

采用 "XmlSql > sqlProvider > CurdSql" 的加载顺序

‌‌扩展点丰富

提供更多可扩展的解析钩子和回调接口

ISqlInjector sql注入器

ISqlInjector 是 MyBatis-Plus 中用于 SQL 方法注入的核心接口，负责将自定义的 SQL 方法注入到 Mapper 接口中。

ISqlInjector 是 MyBatis-Plus 实现自动化 CRUD 和自定义方法扩展的核心机制，通过它可以灵活地扩展 Mapper 接口的功能

‌核心功能

ISqlInjector 是 MyBatis-Plus 实现"只做增强不做改变"理念的关键组件，负责将 BaseMapper 中的通用 CRUD 方法以及自定义方法注入到 Mapper 接口中

核心方法

public interface ISqlInjector {
    void inspectInject(MapperBuilderAssistant builderAssistant, Class<?> mapperClass);
}

该方法接收两个参数：

MapperBuilderAssistant：MyBatis 的 Mapper 构建助手
mapperClass：当前要处理的 Mapper 接口类

工作原理

注入流程

提取 Mapper 接口的泛型实体类
初始化 TableInfo 表信息对象
获取要注入的方法列表
循环调用每个方法的 inject 方法完成注入

‌与 MybatisMapperAnnotationBuilder 的协作

‌在解析 Mapper 接口时，如果发现接口继承了 MyBatis-Plus 的 Mapper 接口，就会调用 ISqlInjector 进行方法注入

AbstractSqlInjector‌ 抽象实现类

抽象实现类，提供了基础的注入逻辑：

通过反射获取实体类信息
初始化 TableInfo 表信息对象
循环注入方法列表中的方法

DefaultSqlInjector‌ 默认实现类

默认实现类，已经包含了 BaseMapper 的基础方法（如 selectById、insert 等）

AbstractMethod 抽象类

AbstractMethod 是 MyBatis-Plus 中用于定义可注入 SQL 方法的抽象基类，属于 SQL 注入器(ISqlInjector)体系的核心组件

核心作用

SQL 方法模板

封装了通用 SQL 方法的生成逻辑，每个子类对应一种特定的 SQL 操作

‌与 ISqlInjector 协同

作为 ISqlInjector.getMethodList() 的返回元素，完成具体方法的注入

‌‌动态 SQL 支持

通过 LanguageDriver 生成最终执行的 SQL 语句

具体实现类

‌SelectById/SelectByIds/SelectByMap/SelectCount/SelectList....
Delete/DeleteById/DeleteByIds
Insert
Update/UpdateById

工作流程

‌初始化阶段

ISqlInjector 获取方法列表时实例化 AbstractMethod 子类‌

‌注入阶段

调用 inject 方法生成 MappedStatement 并注册到 Configuration‌

‌执行阶段

通过 MybatisMapperRegistry 找到对应的 MappedStatement 执行

自动装配与加载流程图整理

元数据映射图

原生myabtis配置文件加载元数据图

mybatis-plus 扩展BaseMapper后元数据图

Mybatis-plus源码解读-自动装配与加载流程

相关重要类介绍说明

MybatisPlusAutoConfiguration 自动装配类

核心作用

注意事项

‌MybatisSqlSessionFactoryBean类

核心作用

‌实现机制

MybatisSqlSessionFactoryBuilder 扩展类

核心作用

MybatisXMLMapperBuilder 类

核心作用

MybatisConfiguration 类

核心作用

MybatisMapperRegistry mapper注册器

‌核心作用

与原生实现的差异

工作流程

MybatisMapperAnnotationBuilder 类

核心作用

工作流程

与原生实现的差异

ISqlInjector sql注入器

‌核心功能

核心方法

工作原理

AbstractSqlInjector‌ 抽象实现类

DefaultSqlInjector‌ 默认实现类

AbstractMethod 抽象类

核心作用

具体实现类

工作流程

自动装配与加载流程图整理

元数据映射图

‌原生myabtis-config.xml文件加载流程时序图

mybatis-plus 扩展 BaseMapper接口扫描与加载流程图