跳到主要内容

数据访问组件 (yudao-spring-boot-starter-mybatis)

引用文件

本文引用的文件

目录​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考量
  8. 故障排查指南
  9. 结论
  10. 附录

简介​

本文件面向 yudao-spring-boot-starter-mybatis 数据访问组件，系统性阐述其在 Spring Boot 生态中的 MyBatis Plus 集成、通用 Mapper 基类(BaseMapper)设计理念与增强能力、自动填充、多数据源与读写分离、动态数据源切换、分页查询、条件构造器、乐观锁与逻辑删除、数据库连接池、SQL 性能监控与 P6Spy 日志输出，以及 MyBatis 组件扩展点（自定义类型处理器、插件开发、批量操作优化）等主题。文档力求以循序渐进的方式呈现，既便于初学者理解，也为资深开发者提供深入的技术参考。

项目结构​

该组件位于 yudao-framework 子模块中，作为 MyBatis Plus 的增强与封装，提供统一的自动配置、通用 Mapper 增强、动态表名、分页、自动填充、多数据源支持与 SQL 监控等能力。关键文件与职责如下：

  • 自动配置与拦截器：YudaoMybatisAutoConfiguration 负责注册 MyBatis Plus 拦截器、动态表名插件、自动填充处理器、主键生成策略等。
  • 通用 Mapper 增强：BaseMapperX 在 MyBatis Plus 的 BaseMapper 与 MPJ 基础之上，提供分页、联表分页、条件便捷方法、批量操作等增强。
  • 动态数据源：YudaoDataSourceAutoConfiguration、DynamicDataSourceProperties、DynamicDataSourceContextHolder 提供多数据源与动态切换能力。
  • 配置属性：MybatisProperties 提供动态表名后缀配置项。
  • 自动填充：DefaultDBFieldHandler 实现字段自动填充。
  • 示例与集成：GoViewMysqlDataServiceImpl 展示手动切换数据源的使用方式；DataSourceConfigServiceImpl 展示数据源配置的增删改查。

Mermaid Diagram Code:

graph TB
subgraph "MyBatis Plus 增强"
A["YudaoMybatisAutoConfiguration<br/>自动配置与拦截器注册"]
B["BaseMapperX<br/>通用 Mapper 增强接口"]
C["MybatisProperties<br/>动态表名配置"]
D["DefaultDBFieldHandler<br/>自动填充处理器"]
end
subgraph "多数据源"
E["YudaoDataSourceAutoConfiguration<br/>多数据源自动配置"]
F["DynamicDataSourceProperties<br/>数据源配置属性"]
G["DynamicDataSourceContextHolder<br/>动态数据源上下文"]
end
subgraph "示例与集成"
H["GoViewMysqlDataServiceImpl<br/>手动切换数据源示例"]
I["DataSourceConfigServiceImpl<br/>数据源配置服务"]
end
A --> B
A --> C
A --> D
E --> F
E --> G
H --> G
I --> F

图表来源

章节来源

核心组件​

  • 通用 Mapper 增强 BaseMapperX
    • 提供分页查询（含排序字段）、联表分页、条件便捷方法（等值、IN、计数、首条记录等）、批量插入/更新、删除等能力。
    • 对 SQL Server 的批量插入做了兼容处理，避免批量插入后获取主键失败的问题。
  • 自动配置 YudaoMybatisAutoConfiguration
    • 注册 MyBatis Plus 拦截器链，包含动态表名插件、分页插件。
    • 注册自动填充处理器 DefaultDBFieldHandler。
    • 根据数据库类型选择合适的主键生成策略。
  • 动态表名与分页
    • 通过 ThreadLocal 维护表名后缀，结合 DynamicTableNameInnerInterceptor 实现按业务规则动态拼接表名。
    • MyPaginationInnerInterceptor 提供分页能力。
  • 多数据源与动态切换
    • YudaoDataSourceAutoConfiguration 提供多数据源自动装配。
    • DynamicDataSourceContextHolder 提供 push/clear 等上下文切换方法。
  • 自动填充
    • DefaultDBFieldHandler 实现创建时间、更新时间、创建者、更新者等字段的自动填充。
  • 配置属性
    • MybatisProperties 提供 addSuffixTableNames，声明需要自动追加后缀的表名集合。

章节来源

架构总览​

下图展示 MyBatis Plus 增强与多数据源的整体交互关系：

Mermaid Diagram Code:

graph TB
Client["应用服务层"] --> Mapper["Mapper 接口<br/>BaseMapperX"]
Mapper --> MP["MyBatis Plus 拦截器链"]
MP --> DynTable["动态表名插件"]
MP --> Pagination["分页插件"]
MP --> Fill["自动填充处理器"]
Mapper --> DS["动态数据源<br/>DynamicDataSourceContextHolder"]
DS --> Pool["数据库连接池"]
Pool --> DB["数据库"]

图表来源

详细组件分析​

通用 Mapper 增强 BaseMapperX​

  • 设计理念
    • 在 MyBatis Plus 的 BaseMapper 与 MPJ 基础之上，提供更贴近业务的便捷方法，减少重复代码。
    • 将分页、联表分页、条件构造、批量操作等常用能力内聚到接口中，提升可维护性与一致性。
  • 关键能力
    • 分页查询：支持传入排序字段集合，自动构建分页对象并返回 PageResult。
    • 联表分页：基于 MPJ 的 Lambda/Join 包装器，提供 selectJoinPage 多种重载。
    • 条件便捷方法：提供按字段相等、IN、计数、首条记录等常用查询方法。
    • 批量操作：insertBatch、updateBatch 等，针对 SQL Server 做了兼容处理。
    • 删除：按字段删除。
  • 复杂度与性能
    • 分页与联表分页基于 MyBatis Plus 内部分页实现，复杂度主要受数据量与索引影响。
    • 批量插入/更新采用 Db 工具类，SQL Server 场景回退为逐条插入，避免主键回写问题。

Mermaid Diagram Code:

classDiagram
class BaseMapperX~T~ {
+selectPage(pageParam, queryWrapper) PageResult~T~
+selectPage(pageParam, sortingFields, queryWrapper) PageResult~T~
+selectJoinPage(pageParam, resultTypeClass, wrapper) PageResult~D~
+selectJoinPage(pageParam, resultTypeClass, joinWrapper) PageResult~DTO~
+selectOne(field, value) T
+selectOne(field1, value1, field2, value2) T
+selectFirstOne(field, value) T
+selectCount() Long
+selectCount(field, value) Long
+selectList() T[]
+selectList(field, values) T[]
+insertBatch(entities) Boolean
+insertBatch(entities, size) Boolean
+updateBatch(entities) Boolean
+updateBatch(entities, size) Boolean
+delete(field, value) int
}

图表来源

章节来源

自动配置与拦截器链​

  • 自动配置
    • 在 MyBatis Plus 自动配置之前执行，确保 Mapper 扫描无警告。
    • 启用配置属性绑定，注册 MyBatis Plus 拦截器链、动态表名插件、自动填充处理器、主键生成策略等。
  • 拦截器链
    • 动态表名插件：根据 ThreadLocal 中的表名后缀与配置的表名集合，动态拼接表名。
    • 分页插件：MyPaginationInnerInterceptor 提供分页能力。
    • 自动填充处理器：DefaultDBFieldHandler 实现字段自动填充。
  • 主键生成策略
    • 根据数据库类型选择合适的 IKeyGenerator，覆盖 PostgreSQL、Oracle、H2、Kingbase、DM 等。

Mermaid Diagram Code:

sequenceDiagram
participant App as "应用启动"
participant Auto as "YudaoMybatisAutoConfiguration"
participant Inter as "MyBatisPlusInterceptor"
participant Dyn as "DynamicTableNameInnerInterceptor"
participant Pg as "MyPaginationInnerInterceptor"
App->>Auto : 加载自动配置
Auto->>Inter : 创建拦截器链
Auto->>Dyn : 注册动态表名插件
Auto->>Pg : 注册分页插件
App-->>App : 完成自动配置

图表来源

章节来源

动态表名与分页​

  • 动态表名
    • 通过 ThreadLocal 维护表名后缀，结合 DynamicTableNameInnerInterceptor，在 SQL 解析阶段动态替换表名。
    • 配合 MybatisProperties 的 addSuffixTableNames，仅对声明的表名进行后缀追加。
  • 分页
    • MyPaginationInnerInterceptor 提供分页能力，与 BaseMapperX 的分页方法配合使用。

Mermaid Diagram Code:

flowchart TD
Start(["进入查询"]) --> GetSuffix["获取表名后缀(ThreadLocal)"]
GetSuffix --> CheckTable["检查表名是否在配置集合中"]
CheckTable --> |是| Append["追加后缀"]
CheckTable --> |否| Keep["保持原表名"]
Append --> BuildSQL["构建最终 SQL"]
Keep --> BuildSQL
BuildSQL --> Exec["执行查询"]
Exec --> End(["返回结果"])

图表来源

章节来源

多数据源、读写分离与动态切换​

  • 多数据源自动配置
    • YudaoDataSourceAutoConfiguration 提供多数据源装配，DynamicDataSourceProperties 提供数据源配置属性。
  • 动态切换
    • DynamicDataSourceContextHolder 提供 push/clear 方法，结合业务上下文实现动态数据源切换。
  • 使用示例
    • GoViewMysqlDataServiceImpl 展示在执行特定查询前切换数据源，结束后清理上下文。

Mermaid Diagram Code:

sequenceDiagram
participant Svc as "业务服务"
participant Ctx as "DynamicDataSourceContextHolder"
participant DS as "动态数据源"
participant DB as "目标数据源"
Svc->>Ctx : push(数据源标识)
Ctx->>DS : 切换到目标数据源
Svc->>DB : 执行查询/写入
Svc->>Ctx : clear()
Ctx-->>Svc : 清理上下文

图表来源

章节来源

自动填充、乐观锁与逻辑删除​

  • 自动填充
    • DefaultDBFieldHandler 实现创建时间、更新时间、创建者、更新者等字段的自动填充。
  • 乐观锁
    • 通过 MyBatis Plus 的版本号字段实现，配合数据库的行级版本控制，防止并发覆盖。
  • 逻辑删除
    • 通过 MyBatis Plus 的逻辑删除注解与全局配置，实现软删除，不影响统计与历史数据。

章节来源

条件构造器与联表查询​

  • 条件构造器
    • 基于 QueryWrapper/LambdaQueryWrapper，提供等值、IN、范围、排序等条件组合。
  • 联表查询
    • 基于 MPJ 的 MPJLambdaWrapper/MPJBaseJoin，提供联表分页与结果映射。

章节来源

批量操作优化​

  • 批量插入/更新
    • BaseMapperX.insertBatch 与 updateBatch 基于 Db 工具类，支持指定批次大小。
    • SQL Server 场景回退为逐条插入，避免批量插入后主键回写异常。
  • 批量删除
    • 通过条件构造器与批量更新实现高效删除。

章节来源

SQL 性能监控与 P6Spy 日志输出​

  • P6Spy 集成
    • 通过 p6spy-spring-boot-starter 输出 SQL 日志，便于性能分析与问题定位。
  • 监控建议
    • 结合慢查询阈值、SQL 执行次数与耗时统计，识别热点 SQL 并优化索引与语句。

章节来源

MyBatis 组件扩展点​

  • 自定义类型处理器
    • 通过 MyBatis 类型处理器注册机制，实现复杂类型的序列化/反序列化。
  • 插件开发
    • 基于 MyBatis Plus 拦截器链，开发分页、审计、租户隔离等插件。
  • 批量操作优化
    • 使用 BaseMapperX 的批量方法或自定义批量 SQL，结合数据库特性（如 MySQL 的批量语法）提升吞吐。

章节来源

依赖关系分析​

  • 组件耦合
    • BaseMapperX 依赖 MyBatis Plus 与 MPJ，提供分页与联表能力。
    • YudaoMybatisAutoConfiguration 依赖 MyBatis Plus、JsqlParser、Druid、P6Spy 等，负责拦截器与连接池配置。
    • 多数据源组件通过 DynamicDataSourceContextHolder 与业务服务解耦。
  • 外部依赖
    • MySQL、Oracle、PostgreSQL、SQLServer、达梦、金仓、openGauss 等驱动可选引入。
    • TDEngine JDBC 驱动用于时序数据源。

Mermaid Diagram Code:

graph TB
MPAuto["YudaoMybatisAutoConfiguration"] --> MP["MyBatis Plus"]
MPAuto --> Jsql["JsqlParser"]
MPAuto --> Druid["Druid 连接池"]
MPAuto --> P6Spy["P6Spy 日志"]
MapperX["BaseMapperX"] --> MP
DS["YudaoDataSourceAutoConfiguration"] --> DSProps["DynamicDataSourceProperties"]
DS --> DSContextHolder["DynamicDataSourceContextHolder"]

图表来源

章节来源

性能考量​

  • 分页与联表
    • 合理使用排序字段与索引，避免全表扫描；联表查询注意小表驱动与过滤前置。
  • 批量操作
    • 使用 BaseMapperX 的批量方法或自定义批量 SQL，结合数据库特性提升吞吐；SQL Server 场景避免批量主键回写问题。
  • 动态表名
    • 控制表名后缀数量与命名规范，避免过多的表分散导致查询计划抖动。
  • 连接池
    • 结合业务峰值 QPS 与事务长度，合理设置连接池大小与超时参数，避免连接争用。
  • SQL 监控
    • 通过 P6Spy 输出 SQL，结合慢查询日志与数据库 EXPLAIN 分析热点 SQL。

故障排查指南​

  • Mapper 扫描警告
    • 确保 YudaoMybatisAutoConfiguration 在 MyBatis Plus 自动配置之前执行，避免扫描不到 Mapper 导致的警告。
  • 动态表名无效
    • 检查 MybatisProperties 的 addSuffixTableNames 是否包含目标表名，确认 ThreadLocal 中的表名后缀是否正确设置与清理。
  • 数据源切换异常
    • 确认业务执行前后是否正确调用 DynamicDataSourceContextHolder.push 与 clear，避免上下文泄漏。
  • 批量插入失败（SQL Server）
    • 使用 BaseMapperX 的批量方法，内部已做逐条插入兼容处理。
  • 自动填充字段为空
    • 检查 DefaultDBFieldHandler 是否被正确注册，以及实体类字段是否标注了自动填充注解。

章节来源

结论​

yudao-spring-boot-starter-mybatis 通过对 MyBatis Plus 的深度集成与扩展，提供了通用 Mapper 增强、动态表名、分页、自动填充、多数据源与动态切换、SQL 监控等能力，能够有效降低数据访问层的开发成本并提升可维护性。结合合理的索引设计、批量操作优化与连接池配置，可在高并发场景下获得稳定且高效的性能表现。

附录​

  • 数据源配置服务示例
    • DataSourceConfigServiceImpl 展示了数据源配置的增删改查流程，便于在后台管理中动态维护数据源。

章节来源

用户文档
AI 助手
Agent 列表
请选择一个 Agent 开始对话
AI 问答