PlantUML元件圖語法指南

什麼是元件圖？

一個元件圖是一種結構性UML圖用來呈現軟體系統的高階模組化組織。作為統一模型語言（UML）規格中的一個重要組成部分，這種特定的UML圖類型用以呈現實際程式碼模組、程式庫、微服務、執行套件與資料庫層級之間的結構性分組與連結方式。它將文件撰寫的焦點從細粒度的類別定義轉移開，讓軟體架構師與資深工程師能清楚地呈現系統整合邊界、API編排路徑與第三方相依性。

無論您是規劃現代雲原生微服務架構，還是展示內部框架程式庫如何與您的舊有應用程式核心相連，UML元件圖都能提供系統邊界的一個清晰且結構化的整體視圖。搭配VPasCode，您的元件佈局會根據宣告式文字自動呈現，無需手動調整佈局方塊或連接線，大幅減少繁瑣作業。

核心語法指南：元素與構造

要在 PlantUML 中設計出優雅且符合標準的 UML 元件圖，您必須熟練掌握模組化程式碼區塊宣告、介面接線機制、系統套件群組，以及方向性連接參數。

1. 宣告軟體元件

您可使用component關鍵字來宣告一個軟體模組。或者，您也可以將清晰的文字識別符號包覆在方括號內（[元件名稱]），這可作為全域的簡寫標示：

component PaymentEngine
[Auth Service] as AuthService

專業提示：請始終將長元件字串與一個as識別符（例如as AuthService）搭配使用，以保持關係線條清晰易讀。

2. 定義埠和介面

組件透過結構性進入點相互互動。您可以使用「interface」關鍵字明確地模擬標準 UML 介面（以清晰的「棒棒糖」圓形圖示視覺化表示）：interface關鍵字：

interface "REST API v2" as WebAPI
[AuthService] --() WebAPI : "公開"

3. 映射組件依賴關係

要顯示一個系統模組依賴或與另一個模組通訊，請使用方向性箭頭（-->）。您也可以使用標準的虛線依賴線（..>）來表示較鬆散的關係，例如訊息佇列消費模式或暫時性的執行時呼叫：

[Frontend App] --> WebAPI
WebAPI ..> [Database Engine] : "SQL 查詢"

4. 使用套件組織邊界

為了建立清晰的子系統邊界或根據部署環境對組件進行分類，請將您的模組區塊包裝在結構性 package 或 cloud 包裝器中：

package "安全環境" {
    [驗證服務]
    [權杖驗證器]
}

建立清晰組件子系統的最佳實務

• 保持節點名稱在高階層次： 避免根據特定的內部程式碼檔案或目錄來命名組件。使用功能性的高階名稱，例如 [通知路由器] 或 [快取層].
• 利用棒棒糖符號： 不要僅僅在方框之間繪製簡單的線條，而是透過明確的 介面 節點來傳輸連接。這能清楚地區分出 *何種* 介面正在被公開，以及 *誰* 正在使用它。
• 控制佈局擴展： 當追蹤多個子系統時，組件地圖會迅速擴展。在依賴箭頭中使用空間標記（例如 -right-> 或 -down->）來在畫布網格上整齊地組織你的組件。

現實世界中的 PlantUML 物件圖範例

範例 1：核心 API 網關網狀結構（介面與套件群組）

此範本示範了一個標準的多層系統網頁設定，強調公開的使用者應用程式如何透過結構化的 REST API 介面連接至內部微服務。

@startuml
package "公開展示層" {
    [Web SPA 客戶端] as client
    [Mobile iOS 客戶端] as mobile
}

package "API 網關子系統" {
    interface "HTTPS 網關端點" as HTTP_GW
    [Kong API 網關] as gateway
}

package "核心後端服務" {
    interface "使用者管理 API" as UserAPI
    interface "計費 API" as BillingAPI
    
    [身分驗證服務] as auth
    [付款處理引擎] as billing
}

' 連接展示層至網關
client --> HTTP_GW
mobile --> HTTP_GW
HTTP_GW -- gateway

' 連接網關至後端介面
gateway --> UserAPI
gateway --> BillingAPI

UserAPI -- auth
BillingAPI -- billing
@enduml

語法解析： 透過將模組嵌套在清晰的 套件 边界內，自動化佈局引擎會創造出美觀且分明的區域。展示層客戶端僅連接到單一公開的 HTTP_GW 網關埠，該埠隨後負責管理內部流量路由至下方的專業後端微服務層。

範例 2：雲端資料處理流程（非同步雲端與佇列）

此進階企業藍圖描繪了現實世界中的非同步雲端資料架構，追蹤資料輸入流程、解耦的消息代理以及實體儲存端點。

@startuml
cloud "AWS 雲端網路邊界" {
    [資料接收 Webhook] as webhook
    queue "Apache Kafka 群集" as broker
    [串流處理事件工作人員] as worker
    database "Amazon S3 資料倉庫" as storage
}

database "企業資料倉庫" as redshift

' 處理流程的流動機制
[外部客戶端應用程式] --> webhook : "POST /telemetry"
webhook -right-> broker : "發布原始日誌"

broker ..> worker : "消費主題資料流"
worker --> storage : "寫入壓縮的 Parquet 檔案"

storage ..> redshift : "每晚 ETL 同步"
@enduml

語法分解： 此範例介紹了專用的 cloud 和 queue 形狀，為開發人員提供即時的視覺提示，以了解結構拓撲。使用水平箭頭覆蓋 -right-> 可確保資料接收流程順暢地從左至右穿越網路格點，而虛線依賴關係（..>）能準確地表示解耦、非同步的通訊。