組合結構圖（CSD）是一種專門的 UML 圖形，旨在展示分類器的內部結構及其各部分之間的互動。雖然它們能提供系統架構的細粒度視圖，但創建這些圖形需要精確性。在組合、連接或定義上的任何單一錯誤，都可能導致開發階段出現重大誤解。
許多工程師將這些圖形視為類別圖的選修延伸，但它們具有獨特的目的：揭示複雜物件的拓撲結構。當設計得當時，它們能釐清各組件如何協作以履行職責；當設計不佳時，則會引入模糊性，導致實施停滯。
本指南探討了創建這些圖形時常見的七種錯誤。透過識別這些陷阱，您可以確保您的架構文件保持準確且可執行。
1. 混淆組件與類別 🏷️
最常見的錯誤是將組合部分單純視為類別。雖然 CSD 中的組件在技術上屬於分類器，但其角色與類別圖中的標準類別有本質上的不同。
- 類別代表單一單元內部的資料結構與邏輯。
- 組件代表可獨立部署的模組化實現單元。
當您在組合結構內部繪製一個部分時，您正在定義一個具有自身生命週期與介面合約的物理或邏輯單元。如果您僅使用類別屬性與方法來定義部分，而未指定連接埠或介面，您將失去結構脈絡。
為何這很重要：
- 它會模糊部署邊界。
- 它會隱藏互動協定。
- 它會導致程式碼生成時的混淆。
修正策略：
- 確保每個部分都代表一個獨立的工作單元。
- 驗證各部分是否已定義用於溝通的介面。
- 區分內部實現細節與外部合約。
2. 忽略連接埠與介面 🚪
組合結構圖本質上是一份互動藍圖。若無連接埠與介面，組件的內部連接將不可見。
許多設計者直接在部分之間繪製連接，卻未定義入口與出口點。這在 UML 語義上是技術上不正確的。連接必須附著於連接埠，而連接埠必須由介面類型化。
常見錯誤：
- 將一個部分直接連接到另一個部分。
- 使用無箭頭的線條來指示方向。
- 未指定介面是提供的（棒棒糖符號）還是需要的（插座符號）。
對架構的影響：
若無明確的連接埠，圖形便無法顯示相依性管理。這使得無法判斷哪個部分依賴哪個服務。這種模糊性會在軟體開發生命週期的後期導致耦合問題。
最佳實踐：
- 務必為每個互動點定義一個連接埠。
- 指定端口上的介面類型。
- 使用提供的和所需的介面標記來顯示相依性的流向。
3. 過度複雜化內部結構 🕸️
細節固然重要，但過度細節會使圖表失去效用。常見的錯誤是試圖在單一組合結構圖中記錄元件的整個內部邏輯。
當組合結構變得過於密集時，讀者將無法追蹤資料或控制的流向。此圖表的目的是結構性的，而非行為性的。如果您發現自己正在元件內部添加狀態轉換或活動流程，則很可能已超出組合結構圖（CSD）的範圍。
過度複雜化的跡象：
- 單一分類器內部包含超過 5 至 7 個元件。
- 元件區格內包含密集的文本描述。
- 多重嵌套的組合結構。
修正策略：
- 將大型元件拆解為子組合結構。
- 專注於元件之間的關係，而非內部程式碼。
- 針對行為使用獨立的圖表（狀態機圖或活動圖）。
4. 忽視連接的語義 🧵
連接器定義資料在元件之間的流向。然而，這些連接的語義常被忽視。單純的線條無法傳達足夠關於關聯類型的資訊。
在組合結構中，您必須區分以下幾種情況：
- 關聯：一種結構關係。
- 相依性：一種使用關係。
- 聚合：一種共享所有權關係。
表格：連接器類型
| 連接器類型 | 含義 | 視覺指示器 |
|---|---|---|
| 關聯 | 元件之間存在結構關係 | 普通線條 |
| 相依性 | 一個部分使用另一個部分 | 虛線箭頭 |
| 組合 | 部分隨整體而消亡 | 實心菱形 |
| 聚合 | 部分可以獨立存在 | 空心菱形 |
為何語意至關重要：
錯誤的連接符號暗示了錯誤的生命週期管理。若您在需要聚合的位置使用了組合菱形，則暗示該部分無法獨立於整體而存在。這將限制架構的靈活性。
5. 不一致的命名規範 📝
可讀性取決於術語的一致性。一個常見的疏忽是在圖表與程式碼庫或其他 UML 工件之間混用命名風格。
常見的不一致之處：
- 對某些部分使用駝峰命名法，對其他部分使用蛇形命名法。
- 以實現類別的名稱來標記部分，而非邏輯角色。
- 使用未在別處定義的縮寫。
對協作的影响：
當開發人員查看圖表以理解系統時，他們期望看到熟悉的術語。如果圖表顯示「PaymentProcessor” 但程式碼中卻是「PayService“，所需的心理轉換會造成摩擦。
標準化規則：
- 為所有部分採用嚴格的命名規範。
- 確保部分名稱反映其功能，而非檔案名稱。
- 保持名稱與領域模型一致。
6. 誤用部分生命週期（組合 vs 聚合）⚖️
整體與其部分之間的關係決定了生命週期。當設計者混淆組合與聚合時，會發生關鍵性錯誤。
組合：部分若無整體則無意義。若整體被銷毀，部分亦隨之銷毀。範例：一個「房屋 及其 門.
聚合： 該部件可以獨立存在。範例：一個 團隊 及其 成員.
為何此區分至關重要：
- 它影響記憶體管理策略。
- 它影響資料庫持久化邏輯。
- 它定義了錯誤處理的邊界。
修正：
檢視每個部件的擁有權規則。詢問：「若主要組合體被移除，此部件是否仍能存在？」若答案為是，請使用聚合；若為否，請使用組合。
7. 未能顯示部件內的行為 🎭
組合結構圖專注於結構，但並非孤立存在。設計者常未能將結構與驅動該結構的行為連結起來。
雖然不應在部件內繪製完整的活動流程，但應標示該部件是否具有影響組合體的內部狀態或操作。
應包含：
- 對組合體公開的操作。
- 與組合體功能相關的狀態變更。
- 部件之間傳遞的信號。
應排除：
- 完整的呼叫方法序列。
- 詳細的演算法邏輯。
- 與外部系統的互動（除非與該部件相關）。
最佳實踐：
使用標記或標籤來標示該部件是否包含重要的行為邏輯。這向讀者表明該部件不僅僅是資料容器。
比較：組合結構圖與類別圖 📊
為了確保清晰，了解何時使用組合結構圖與標準類別圖至關重要。兩者不可互換。
| 功能 | 組合結構圖 | 類別圖 |
|---|---|---|
| 焦點 | 分類器的內部結構 | 類別之間的關係 |
| 細粒度 | 組件、端口、連接器 | 屬性、方法、關聯 |
| 部署視圖 | 可暗示部署 | 僅限邏輯視圖 |
| 複雜度 | 高（適用於複雜物件） | 中等（標準建模） |
| 用途 | 組件導向架構 | 物件導向設計 |
驗證檢查清單 ✅
在定稿您的圖表之前，請瀏覽此驗證清單以發現常見錯誤。
- 已定義的端口：所有外部互動是否都有端口？
- 已指定類型的介面：端口是否已連接到特定的介面定義？
- 生命週期正確：組合與聚合的菱形標記是否準確？
- 範圍已檢查：內部結構是否易讀且未過於擁擠？
- 名稱一致：部件名稱是否與領域模型相符？
- 連接器有效：線條是否代表有效的關係？
- 行為情境：如有必要，是否已註明關鍵內部行為？
最終考量 🧭
設計有效的組合結構圖需要在結構準確性與可讀性之間取得平衡。其目標是清晰地傳達系統組件的內部組織。
透過避免上述錯誤，您能確保您的圖表成為開發人員與利害關係人的可靠參考。在連接埠、介面與關係上的精準度，可避免在實作階段產生歧義。
請記住，圖表是溝通的工具，而不僅僅是程式碼的記錄。如果新團隊成員無法在不加解釋的情況下理解圖表，則需要簡化。應聚焦於定義系統行為與穩定性的結構關係。
遵循這些指引將產生能經得起時間考驗的文檔，支持架構的演進，而無需不斷重寫。