api-sequence-diagram

by lijie012

Install this Skill

curl -fsSL -o api-sequence-diagram.zip https://skill.seembox.com/api/v1/skills/api-sequence-diagram/download && unzip api-sequence-diagram.zip

Download api-sequence-diagram.zip

SKILL.md About

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

# 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. **找不到实现类**：明确告知用户，标注为"未找到实现，可能为远程调用或动态代理"

_meta.json Metadata

{
  "ownerId": "kn734b4jxrka0pgegbar4cm4y984c3jx",
  "publishedAt": 1775535023207,
  "slug": "api-sequence-diagram",
  "version": "1.0.0"
}