Java Controller 调用链路分析 Skill

简介

本技能用于分析 Java 微服务项目中 Controller 层的完整调用链路，能够自动追溯到 Service、Mapper、Repository 层，并提取完整的 SQL 语句。最终生成结构化的 JSON 文件，便于 API 文档生成、代码审计或架构理解。

适用场景

• 需要快速了解某个 Controller 接口背后的业务逻辑和数据流向
• 自动化生成 API 调用链路文档
• 审计 SQL 语句或分析数据库访问模式
• 批量分析整个模块的接口实现细节

输入参数

输出

在指定的输出目录下生成一个以 Controller 类名命名的 JSON 文件（例如 TDrugdictController.json），文件内容遵循固定的 JSON 结构（详见下文）。该文件包含了从 Controller 方法到 Service 实现、再到 Mapper/Repository 以及最终 SQL 语句的完整调用链路信息。

工作流程

1. 读取 Controller 文件

• 解析 Java 源文件，提取：
  • 类名、包名
  • 类级别的 @RequestMapping 路径
  • 类级别的 @Api 或 @ApiOperation 注解（接口描述）
  • 每个方法的 HTTP 方法注解（@GetMapping、@PostMapping 等）及路径
  • 方法参数列表（包括参数名、类型、是否必填、@ApiParam 描述等）

2. 追溯 Service 实现类

• 根据 Controller 中注入的 Service 字段类型，定位对应的 Service 接口
• 查找接口的实现类 Search(pattern: "implements 接口名称", path: "项目地址")
• 读取实现类，识别每个方法内部调用的 Mapper 或 Repository 方法
• 读取实现类，识别每个方法内部方法（该方法可能存在Mapper 或 Repository 方法调用）
• 根据代码，输出方法介绍

3. 追溯 Mapper 层（MyBatis）

• 查找与 Service 中调用的 Mapper 接口（通常在 mapper/ 目录下）
• 定位对应的 MyBatis XML 文件（通常在 src/main/resources/mapper/ 目录下，命名与接口相同）
• 提取 XML 中对应方法的 SQL 语句，并解析出表名、查询条件、SQL 类型（select/insert/update/delete）

4. 追溯 Repository 层（Spring Data JPA）

• 查找 Service 中调用的 Repository 接口（通常在 repository/ 目录下）
• 提取方法上的 @Query 注解中的 JPQL 或原生 SQL；如果方法名符合命名规范，则根据方法名解析 SQL（可选）

5. 生成 JSON 输出

按照预定义的 JSON 结构，将上述信息组合并写入文件。

输出 JSON 结构

{
  "module": "模块名",                        // 根据包名自动推断，例如 "itemSupply"
  "controller": {
    "className": "Controller类名",
    "filePath": "Controller源文件路径",
    "requestMapping": "/请求路径",           // 类级别的 @RequestMapping
    "description": "Controller描述",         // @Api 注解的 value 或 description
    "methods": [
      {
        "name": "方法名",
        "httpMethod": "GET/POST/PUT/DELETE",
        "url": "/完整URL",                    // 类路径 + 方法路径
        "description": "接口描述",             // @ApiOperation 的值
        "controllerFilePath": "Controller.java:行号", // 源文件位置
        "params": [
          {
            "name": "参数名",
            "type": "类型",
            "required": true/false,
            "description": "描述"             // @ApiParam 的值
          }
        ],
        "service": [{                         // 可能多个
          "className": "ServiceImpl类名",
          "filePath": "ServiceImpl源文件路径",
          "method": "方法名",                  // Service 中调用的方法
          "steps": ["业务步骤描述"],            // 可选，可提取方法中的业务逻辑注释
          "mapper": [{                          // 如果调用的是 MyBatis Mapper,可能的多个
            "className": "Mapper接口类名",
            "filePath": "Mapper接口源文件路径",
            "method": "方法名",
            "xmlFilePath": "Mapper XML文件路径",
            "sql": {
              "id": "SQL ID",
              "table": "表名",
              "statement": "完整SQL语句",
              "conditions": ["查询条件"]
            }
          }],
          "repository": [{                       // 如果调用的是 JPA Repository,可能的多个
            "className": "Repository接口类名",
            "filePath": "Repository源文件路径",
            "method": "方法名",
            "framework": "Spring Data JPA",
            "sql": "JPQL或native SQL"
          }]
        }]
      }
    ]
  }
}

注意事项

• 项目根目录：本技能默认项目根路径为当前目录，所有文件路径均相对于此目录。如需修改，请在调用前调整。
• 输出目录：如未指定 outputPath，默认输出到 docs/api_analysis/。
• 批量分析：本技能一次只分析一个 Controller；若需批量分析，请通过循环调用本技能，每次传入不同的 controllerPath。
• 依赖假设：代码结构需遵循常见的 Spring Boot + MyBatis / JPA 的包命名规范（如 service.impl、mapper、repository、resources/mapper）。若项目结构特殊，分析可能不完整。