核心改動影響範圍與依賴追蹤 · Codegraph

為什麼需要影響範圍分析？

在軟體重構或功能升級時，最常見的事故就是「改 A 壞 B」。當你打算修改一個通用的底層 API 介面或公用 Utility 函數時，如果沒有清晰的依賴視角，很容易遺漏某個不起眼的上游呼叫端，從而引入 Breaking Changes。

改動影響範圍分析工作流 (Dependency Impact Analysis Flow) 旨在利用 Codegraph 的單一呼叫依賴鏈檢索能力，在開始重構前建立一個清晰的「安全防禦圈」。

步驟詳解與實戰指令

    ┌──────────────────────┐
    │  1. 核心探索 (Symbol) │  <-- 執行 codegraph explore <symbol>
    └──────────┬───────────┘
               │ 
               ▼
    ┌──────────────────────┐
    │  2. 梳理上游呼叫者   │  <-- 檢視 Inbound Callers
    └──────────┬───────────┘
               │
               ▼
    ┌──────────────────────┐
    │  3. 風險評估與定級   │  <-- 判斷是否為 Breaking Change
    └──────────┬───────────┘
               │
               ▼
    ┌──────────────────────┐
    │  4. 分批漸進重構     │  <-- 配合 Git 分批修改並驗證
    └──────────────────────┘

步驟 1：探索目標 Symbol 核心結構

對你打算修改的核心類別或方法，使用 codegraph explore 進行關係剖析。

實戰指令：
```
codegraph explore "updateUserProfile"
```
分析內容：
- 檢視 updateUserProfile 的參數定義與返回結構。
- 了解其底層呼叫的出站依賴（例如它內部相依於哪些資料庫方法）。

步驟 2：梳理所有上游呼叫者 (Inbound Callers)

在 Codegraph 返回的資訊中，重點聚焦於 Inbound Callers 區塊。這裡列出了所有引用了當前 Symbol 的檔案名稱、方法名稱以及調用所在的精確行數。

影響指標評估：
- 呼叫次數：如果呼叫次數少於 3 次，可直接一次性修改；若多於 10 次，則必須制定分批重構計畫。
- 業務跨度：檢查上游呼叫者是否分佈在不同的專案或服務中（例如：同時被客戶端 UI、後端 API 控制器與背景腳本呼叫）。

步驟 3：變更風險等級劃分

依據上游呼叫的複雜度與變更方式，將風險分為以下等級並採取對應防禦措施：

風險等級	變更特徵	建議防禦策略
低風險 (Low)	僅優化方法內部邏輯或效能，簽章與回傳型別完全不變	執行單元測試驗證內部邏輯即可，無需修改上游。
中風險 (Medium)	為方法新增參數，但該參數為「可選參數」或有預設值	確保預設值符合預期，測試舊版上游是否依然相容。
高風險 (High)	修改方法名稱、刪除參數、或修改必填參數的型別與回傳 Schema	必須採取「向後相容過渡方案」：保留舊方法，新增 v2 版本，分批將上游轉移後再刪除舊代碼。

步驟 4：執行漸進式重構與測試驗證

針對高風險的變更，按照 Codegraph 整理出的上游依賴清單，執行分批修改：

建立過渡方法：在原類別中新增一個後綴為 V2 的新方法，將新業務邏輯寫在 V2 內，並讓舊方法內部包裝 V2（保證相容性）。
逐步轉移上游：分批修改上游呼叫者，將其對舊方法的呼叫改為 V2，每改一批就提交一個 commit。
安全移除舊代碼：當 Codegraph 的 Inbound Callers 清單顯示舊方法的呼叫次數歸零時，即可安全地將舊方法自 codebase 中刪除。