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 時序圖

參與者命名：

箭頭語義： - 同步呼叫：->> (實線) - 同步返回：-->> (虛線) - 非同步呼叫：使用 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: 輸出關鍵判斷節點表

在時序圖之後，以表格形式列出所有關鍵判斷節點：

要求： - "業務含義"列必須用業務語言解釋，不能僅複述程式碼 - 對於關鍵 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: 補充分析

根據實際程式碼情況，選擇性輸出以下內容：

7w4.net提供免費和付費技能下載。

事務邊界

• 標註 @Transactional 覆蓋範圍及傳播行為
• 如果存在巢狀事務，說明事務傳播鏈

異常處理鏈路

• 各層的 try-catch 範圍
• 自定義異常型別及其觸發條件
• 全域性異常處理器是否兜底

效能關注點（如發現則標註）

• N+1 查詢
• 迴圈內資料庫呼叫
• 未分頁的全量查詢
• 大物件序列化

外部依賴

• 列出所有外部系統呼叫及其用途

完整輸出格式

## 介面概述

| 屬性 | 值 |
|------|-----|
| 介面路徑 | POST /api/xxx |
| 所屬模組 | xxx模組 |
| Controller | XxxController#methodName |
| 功能描述 | 一句話描述介面功能 |

## 時序圖

（Mermaid sequenceDiagram 程式碼塊）

## 關鍵判斷節點

（表格）

## 呼叫鏈路詳情

（分層列出）

## 補充分析

### 事務邊界
（如有）

### 異常處理鏈路
（如有）

### 效能關注點
（如有）

### 外部依賴
（如有）

特殊情況處理

1. 介面呼叫鏈過長：先生成主鏈路概覽圖，再按模組拆分子鏈路圖
2. 存在非同步呼叫：在時序圖中用 Note 標註非同步邊界，單獨說明非同步處理流程
3. 存在回撥/監聽：追蹤事件釋出後的 @EventListener 或 subscriber 處理邏輯
4. 程式碼中有 TODO/FIXME：在補充分析中提示
5. 找不到實現類：明確告知使用者，標註為"未找到實現，可能為遠端呼叫或動態代理"

這是一個功能定位明確的 Skill，專注於介面呼叫鏈路分析和時序圖生成。文件規範詳盡，流程清晰，模板示例實用，對關鍵判斷節點和業務語義的處理較為深入。但目前主要適用於 Java Spring 技術棧，對其他技術棧支援有限，在複雜場景下的靈活性也有提升空間。總體來說質量良好，但適用範圍需要進一步擴充套件。