Mybatis

Бесплатно

A MyBatis configuration validation tool that checks for consistency between Java entity fields and database columns across XML maps, annotations, and SQL querie

автор: Hale2000

GitHub

Описание

A MyBatis configuration validation tool that checks for consistency between Java entity fields and database columns across XML maps, annotations, and SQL queries. It provides detailed diagnostic reports and actionable prompts to help developers identify and fix mapping errors and configuration issues.

README

这是一个 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

Как установить

Добавь это в claude_desktop_config.json и перезапусти Claude Desktop.

{
  "mcpServers": {
    "mcp-mybatis": {
      "command": "npx",
      "args": []
    }
  }
}