api-sequence-diagram

根据指定的Java接口（Controller方法/API路径）分析完整调用链路，生成Mermaid时序图，标注关键判断节点、异常处理分支和业务逻辑。当用户要求分析接口调用链路、生成时序图、分析接口流程、查看接口调用关系时使用。

Security Scan

The skill's requirements and instructions are internally consistent with its stated purpose: it describes how to locate Java controller/service/mapper code, trace call chains, and produce Mermaid sequence diagrams without requesting unrelated credentials or installing software.

Purpose & Capability

The name/description (generate sequence diagrams for Java APIs) matches the instructions: locate controller/service/mapper code, follow calls, inspect annotations/SQL, and produce Mermaid output. There are no unrelated environment variables, binaries, or external services required.

Instruction Scope

Instructions rely on workspace code-search helpers (search_symbol, grep_code, read_file) and explicitly instruct reading controllers, services, mapper XML, annotations, and other source files up to 4 layers deep. This stays within the stated purpose, but it necessarily requires full read access to the codebase — so the skill will examine any repository files it can access (which could include secrets unrelated to the API analysis).

Install Mechanism

Instruction-only skill with no install spec and no code files; nothing is written to disk or downloaded. This is the lowest-risk install model.

Credentials

The skill declares no environment variables, credentials, or config paths. The runtime instructions do not request secrets or external service tokens. The only required capability is reading repository/source files, which is appropriate for static code analysis.

Persistence & Privilege

always is false and the skill does not request permanent system presence or modify other skills/config. It uses the platform's normal code-search/read tools; autonomous invocation is allowed by default but not unique to this skill.

Assessment

This skill appears to do what it says — it will read your Java source files, mapper XML, and annotations to trace call chains and build Mermaid diagrams. Before installing or running it, confirm you are comfortable granting the agent read access to the repository (the skill could encounter any sensitive data present in code or config). Also review generated findings for correctness (the skill interprets business semantics automatically and may mislabel intent). If you want to limit exposure, run it on a sanitized or sample codebase rather than a repo containing secrets or unrelated proprietary data.

API 接口时序图生成

使用场景

当用户指定一个接口（Controller 方法名、API 路径、或 Service 方法名），自动追踪完整调用链路并生成 Mermaid 时序图。

工作流程

Step 1: 定位目标接口

用户可能提供以下任一信息：

• API 路径：如 /api/v1/dossier/selectDossierVolume
• Controller 方法名：如 selectDossierVolume
• Controller 类名 + 方法名：如 EleDossierController#selectDossierVolume
• Service 方法名：需反向查找调用它的 Controller

操作：

1. 使用 search_symbol 定位目标 Controller 方法，必要时结合 grep_code 搜索路径注解
2. 读取 Controller 完整代码，确认 HTTP 方法和请求路径（从 @RequestMapping、@PostMapping 等注解或对应 API 接口定义获取）
3. 同时读取对应的 API 接口定义文件（ele-archives-api 模块），获取注解和路径信息

Step 2: 追踪调用链路

从 Controller 方法开始，逐层深入追踪：

Controller → Service(接口) → ServiceImpl(实现) → DAO/Mapper → SQL
                                                → 外部调用(Feign/MQ/Redis)

对每一层执行：

1. 用 search_symbol（带 relation: calls）查找被调用方法
2. 用 read_file 读取方法完整实现代码
3. 记录：
   • 方法签名、所在类、行号范围
   • 入参和返回值的业务语义（不仅是类型名）
   • 调用的下游方法列表
   • 关键判断节点（if/else、switch、三元表达式）及其业务含义
   • 异常处理（try-catch、throw）
   • 注解信息（@Transactional、@Async、@TLogAspect 等）
   • 循环处理（for/while 中的批量操作）
4. 对每个下游方法递归追踪（最多 4 层）

必须关注的调用类型：

• @Autowired 注入的 Service、DAO、工具类
• MyBatis Mapper 接口 → 对应 XML 中的 SQL
• Feign 远程调用接口
• MQ 消息发送（如 AppMessageSender、publisher 包下的类）
• Redis/缓存操作
• 事件发布（ApplicationEventPublisher）

追踪终止条件：

• 到达 Mapper 接口方法（尝试查找对应 XML 中 SQL）
• 到达 Feign 接口方法
• 到达 JDK/Spring 框架方法
• 通用工具方法（如 MessageUtils、BeanUtils、PageHelper）仅标注不展开

Step 3: 生成 Mermaid 时序图

参与者命名：

层级	命名规则	示例
客户端	Client	Client
Controller	类名简称	Controller
Service	业务名+Service	DossierService
Mapper/DAO	业务名+Mapper	DossierMapper
数据库	DB	DB
缓存	Redis	Redis
消息队列	MQ	MQ
外部服务	服务名	MoiraiService

箭头语义：

• 同步调用：->> (实线)
• 同步返回：-->> (虚线)
• 异步调用：使用 Note right of 标注"异步"

分支与循环：

• 条件分支：alt 条件A业务含义 / else 条件B业务含义 / end
• 循环：loop 循环业务含义
• 可选：opt 可选条件业务含义
• 并行：par 并行任务描述
• 关键判断用 Note over 参与者: 判断说明 标注

模板：

sequenceDiagram
    participant Client
    participant Controller
    participant Service
    participant Mapper
    participant DB

    Client->>Controller: POST /api/path (RequestDto)
    Controller->>Controller: 参数预处理（业务含义说明）
    Controller->>Service: methodName(params)

    Note over Service: 关键变量 xxx 的业务含义说明

    alt 条件成立（用业务语言描述）
        Service->>Mapper: queryMethod(params)
        Mapper->>DB: SQL操作描述
        DB-->>Mapper: 结果集
        Mapper-->>Service: List<Entity>
        Note over Service: 对结果进行 xxx 业务处理
    else 条件不成立（用业务语言描述）
        Service-->>Controller: 返回错误/空结果
    end

    opt 存在某可选条件时
        Service->>Mapper: updateMethod(params)
        Mapper->>DB: UPDATE ...
    end

    Service-->>Controller: 处理结果
    Controller-->>Client: BWJsonResult<Vo>

Step 4: 输出关键判断节点表

在时序图之后，以表格形式列出所有关键判断节点：

序号	位置（类#方法 行号）	判断条件（代码）	业务含义（自然语言）	True 分支处理	False 分支处理
1	ServiceImpl#method L45	if (status == null)	校验归档状态是否存在	抛出异常：状态不能为空	继续后续处理
2	ServiceImpl#method L78	if ("6".equals(dataState))	判断是否为已归档状态	过滤未接收的记录	保持原始状态不变

要求：

• "业务含义"列必须用业务语言解释，不能仅复述代码
• 对于关键 boolean 变量或表达式，优先说明其语义和判断意图

Step 5: 输出调用链路详情

按层级列出每个方法：

### 调用链路

1. **Controller 层**
   - `EleDossierController#selectDossierVolume`
   - 职责：接收请求，参数预处理，调用 Service
   - 关键逻辑：将逗号分隔的分类ID拆分为列表

2. **Service 层**
   - `EleDossierServiceImpl#selectDossierVolume`
   - 职责：核心业务逻辑处理
   - 关键逻辑：分页查询、权限过滤
   - 事务：无 / @Transactional(propagation=REQUIRED)

3. **DAO 层**
   - `EleDossierMapper#selectDossierVolume`
   - 对应 SQL：SELECT ... FROM ... WHERE ...

Step 6: 补充分析

根据实际代码情况，选择性输出以下内容：

事务边界

• 标注 @Transactional 覆盖范围及传播行为
• 如果存在嵌套事务，说明事务传播链

异常处理链路

• 各层的 try-catch 范围
• 自定义异常类型及其触发条件
• 全局异常处理器是否兜底

性能关注点（如发现则标注）

• N+1 查询
• 循环内数据库调用
• 未分页的全量查询
• 大对象序列化

外部依赖

• 列出所有外部系统调用及其用途

完整输出格式

## 接口概述

| 属性 | 值 |
|------|-----|
| 接口路径 | POST /api/xxx |
| 所属模块 | xxx模块 |
| Controller | XxxController#methodName |
| 功能描述 | 一句话描述接口功能 |

## 时序图

（Mermaid sequenceDiagram 代码块）

## 关键判断节点

（表格）

## 调用链路详情

（分层列出）

## 补充分析

### 事务边界
（如有）

### 异常处理链路
（如有）

### 性能关注点
（如有）

### 外部依赖
（如有）

特殊情况处理

1. 接口调用链过长：先生成主链路概览图，再按模块拆分子链路图
2. 存在异步调用：在时序图中用 Note 标注异步边界，单独说明异步处理流程
3. 存在回调/监听：追踪事件发布后的 @EventListener 或 subscriber 处理逻辑
4. 代码中有 TODO/FIXME：在补充分析中提示
5. 找不到实现类：明确告知用户，标注为"未找到实现，可能为远程调用或动态代理"