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 文件，配置以下路径：
{
"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 服务器运行
python main.py
工具会自动加载 config.json 配置，并启动 MCP 服务器。
独立模式运行（用于测试）
如果未安装 mcp 包，工具会以独立模式运行，输出 JSON 格式的检查结果。
生成检查报告
使用 generate_detailed_report() 函数生成详细报告：
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 服务器模式）
安装依赖
pip install -r requirements.txt
注意事项
- 确保配置的路径正确且可访问
- SQL 文件中的表名和列名会被转换为小写进行匹配
- 实体类字段名区分大小写
- 工具会自动递归扫描目录中的所有相关文件
- 报告只显示发现的问题，不显示正确的配置
- 报告路径支持绝对路径和相对路径
- 如果报告目录不存在，工具会自动创建
最佳实践
- 在 CI/CD 流程中集成此工具，自动检查代码质量
- 定期运行
generate_detailed_report()生成详细报告 - 优先处理 ERROR 级别的问题
- 根据报告中的 prompt 指导进行修复
- 配置多个路径以覆盖所有需要检查的模块
- 使用绝对路径配置报告输出，便于集成到其他系统
常见问题
Q: 如何检查多个模块的实体类？
A: 在 entity_paths 中配置多个路径即可：
{
"entity_paths": [
"src/main/java/com/module1/entity",
"src/main/java/com/module2/entity",
"src/main/java/com/module3/entity"
]
}
Q: 报告文件太大怎么办？
A: 报告只包含发现的问题，如果问题很多，可以：
- 先修复 ERROR 级别的问题
- 分模块检查，每个模块单独配置路径
- 使用 grep 或其他工具过滤特定类型的问题
Q: 如何忽略某些检查项？
A: 目前不支持忽略特定检查项，所有检查项都会执行。但可以只关注报告中的 ERROR 和 WARNING 级别问题。
许可证
MIT License