# 数据库配置

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

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

## 简介
本文件面向本项目（CRM 后端）的数据库配置与 MyBatis Plus 集成，覆盖数据源连接池、SQL 注入器、元对象处理器、分页插件、自动填充字段、事务管理、不同数据库的连接示例、连接池调优、SQL 监控以及数据库迁移策略与版本管理。文档以仓库中实际代码为依据，提供可操作的配置要点与优化建议，帮助读者快速搭建并稳定运行生产级数据库访问层。

## 项目结构
本项目采用多模块组织，数据库相关配置集中在基础模块 crm-base 的配置类与应用配置文件 application.yml 中：
- 应用入口与全局配置：crm-app/src/main/resources/application.yml
- MyBatis Plus 主配置：crm-base/src/main/java/com/crm/base/config/MybatisPlusConfig.java
- 元对象处理器（自动填充）：crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java
- SQL 注入器（扩展通用方法）：crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java
- 实体基类（自动填充字段定义）：crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java
- ID 生成器（雪花算法）：crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java
- 自定义 ID 生成器适配：crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java
- 批量插入去重更新支持：crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java
- 依赖声明（包含 MyBatis Plus 等）：crm-app/pom.xml

```mermaid
graph TB
A["应用配置<br/>application.yml"] --> B["MyBatis Plus 配置<br/>MybatisPlusConfig.java"]
B --> C["元对象处理器<br/>MetaObjectFillHandler.java"]
B --> D["SQL 注入器<br/>CrmSqlInjector.java"]
B --> E["ID 生成器<br/>CustomIdGenerator.java / SnowflakeIdWorker.java"]
B --> F["批量插入去重更新<br/>InsertBatchOnDuplicateKeyUpdate.java"]
C --> G["实体基类<br/>BaseEntity.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)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.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)
- [MetaObjectFillHandler.java](file://crm-base/src/main/java/com/crm/base/config/MetaObjectFillHandler.java)
- [CrmSqlInjector.java](file://crm-base/src/main/java/com/crm/base/config/CrmSqlInjector.java)
- [BaseEntity.java](file://crm-base/src/main/java/com/crm/base/domain/entity/BaseEntity.java)
- [SnowflakeIdWorker.java](file://crm-base/src/main/java/com/crm/base/config/SnowflakeIdWorker.java)
- [CustomIdGenerator.java](file://crm-base/src/main/java/com/crm/base/config/CustomIdGenerator.java)
- [InsertBatchOnDuplicateKeyUpdate.java](file://crm-base/src/main/java/com/crm/base/config/InsertBatchOnDuplicateKeyUpdate.java)
- [pom.xml](file://crm-app/pom.xml)

## 核心组件
- MyBatis Plus 主配置：集中注册分页插件、乐观锁、SQL 注入器、ID 生成器、全局策略等。
- 元对象处理器：实现创建时间、更新时间、创建人、更新人等字段的自动填充。
- SQL 注入器：扩展通用 Mapper 方法，提升批量操作与复杂查询能力。
- ID 生成器：基于雪花算法的分布式唯一 ID 生成，避免自增主键瓶颈。
- 批量插入去重更新：针对 MySQL 的 ON DUPLICATE KEY UPDATE 封装，简化幂等写入。
- 实体基类：统一审计字段与公共属性，配合自动填充使用。

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

## 架构总览
下图展示了从应用启动到数据库访问的关键路径：应用加载配置 → MyBatis Plus 初始化 → 插件与处理器装配 → 业务调用通过 Mapper 执行 SQL。

```mermaid
sequenceDiagram
participant App as "应用启动"
participant MP as "MyBatis Plus 配置"
participant Interceptor as "拦截器/插件"
participant Handler as "元对象处理器"
participant Injector as "SQL 注入器"
participant DB as "数据库"
App->>MP : 加载配置并初始化
MP->>Interceptor : 注册分页/乐观锁等插件
MP->>Handler : 注册自动填充处理器
MP->>Injector : 注册扩展方法注入器
App->>DB : 发起查询/更新请求
DB-->>App : 返回结果集
```

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

## 详细组件分析

### MyBatis Plus 配置
- 功能要点
  - 注册分页插件、乐观锁插件、SQL 注入器、ID 生成器、全局策略。
  - 设置驼峰映射、逻辑删除、打印 SQL（开发环境）、类型处理器等。
  - 与数据源解耦，由 Spring Boot 数据源驱动完成连接池初始化。
- 关键配置项说明
  - 分页插件：控制分页参数解析、方言、是否 count 查询等。
  - 乐观锁：版本号字段与冲突处理策略。
  - SQL 注入器：扩展通用方法，如批量插入去重更新。
  - ID 生成器：雪花算法或自定义策略。
  - 全局策略：驼峰转下划线、逻辑删除字段、字段策略等。
- 与数据源的关系
  - 数据源由 Spring Boot 根据 application.yml 中的 spring.datasource.* 配置创建，MyBatis Plus 仅负责 ORM 层装配。

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

### 数据源与连接池配置
- 配置位置
  - 应用级数据源配置位于 application.yml 的 spring.datasource.* 节点。
- 连接池选择
  - 默认使用 HikariCP（Spring Boot 推荐），具备高性能与低开销特性。
- 关键调优参数
  - 最大连接数、最小空闲连接、连接超时、心跳检测、连接泄漏检测等。
  - 根据并发量、慢查询比例、数据库资源上限进行压测后确定。
- 多数据源
  - 如需读写分离或多库，可通过多数据源方案拆分 DataSource 与 SqlSessionFactory。
- 注意事项
  - 确保 JDBC URL、驱动类名、用户名密码与环境一致。
  - 开启连接健康检查与超时回收，避免连接泄露导致 OOM。

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

### SQL 注入器配置
- 作用
  - 在运行时向 Mapper 注入通用方法，减少样板代码。
- 常见扩展
  - 批量插入去重更新（MySQL ON DUPLICATE KEY UPDATE）。
  - 条件构造器增强、动态表名、分库分表辅助方法等。
- 使用方式
  - 在 MyBatis Plus 配置中注册自定义注入器类。
  - 在 Mapper 接口继承基础接口后即可使用扩展方法。

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

### 元对象处理器与自动填充
- 触发时机
  - 插入前、更新前、插入时填充、更新时填充等。
- 典型字段
  - 创建时间、更新时间、创建人、更新人、逻辑删除标记等。
- 实现要点
  - 实现 MetaObjectHandler 接口，按字段名匹配填充。
  - 结合 BaseEntity 统一审计字段，保证一致性。
- 安全与幂等
  - 避免覆盖业务显式设置的值；对空值进行保护性判断。

章节来源
- [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)

### ID 生成器（雪花算法）
- 设计目标
  - 分布式环境下高吞吐、单调递增、可排序的唯一 ID。
- 实现要点
  - 数据中心位、机器位、序列位分配合理，避免冲突。
  - 时钟回拨处理策略（容忍、告警、拒绝）。
- 集成方式
  - 通过自定义 ID 生成器接入 MyBatis Plus 全局策略。

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

### 批量插入去重更新
- 场景
  - 幂等写入、增量同步、Upsert 需求。
- 实现
  - 基于 MySQL 的 ON DUPLICATE KEY UPDATE 语法封装。
  - 指定唯一键与冲突时的更新字段集合。
- 注意
  - 需确保唯一索引存在；大事务分批提交，避免锁竞争。

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

### 分页插件配置
- 功能
  - 自动改写 SQL 为分页语句，支持 count 查询与物理分页。
- 关键参数
  - 方言、是否 count、是否 optimizeCountSql、是否 removePageHelperOne。
- 使用
  - 在 Service 层使用 IPage 与 Page 对象进行分页查询。

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

### 事务管理配置
- 默认行为
  - Spring 的 @Transactional 注解生效，默认传播级别与回滚规则。
- 建议
  - 明确只读事务、隔离级别、超时时间；避免长事务。
  - 对批量写操作分批提交，降低锁持有时间。

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

### 不同数据库类型的连接配置示例
- MySQL
  - JDBC URL、驱动类、连接池参数、字符集与时区。
- PostgreSQL
  - 驱动类、URL 格式、SSL、连接池参数。
- Oracle
  - SID/服务名、驱动类、连接池参数。
- SQL Server
  - 实例名、端口、驱动类、连接池参数。
- 说明
  - 以上为通用模板，具体参数需结合实际环境与数据库版本调整。

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

### SQL 监控配置
- 开发调试
  - 开启 SQL 日志输出，便于定位慢查询与问题 SQL。
- 生产监控
  - 建议使用 APM 或数据库代理进行 SQL 采集与分析。
- 性能影响
  - 生产环境关闭详细 SQL 日志，按需采样。

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

### 数据库迁移策略与版本管理
- 工具选型
  - Flyway/Liquibase：脚本化、版本化、可回滚。
- 策略建议
  - 正向迁移脚本命名规范；禁止直接修改已发布脚本。
  - 变更先行（先加字段/索引，再改代码），灰度发布。
  - 回滚脚本与热修复流程完善。
- 自动化
  - CI/CD 流水线集成迁移任务，失败阻断发布。

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

## 依赖关系分析
- 外部依赖
  - MyBatis Plus、Spring Boot Starter、数据库驱动、连接池（HikariCP）。
- 内部依赖
  - MyBatis Plus 配置依赖元对象处理器、SQL 注入器、ID 生成器。
  - 实体基类与自动填充处理器协同工作。

```mermaid
graph LR
App["应用"] --> MP["MyBatis Plus 配置"]
MP --> H["元对象处理器"]
MP --> I["SQL 注入器"]
MP --> ID["ID 生成器"]
H --> E["实体基类"]
MP --> DS["数据源/连接池"]
DS --> DB["数据库"]
```

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

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

## 性能考虑
- 连接池调优
  - 根据 CPU、内存、数据库连接上限设定最大连接数与空闲连接阈值。
  - 启用连接泄漏检测与超时回收，避免连接耗尽。
- SQL 优化
  - 合理使用索引、避免 N+1 查询、分页限制返回条数。
  - 使用批量操作减少往返次数。
- 缓存与异步
  - 热点数据使用 Redis 缓存；耗时任务异步化。
- 监控与告警
  - 关注连接池使用率、慢查询、锁等待、事务超时。

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

## 故障排查指南
- 常见问题
  - 连接池耗尽：检查最大连接数、慢查询、未释放连接。
  - 自动填充失效：确认处理器注册与字段名匹配。
  - 分页异常：检查方言与 count 查询配置。
  - ID 冲突：校验雪花位分配与时钟回拨处理。
- 排查步骤
  - 查看应用日志与 SQL 日志。
  - 检查数据库连接状态与锁信息。
  - 使用 APM 定位慢 SQL 与热点方法。
  - 逐步缩小范围，复现问题。

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

## 结论
通过合理的 MyBatis Plus 配置、连接池调优、自动填充与 ID 生成策略，以及完善的迁移与监控体系，可在保证性能与稳定性的前提下高效支撑 CRM 系统的数据库访问需求。建议在生产环境严格遵循变更管理与性能基线，持续优化。

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

## 附录
- 常用配置清单
  - 数据源：URL、驱动、用户名、密码、连接池参数。
  - MyBatis Plus：分页、乐观锁、SQL 注入器、ID 生成器、全局策略。
  - 自动填充：审计字段、处理器注册。
  - 事务：传播级别、隔离级别、超时。
- 参考实践
  - 连接池压测与容量规划。
  - 数据库迁移脚本规范与回滚策略。
  - SQL 监控与慢查询治理流程。

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