舊系統代表許多現代企業的骨幹。它們包含數十年的商業邏輯、關鍵的資料處理，以及新綠地專案往往無法立即複製的複雜依賴關係。然而，隨著時間推移，文件逐漸遺失，知識隨著退休員工一同流失，原始架構的設計意圖也變得模糊。這種衰敗狀態在現代化過程中、新工程師的融入，或僅僅是日常運作維護時，都會帶來重大風險。
C4模型提供了一種結構化的軟體架構文件方法，可從高階背景層級逐步細化至程式碼層級。雖然常與新開發專案相關聯，但其分層方法特別適合理清現有系統的複雜性。透過將龐大的單體系統分解為可理解的「背景」、「容器」、「組件」與「程式碼」層級，團隊能在無需立即重寫所有內容的情況下，重新獲得清晰的視角。
🧐 為何舊系統需要更好的文件
舊的程式碼庫經常面臨所謂的「架構偏移」問題。經過多年補丁、緊急修復與功能新增，系統的演變方式遠超出原始架構師的預期。若缺乏清晰的圖譜，開發人員會猶豫是否觸碰關鍵區域，擔心產生未預期的副作用。這種猶豫不決導致技術負債累積、功能交付速度變慢，並過度依賴少數掌握知識的關鍵人員。
文件不僅僅是畫框框；它本質上是一種溝通。一個明確的架構圖能促進利益相關者、開發人員與業務負責人之間的討論。對於舊系統環境而言，這種溝通至關重要，因為錯誤的成本極高。當你對一個已運行十年的系統進行變更時，理解資料流與依賴關係的邊界是絕對不可妥協的。
將C4模型應用於舊系統的主要動機包括：
- 知識傳遞： 透過可視化結構，減少對部落知識的依賴。
- 風險減緩： 在重構前識別單點故障或緊密耦合的模組。
- 新人融入效率： 協助新進人員比閱讀原始程式碼更快地理解系統全貌。
- 現代化規劃： 建立基準，以規劃遷移至微服務或雲原生環境。
- 合規與審計： 提供系統邊界與資料處理的證據，以符合法規要求。
📐 理解C4模型的層級
C4模型將文件組織成四個不同抽象層級。每一層都針對特定的受眾，並回答特定的問題。在應用於舊系統時，並不需要立即創建每一張圖表。你可以從價值最高的層級開始，逐步向下推進。
1. 系統背景圖（第1層）
這是宏觀視角。它將整個系統呈現為一個單一框體，並顯示與其互動的人員或外部系統。對於舊系統應用，這有助於回答：「我們正在觀察的範圍邊界是什麼？」以及「誰依賴於這個系統？」
舊系統背景中常見的元素包括：
- 使用者（內部員工、客戶、合作夥伴）。
- 外部資料庫（ERP系統、CRM平台）。
- 舊的主機系統或中介軟體。
- 通訊協定（HTTP、SOAP、專有API）。
2. 容器圖（第2層）
容器代表獨立的可部署單元。在舊系統環境中，這可能是一個編譯後的可執行檔、WAR檔案、資料庫、伺服器端程序或前端應用程式。此層級回答的問題是：「系統的構建模組是什麼？」
舊系統經常模糊組件與容器之間的界線。單體應用程式可能是一個大型容器，而現代化版本則會將其拆分成較小的服務。識別這些邊界有助於規劃系統拆解策略。
3. 組件圖（第3層）
組件是容器內部的構建模塊。它們代表功能的邏輯分組，例如「支付處理模塊」或「用戶身份驗證服務」。此層級對於遺留代碼至關重要，因為它揭示了內部邏輯，而不會陷入特定的方法簽名或類名細節中。
專注於這些組件的職責。資料是如何在它們之間流動的？它們公開了哪些介面？
4. 程式碼圖示（第4層）
程式碼圖示顯示類別與介面之間的關係。這通常是由原始碼自動生成的。雖然在高階架構審查中較不常見，但對於深入探討需要重構的特定遺留模組非常有用。
🛠️ 為現有程式碼庫適應C4模型
將C4模型應用於新專案相當直接，因為你在建造房屋之前就設計好了盒子。但應用於遺留系統時，則像是在有人仍住在裡面的情況下逆向工程一棟建築。你必須小心，以免在收集資訊時打擾到正常運作。
從上下文開始
首先從訪談關鍵利益相關者開始。詢問系統支援的業務功能。將這些功能映射到外部系統。如果系統處理薪資，誰提供員工資料？最終報告送往何處？這種高階視角將文件的重點建立在業務價值上，而非技術實現。
映射容器
對於遺留系統，識別容器通常需要檢視部署資產。請尋找：
- 定義端點的設定檔。
- 打包應用程式的建構指令碼。
- 顯示服務啟動順序的執行時期日誌。
- 網路流量分析，以了解哪些服務彼此通訊。
不要假設原始碼中的每個資料夾都是一個容器。容器是一個可部署的單元。有時，單一的遺留JAR檔包含了本應在未來狀態中邏輯上分離為多個容器的邏輯。
組件提取
這是遺留分析中最耗時的部分。你本質上是在閱讀程式碼以理解其意圖。請尋找：
- 套件名稱與目錄結構。
- 介面定義與抽象類別。
- 資料庫結構的關係。
- API端點及其請求/回應結構。
將相關功能歸為一組。如果你發現五個類別都處理「電子郵件通知」，它們很可能屬於一個稱為「通知服務」的組件。這種抽象隱藏了實作上的雜訊，專注於行為。
📋 分步實施計畫
在遺留環境中實施C4需要分階段的方法。試圖一次性記錄所有內容很可能會導致專案停滯。請使用以下工作流程以確保穩步推進。
| 階段 | 關注領域 | 關鍵活動 | 輸出 |
|---|---|---|---|
| 1 | 探索 | 訪談利害關係人並檢視部署設定 | 系統上下文圖 |
| 2 | 邊界定義 | 識別可部署單元與資料儲存 | 容器圖 |
| 3 | 邏輯分析 | 檢視原始碼以辨識功能群組 | 元件圖 |
| 4 | 細部調整 | 與開發人員核對圖表並進行更新 | 定稿的架構文件 |
第一階段：探索
收集現有的文件，即使已過時。與「記得的人」對談。詢問整合相關資訊。草擬一份上下文圖的粗略草圖。此圖應為高階且所有相關方都能接受的內容。
第二階段：邊界定義
繪製實體與邏輯邊界。區分應用程式邏輯與資料儲存。識別舊系統與第三方服務互動的位置。這通常能揭露未被記錄的隱藏依賴關係。
第三階段：邏輯分析
深入探討容器。識別核心模組。例如，在庫存系統中，不同的元件可能包括「庫存管理」、「訂單處理」與「報表」。若可使用程式碼分析工具，應加以利用，但對於複雜邏輯，仍應優先進行手動審查。
第四階段：細部調整
向團隊展示圖表，並請提出修正意見。這是否符合開發人員的腦中模型？若圖表顯示的流程實際上不存在，應立即更新。目標是準確性，而非藝術美感。
⚠️ 常見陷阱與避免方法
與舊系統合作會帶來獨特的挑戰。意識到這些陷阱可節省大量時間與精力。
陷阱一：「完美圖表」症候群
試圖為每個邊界情況創造100%準確的圖表是一種陷阱。舊系統本來就雜亂無章。應專注於正常流程與關鍵流程。若圖表有80%的準確度，仍遠勝於沒有文件。
陷阱二：忽略原始碼
文件必須建立在現實基礎上。若圖表顯示元件A與元件B通訊，但原始碼中並無任何網路呼叫，則存在矛盾。應以實際原始碼庫驗證各項說法。有時架構已與書面設計產生顯著偏離。
陷阱三：結構過度設計
不要因為微服務架構流行，就硬將其套用在單體系統上。若舊系統以單體方式運作，就應將其記錄為單體。使用C4模型描述現實狀況，而非理想願景。若真想轉向微服務，應將目標狀態以獨立圖表記錄。
陷阱4：過時的文件
文件的衰減速度比程式碼還快。如果系統有變更，理想上應該同步更新圖表。建立一個輕量級的流程來處理此事。例如，只有當變更影響到主要組件邊界時，才要求更新圖表。
🤝 將文件整合至工作流程中
文件經常被視為額外負擔。為了使其可持續，應將其整合至現有的工程工作流程中。這能確保圖表不會只建立一次就遭遺忘。
- 程式碼審查：在影響組件邊界的拉取請求中包含架構圖。這迫使作者思考變更的影響。
- 迭代規劃：在迭代期間分配時間用於文件更新。將圖表維護視為一項任務，而非可有可無的額外工作。
- 新成員培訓：將圖表作為新工程師的首選資源。如果他們發現錯誤，就讓他們在培訓任務中一併修正。
- 架構決策紀錄：將圖表與決策連結。當決定整合新服務時，立即更新上下文圖。
🔄 長期維護圖表
在舊系統環境中，維護是C4模型最困難的部分。系統不斷變動。以下是一些策略，可在不給團隊帶來過大負擔的情況下，保持文件的相關性。
盡可能自動化
針對程式碼層級的圖表，使用自動化生成工具。這些工具可直接從原始碼中提取類別關係。雖然它們可能不美觀，但永遠準確。應將其用於深入的技術審查，而非高階溝通。
使用版本控制管理圖表
將圖表與原始碼儲存在同一個程式庫中。這能確保文件版本與程式碼版本一致。使用分支策略，在合併至主文件分支前先草擬變更。
定期審查
每季安排一次架構審查。指派資深工程師走查圖表，並與系統當前狀態進行核對。這是一個發現先前未察覺技術負債的良機。
📈 衡量成功
如何判斷將C4模型應用於你的舊系統是否有效？請留意以下指標：
- 更快的培訓上手：新成員能更快達到生產力水平。
- 錯誤減少：由於依賴關係明確，部署期間發生的回退問題減少。
- 更好的規劃：現代化專案的時間表與資源估算更為準確。
- 活躍使用：開發人員在會議與故障排除時會參考圖表。
- 明確的界限：團隊可以識別系統中哪些部分由他們負責，哪些部分不是。
將C4模型應用於遺留系統，並非為了創造過去的博物館，而是為了建立一個活生生的地圖，引導未來的發展。透過理解當前的結構，你可以做出明智的決策，判斷在哪些地方投資重構，哪些地方引入新服務，以及哪些地方穩定核心。
這個過程需要耐心與紀律。它包括與人對話、閱讀程式碼以及繪製框圖。但結果是整個組織對系統達成共識，從而有信心地向前推進。無論你是規劃全面遷移，還是僅僅想維持系統運作，清晰的架構文件都是根本性的資產。
從小處著手。選擇一個容器，繪製其組件，分享它，不斷迭代。隨著時間推移，圖像會變得更清晰，遺留系統也將從一個難以理解的負擔，轉變為可管理的資產。
