# MyBatis-Plus持久层与数据库表结构一致性检测机制设计

## 一、检测目标

确保MyBatis-Plus持久层（Entity + Mapper + Mapper XML）与达梦数据库表结构保持一致，提前发现并规避因字段不匹配导致的运行时错误。

**应用场景**：
- 开发阶段：提前发现字段映射问题
- 上线前审计：生成完整的一致性报告

---

## 二、检测架构

```
┌─────────────────────────────────────────────────────┐
│           Schema Consistency Checker                │
├─────────────────────────────────────────────────────┤
│ 1. 元数据采集                                         │
│    ├─ DatabaseMetadataExtractor  (数据库表结构)      │
│    ├─ MapperMetadataExtractor    (Entity注解+XML)    │
│    └─ SqlFileParser             (SQL脚本)           │
├─────────────────────────────────────────────────────┤
│ 2. 一致性分析                                         │
│    ├─ TableComparator    (表级对比)                  │
│    └─ FieldComparator    (字段级对比)                │
├─────────────────────────────────────────────────────┤
│ 3. 报告生成                                           │
│    ├─ MarkdownReporter  (开发查看)                   │
│    └─ HtmlReporter      (团队分享)                   │
├─────────────────────────────────────────────────────┤
│ 4. 执行入口                                           │
│    └─ SchemaConsistencyMain  (main方法驱动)         │
└─────────────────────────────────────────────────────┘
```

---

## 三、检测维度

### 3.1 表结构检查
| 检查项 | 说明 | 严重程度 |
|--------|------|----------|
| 表是否存在 | Mapper对应的表在数据库中存在 | HIGH |
| 主键一致性 | @TableId与数据库主键定义一致 | HIGH |
| 表名匹配 | @TableName与实际表名一致 | MEDIUM |

### 3.2 字段检查
| 检查项 | 说明 | 严重程度 |
|--------|------|----------|
| 字段完整性 | Mapper字段全部在数据库中存在 | HIGH |
| 字段多余性 | 无数据库中已删除的废弃字段 | MEDIUM |
| 类型匹配 | Java类型 ↔ 达梦类型对应正确 | MEDIUM |
| 长度匹配 | VARCHAR/DECIMAL长度一致 | LOW |
| 可空性 | @TableField + 实际可空性一致 | LOW |

### 3.3 Mapper XML检查
| 检查项 | 说明 | 严重程度 |
|--------|------|----------|
| ResultMap完整性 | 所有字段有对应column定义 | MEDIUM |
| Base_Column_List | 包含所有非LOB字段 | LOW |
| SQL字段存在性 | SQL中的字段在表结构中存在 | HIGH |

---

## 四、技术实现

### 4.1 核心技术
- **数据库元数据提取**: 使用JDBC DatabaseMetaData API获取达梦表结构
- **Mapper元数据提取**: 使用MyBatis-Plus TableInfoHelper获取Entity注解 + SAX解析XML
- **类型映射**: 配置化Java类型与达梦数据库类型的对应关系
- **对比算法**: 基于反射和元数据的多维度差异检测

### 4.2 包结构
```
com.chinaweal.aiccs.dev.consistency/
├── SchemaConsistencyMain    # 入口类
├── config/                   # 配置管理
├── metadata/                 # 元数据提取器
│   ├── DatabaseMetadataExtractor
│   ├── MapperMetadataExtractor
│   └── model/               # 元数据模型
├── comparator/              # 一致性对比器
└── reporter/                # 报告生成器
```

---

## 五、使用方式

### 5.1 命令行运行

```bash
# 检查所有数据源
mvn exec:java -Dexec.mainClass="com.chinaweal.aiccs.dev.consistency.SchemaConsistencyMain"

# 检查指定数据源
mvn exec:java -Dexec.mainClass="..." -Dexec.args="--datasource=aiccs --output=html"
```

### 5.2 配置文件
- `consistency-check.yml`: 数据源配置、检查规则（忽略表、失败策略）
- `type-mapping.yml`: Java类型与达梦数据库类型映射关系

---

## 六、输出报告

支持多种报告格式：
- **Markdown**: 开发人员查看，包含差异详情和修复建议
- **HTML**: 团队分享和归档

### 报告内容结构
1. **摘要**: 一致表数量、差异表数量、严重错误统计
2. **差异详情**: 按表分组展示字段级差异（缺失、多余、类型不匹配、长度不一致等）
3. **修复建议**: 自动生成ALTER TABLE SQL语句