# MyBatis Plus配置

<cite>
**本文引用的文件**   
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)
</cite>

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

## 简介
本文件围绕 MyBatis Plus 在该项目中的配置与使用进行系统化说明，重点覆盖：
- 分页插件、SQL 注入器、元对象填充处理器的配置与用法
- 自定义 SQL 注入器的实现原理（批量插入更新、逻辑删除等增强）
- 元对象填充处理器自动填充创建时间、更新时间等字段的机制
- 配置参数说明、性能优化建议与常见问题解决方案

## 项目结构
本项目将 MyBatis Plus 相关配置集中在基础模块 crm-base 的 config 包中，并通过应用模块 crm-app 的 application.yml 进行外部化配置。关键文件如下：
- MybatisPlusConfig：注册 MP 插件、全局策略、ID 生成器等
- CrmSqlInjector：自定义 SQL 注入器，扩展批量插入更新、逻辑删除等能力
- MetaObjectFillHandler：元对象填充处理器，统一自动填充审计字段
- BaseEntity / OwnedEntity：实体基类，定义通用审计与数据权限字段
- InsertBatchOnDuplicateKeyUpdate：批量插入时冲突处理策略
- CustomIdGenerator / SnowflakeIdWorker / SnowflakeProperties：分布式 ID 生成与配置
- CrmBaseMapper：基础 Mapper 接口，供业务 Mapper 继承
- application.yml：数据库连接、MP 全局配置等

```mermaid
graph TB
subgraph "应用层"
APP["应用启动<br/>application.yml"]
end
subgraph "基础配置(crm-base)"
CFG["MybatisPlusConfig"]
INJ["CrmSqlInjector"]
FILL["MetaObjectFillHandler"]
BASE["BaseEntity / OwnedEntity"]
BATCH["InsertBatchOnDuplicateKeyUpdate"]
IDGEN["CustomIdGenerator / SnowflakeIdWorker / SnowflakeProperties"]
MAPPER["CrmBaseMapper"]
end
APP --> CFG
CFG --> INJ
CFG --> FILL
CFG --> IDGEN
CFG --> BATCH
MAPPER --> BASE
INJ --> BASE
FILL --> BASE
```

图表来源
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

章节来源
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

## 核心组件
- 分页插件：通过 MybatisPlusConfig 注册，提供 Page 分页查询能力，支持物理分页与排序。
- SQL 注入器：通过 CrmSqlInjector 扩展 MP 内置方法，如批量插入更新、逻辑删除等。
- 元对象填充处理器：通过 MetaObjectFillHandler 自动填充审计字段（如创建时间、更新时间）。
- 全局策略：配置表名、主键策略、逻辑删除、驼峰映射等。
- ID 生成器：基于雪花算法的分布式 ID 生成，支持可配置参数。
- 批量插入冲突处理：InsertBatchOnDuplicateKeyUpdate 定义 ON DUPLICATE KEY UPDATE 行为。
- 基础 Mapper：CrmBaseMapper 作为业务 Mapper 的统一父接口。

章节来源
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java)

## 架构总览
下图展示了 MyBatis Plus 在系统中的装配顺序与调用链路：应用启动加载配置，注册插件与处理器；业务调用 Mapper 时，由注入器增强方法；实体写入时由填充处理器自动填充审计字段；ID 生成器为新增记录分配唯一标识。

```mermaid
sequenceDiagram
participant App as "应用启动"
participant MP as "MybatisPlusConfig"
participant Inj as "CrmSqlInjector"
participant Fill as "MetaObjectFillHandler"
participant Gen as "CustomIdGenerator"
participant DB as "数据库"
App->>MP : 初始化并注册插件/策略/处理器
MP->>Inj : 注册自定义SQL注入器
MP->>Fill : 注册元对象填充处理器
MP->>Gen : 注册ID生成器
Note over MP,Gen : 完成全局装配
App->>DB : 业务调用(分页/插入/更新/删除)
DB-->>App : 返回结果
```

图表来源
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)

## 详细组件分析

### 分页插件配置与使用
- 功能要点
  - 启用物理分页，拦截 SQL 并追加 LIMIT/OFFSET 或方言特定语法
  - 支持排序、条件过滤、总数统计
  - 与 Page 对象配合，简化分页查询代码
- 配置位置
  - 在 MybatisPlusConfig 中注册分页插件
  - 可通过 application.yml 调整分页默认大小等参数
- 使用方式
  - Service 层构造 Page 对象，传入查询条件与排序
  - Mapper 执行分页查询后返回 PageResult 封装结果

章节来源
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

### SQL 注入器（CrmSqlInjector）
- 设计目标
  - 扩展 MP 内置方法，减少样板代码
  - 提供批量插入更新、逻辑删除等常用能力
- 增强能力
  - 批量插入更新：根据唯一键冲突策略合并更新
  - 逻辑删除：对指定字段标记删除状态，查询自动过滤
  - 其他自定义方法：可按需扩展
- 工作原理
  - 继承 MP 注入器，重写方法注册逻辑
  - 在 MP 初始化阶段将自定义方法注入到 Mapper 代理中
  - 结合实体注解与全局策略生效

```mermaid
classDiagram
class CrmSqlInjector {
+注册批量插入更新()
+注册逻辑删除()
+扩展其他方法()
}
class MybatisPlusConfig {
+注册SQL注入器()
}
class BaseEntity {
+审计字段()
}
class OwnedEntity {
+数据权限字段()
}
MybatisPlusConfig --> CrmSqlInjector : "注册"
CrmSqlInjector --> BaseEntity : "读取注解/字段"
CrmSqlInjector --> OwnedEntity : "读取注解/字段"
```

图表来源
- [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)

章节来源
- [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)

### 元对象填充处理器（MetaObjectFillHandler）
- 功能要点
  - 自动填充创建时间、更新时间、创建人、更新人等审计字段
  - 支持按条件填充（仅在首次插入或每次更新时）
- 工作机制
  - 实现 MP 的 MetaObjectHandler 接口
  - 在 insertFill / updateFill 钩子中设置字段值
  - 结合实体注解或命名约定识别待填充字段
- 适用场景
  - 所有继承 BaseEntity / OwnedEntity 的实体自动获得审计能力

```mermaid
flowchart TD
Start(["插入/更新入口"]) --> CheckType{"操作类型"}
CheckType --> |插入| InsertFill["执行insertFill"]
CheckType --> |更新| UpdateFill["执行updateFill"]
InsertFill --> SetCreateTime["设置创建时间/创建人"]
UpdateFill --> SetUpdateTime["设置更新时间/更新人"]
SetCreateTime --> End(["完成"])
SetUpdateTime --> End
```

图表来源
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)

章节来源
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)

### 批量插入冲突处理（InsertBatchOnDuplicateKeyUpdate）
- 功能要点
  - 定义批量插入时的冲突解决策略（如 ON DUPLICATE KEY UPDATE）
  - 指定冲突时更新的字段集合
- 使用方式
  - 在 MP 的批量插入方法中启用该策略
  - 适用于幂等导入、增量同步等场景

章节来源
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)

### ID 生成器（CustomIdGenerator / SnowflakeIdWorker / SnowflakeProperties）
- 功能要点
  - 基于雪花算法生成全局唯一 ID
  - 支持通过配置文件调整机器位、序列位等参数
- 集成方式
  - 在 MybatisPlusConfig 中注册自定义 ID 生成器
  - 实体主键字段配置对应策略

章节来源
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)

### 基础 Mapper（CrmBaseMapper）
- 功能要点
  - 作为业务 Mapper 的统一父接口
  - 可在此扩展通用方法（如分页、条件查询）
- 使用方式
  - 业务 Mapper 继承 CrmBaseMapper，直接获得增强能力

章节来源
- [CrmBaseMapper.java](file://crm-base/src/main/java/com/crm/base/mapper/CrmBaseMapper.java)

## 依赖关系分析
- MybatisPlusConfig 依赖 CrmSqlInjector、MetaObjectFillHandler、ID 生成器与批量策略
- CrmSqlInjector 依赖实体基类以读取注解与字段信息
- MetaObjectFillHandler 依赖实体基类以识别审计字段
- 应用通过 application.yml 提供数据库与 MP 全局配置

```mermaid
graph LR
APP["application.yml"] --> CFG["MybatisPlusConfig"]
CFG --> INJ["CrmSqlInjector"]
CFG --> FILL["MetaObjectFillHandler"]
CFG --> IDGEN["CustomIdGenerator / SnowflakeIdWorker / SnowflakeProperties"]
CFG --> BATCH["InsertBatchOnDuplicateKeyUpdate"]
INJ --> BASE["BaseEntity / OwnedEntity"]
FILL --> BASE
```

图表来源
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [OwnedEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/OwnedEntity.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

章节来源
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [application.yml](file://crm-app/src/main/resources/application.yml)

## 性能考虑
- 分页查询
  - 合理设置 page size，避免一次性拉取过多数据
  - 使用索引覆盖查询，减少回表
  - 复杂条件尽量下推到数据库层
- 批量操作
  - 使用批量插入/更新减少网络往返
  - 控制单次批次大小，避免事务过大导致锁竞争
  - 冲突策略选择合适字段，减少不必要的更新
- ID 生成
  - 雪花算法分片均匀，注意时钟回拨防护
  - 合理配置机器位与序列位，避免冲突
- 元对象填充
  - 仅填充必要字段，避免多余赋值
  - 区分插入与更新填充策略，降低无效写操作

[本节为通用指导，不直接分析具体文件]

## 故障排查指南
- 分页无效
  - 检查是否已注册分页插件
  - 确认 SQL 是否被拦截且未绕过 MP
- 逻辑删除失效
  - 检查实体逻辑删除字段与全局策略配置
  - 确认查询是否启用了逻辑删除过滤
- 元对象填充未生效
  - 检查处理器是否注册
  - 确认字段命名与注解是否符合预期
- 批量插入冲突策略异常
  - 核对唯一键约束与冲突字段映射
  - 检查数据库方言与语法支持
- ID 生成异常
  - 检查雪花参数配置与节点隔离
  - 关注时钟回拨与重复 ID 问题

章节来源
- [MybatisPlusConfig.java](file://crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java)
- [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [SnowflakeProperties.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeProperties.java)

## 结论
通过 MybatisPlusConfig 集中装配分页插件、SQL 注入器、元对象填充处理器与 ID 生成器，项目在数据访问层实现了高内聚、低耦合的增强能力。自定义 SQL 注入器提供了批量插入更新与逻辑删除等实用方法，元对象填充处理器统一了审计字段管理，配合合理的配置与性能优化策略，可有效提升开发效率与系统稳定性。

[本节为总结性内容，不直接分析具体文件]

## 附录
- 配置参数建议
  - 分页默认大小：根据业务场景设定，避免过大
  - 逻辑删除字段：统一命名，便于全局策略生效
  - 雪花参数：确保节点唯一，避免时钟回拨
  - 批量批次大小：平衡吞吐与内存占用
- 最佳实践
  - 实体基类统一审计字段
  - Mapper 继承基础接口，复用通用方法
  - 服务层封装分页与批量操作，屏蔽底层细节

[本节为补充信息，不直接分析具体文件]