# MyBatis 字段名与数据库列名一致性检查工具

这是一个 MyBatis 配置验证工具，用于检查实体类（POJO）的字段名与数据库表的列名是否一致，以及相关的 MyBatis 配置是否正确。

## 功能特性

该工具提供以下 7 个 MCP 工具函数：

### 1. `check_entity_fields()`
检查实体类字段定义，列出所有字段名并检查与数据库列名的对应关系。

### 2. `check_result_maps()`
检查 Mapper XML 中的 resultMap 配置：
- resultMap 的 id 和 type 是否正确
- 每个 `<result>` 的 column 属性是否与 SQL 查询列名一致
- 每个 `<result>` 的 property 属性是否与实体类字段名一致
- 嵌套对象的字段映射是否正确

### 3. `check_mapper_annotations()`
检查 Mapper 接口中的 @Results 注解配置：
- @Results 数组中每个 @Result 的 column 和 property 是否正确
- @ResultMap 引用的 resultMap id 是否与 XML 中定义的完全一致

### 4. `check_sql_aliases()`
检查 SQL 语句中的列别名配置：
- 对于使用 resultType 的查询，SQL 语句中是否通过 AS 为列起别名
- 列别名是否与实体字段名匹配（考虑驼峰转换）

### 5. `check_join_queries()`
检查联合查询中的字段重复或歧义问题：
- 涉及多表关联的查询，是否存在同名字段
- 是否为重复列使用了唯一别名
- 在 resultMap 中是否正确映射

### 6. `check_type_handlers()`
检查特殊类型字段的类型处理器配置：
- 实体字段类型与数据库列类型不完全匹配的字段
- 是否配置了自定义 TypeHandler
- 检查全局配置、resultMap 和注解中的 typeHandler 属性

### 7. `generate_detailed_report()` ⭐
生成详细的 MyBatis 配置检查报告，**只显示发现的问题**，每个问题都以可直接使用的 prompt 格式呈现。

## 配置文件

在项目根目录创建 `config.json` 文件，配置以下路径：

```json
{
  "entity_paths": [
    "src/main/java/com/example/entity",
    "src/main/java/com/example/model"
  ],
  "mapper_paths": [
    "src/main/resources/mapper",
    "src/main/java/com/example/mapper"
  ],
  "sql_files": [
    "src/main/resources/sql/schema.sql",
    "src/main/resources/db/migration/V1__init.sql"
  ],
  "report_path": "reports/mybatis_check_report.txt"
}
```

### 配置说明

- **entity_paths**: 实体类（POJO）的目录路径或文件路径，支持多个路径
- **mapper_paths**: Mapper XML 文件和 Mapper 接口的目录路径，支持多个路径
- **sql_files**: 数据库建表 SQL 文件的路径，支持多个文件
- **report_path**: 报告输出路径（可选，默认为 `mybatis_check_report.txt`）

### 重要特性

✅ **递归扫描**: 工具会自动递归扫描配置目录中的所有子文件夹
✅ **多路径支持**: 支持配置多个 entity_paths、mapper_paths 和 sql_files
✅ **报告路径配置**: 可自定义报告输出路径，支持绝对路径和相对路径
✅ **自动创建目录**: 如果报告目录不存在，工具会自动创建

## 使用方式

### 作为 MCP 服务器运行

```bash
python main.py
```

工具会自动加载 `config.json` 配置，并启动 MCP 服务器。

### 独立模式运行（用于测试）

如果未安装 mcp 包，工具会以独立模式运行，输出 JSON 格式的检查结果。

### 生成检查报告

使用 `generate_detailed_report()` 函数生成详细报告：

```python
from main import generate_detailed_report

report = generate_detailed_report()
print(report)
```

报告会自动保存到配置的 `report_path` 路径。

## 检查报告格式

`generate_detailed_report()` 生成的报告**只包含发现的问题**，不显示正确的配置。报告包含以下部分：

### 1. 检查 Mapper XML 中的 resultMap
详细列出所有 resultMap 配置问题，每个问题都附带修复 prompt。

### 2. 检查 Mapper 接口中的 @Results 注解
检查注解配置问题，提供详细的修复指导。

### 3. 检查 SQL 语句中的列别名
验证列别名与实体字段的匹配情况。

### 4. 检查联合查询字段重复或歧义
识别多表关联查询中的潜在问题。

### 5. 检查特殊类型字段的类型处理器
标记需要自定义 TypeHandler 的复杂类型字段。

### 6. 检查总结
提供统计信息和整体评估。

## 问题级别

- **ERROR**: 严重问题，必须修复
- **WARNING**: 警告，建议尽快处理
- **INFO**: 信息提示，可能需要关注

## 示例输出

```
================================================================================
报告已保存到: D:\Workspace\project\reports\mybatis_check_report.txt

================================================================================
MyBatis 配置检查详细报告
================================================================================

【检查项 1】检查 Mapper XML 中的 resultMap
--------------------------------------------------------------------------------
检查内容：
  - resultMap 的 id 和 type 是否正确
  - 每个 <result> 的 column 属性是否与 SQL 查询列名一致
  - 每个 <result> 的 property 属性是否与实体类字段名一致
  - 嵌套对象的字段映射是否正确

发现 2 个问题：

  1. 问题级别: ERROR
     问题类型: RESULTMAP_PROPERTY
     问题描述: Property "deleteFlag" not found in entity Student
     位置: D:\Workspace\project\src\main\resources\mapper\student\StudentMapper.xml:BaseResultMap
     建议: 检查 Student 实体类是否存在 deleteFlag 字段，或修改 resultMap 中的 property 属性

  Prompt（用于修复此问题）：
  --------------------------------------------------------------------------------
  请修复以下 MyBatis resultMap 配置问题：

  问题级别: ERROR
  问题类型: RESULTMAP_PROPERTY
  问题描述: Property "deleteFlag" not found in entity Student
  位置: D:\Workspace\project\src\main\resources\mapper\student\StudentMapper.xml:BaseResultMap
  建议: 检查 Student 实体类是否存在 deleteFlag 字段，或修改 resultMap 中的 property 属性

  请：
  1. 打开文件: D:\Workspace\project\src\main\resources\mapper\student\StudentMapper.xml:BaseResultMap
  2. 根据问题描述定位问题
  3. 检查 resultMap 的 type 属性是否正确指向实体类
  4. 检查每个 <result> 的 property 属性是否与实体类字段名完全一致（区分大小写）
  5. 检查每个 <result> 的 column 属性是否与 SQL 查询中的列名一致
  6. 提供修复后的代码

【检查项 2】检查 Mapper 接口中的 @Results 注解
--------------------------------------------------------------------------------
检查内容：
  - Mapper 接口方法上的 @Results 或 @ResultMap 注解
  - @Results 数组中每个 @Result 的 column 和 property 是否正确
  - @ResultMap 引用的 resultMap id 是否与 XML 中定义的完全一致

发现 4 个问题：
  ...

================================================================================
检查总结
================================================================================

实体类数量: 142
数据库表数量: 44
ResultMap 数量: 2
Mapper 方法数量: 15

问题统计:
  - 错误 (ERROR): 4
  - 警告 (WARNING): 0
  - 信息 (INFO): 56
  - 总计: 60

⚠️  发现严重问题，请优先处理错误级别的问题！

================================================================================
```

## 依赖项

- Python 3.7+
- mcp>=0.9.0（可选，用于 MCP 服务器模式）

## 安装依赖

```bash
pip install -r requirements.txt
```

## 注意事项

1. 确保配置的路径正确且可访问
2. SQL 文件中的表名和列名会被转换为小写进行匹配
3. 实体类字段名区分大小写
4. 工具会自动递归扫描目录中的所有相关文件
5. 报告只显示发现的问题，不显示正确的配置
6. 报告路径支持绝对路径和相对路径
7. 如果报告目录不存在，工具会自动创建

## 最佳实践

1. 在 CI/CD 流程中集成此工具，自动检查代码质量
2. 定期运行 `generate_detailed_report()` 生成详细报告
3. 优先处理 ERROR 级别的问题
4. 根据报告中的 prompt 指导进行修复
5. 配置多个路径以覆盖所有需要检查的模块
6. 使用绝对路径配置报告输出，便于集成到其他系统

## 常见问题

### Q: 如何检查多个模块的实体类？
A: 在 `entity_paths` 中配置多个路径即可：
```json
{
  "entity_paths": [
    "src/main/java/com/module1/entity",
    "src/main/java/com/module2/entity",
    "src/main/java/com/module3/entity"
  ]
}
```

### Q: 报告文件太大怎么办？
A: 报告只包含发现的问题，如果问题很多，可以：
1. 先修复 ERROR 级别的问题
2. 分模块检查，每个模块单独配置路径
3. 使用 grep 或其他工具过滤特定类型的问题

### Q: 如何忽略某些检查项？
A: 目前不支持忽略特定检查项，所有检查项都会执行。但可以只关注报告中的 ERROR 和 WARNING 级别问题。

## 许可证

MIT License