C4 圖表
來源:官方 C4 模型,網址為 https://c4model.com/。在繪製、審查或解釋任何 C4 圖表時,請套用以下規則。當輸出內容包含文字(如 ADR、文件、PR 描述)時,請一併載入 writing 技能。
1. 目的
C4 是一組程式碼的四層縮放地圖:脈絡(Context)、容器(Containers)、元件(Components)、程式碼(Code)。由 Simon Brown 創建,靈感來自 UML 和 4+1 視圖模型,用以取代臨時的方框和連線圖。它能修正的典型問題包括:無圖例、混合抽象層級、未標示的箭頭、缺少技術堆疊,以及模糊的標籤(例如「商業邏輯」)。
C4 不受記號法及工具限制。重要的是以下抽象層級與規則,而非形狀。
2. 抽象層級
階層:人物(Person) -> 軟體系統(Software System) -> 容器(Container) -> 元件(Component) -> 程式碼(Code)。每一層級都是對上一層級中某個元素的放大。
| 抽象層級 | 定義 | 範例 |
|---|---|---|
| 人物 (Person) | 系統的人類使用者、參與者、角色或人物誌 | 客戶、支援專員、管理員 |
| 軟體系統 (Software System) | 最高層級的抽象;為使用者提供價值。通常由單一團隊擁有和建置。它不是產品領域、限界上下文(bounded context)、部落(tribe)或小隊(squad) | 購票平台、支付系統 |
| 容器 (Container) | 軟體系統內部可獨立執行或部署的應用程式或資料儲存 | 伺服器端網頁應用程式、SPA、桌面應用程式、行動應用程式、無伺服器函式、批次/主控台應用程式、微服務 API、資料庫綱要、S3/物件儲存、CDN、檔案系統、Shell 腳本 |
| 元件 (Component) | 容器內部,透過明確定義的介面所封裝的一組相關功能。不可單獨部署:一個容器內的所有元件共用同一個程序空間 | OrderController、PaymentService、EmailSender |
| 程式碼 (Code) | 元件內部的類別、介面、函式或資料庫表格 | class OrderValidator、orders 表格 |
容器規則 (C4 FAQ)
- C4 的容器不是 Docker。 它是一個可執行/可部署的應用程式或資料儲存,無論其封裝方式為何。
- 伺服器端渲染的 HTML 應用程式是 1 個容器。伺服器加上 SPA 或行動用戶端是透過遠端 API 通訊的 2 個容器。
- JAR、DLL、組件和模組不是容器。它們是容器內部組織程式碼的方式。
- 當您擁有或控制儲存槽或綱要時,受管理的資料服務(S3、RDS、CDN)是您系統邊界內的容器。它們不是外部系統。
元件規則
- 元件不是一個資料夾、套件或 JAR。它是一個帶有介面的功能分組。
- 元件不可獨立部署。如果可以獨立部署,它就是一個容器。
調整術語
團隊可以使用與語言慣例相符的名稱(例如在函數式程式碼中使用「模組 (Module)」或「函式 (Function)」),但必須在圖表或其文件中明確定義該詞彙。除非每個額外的抽象層級都有嚴格的定義,否則不要發明新的層級。
3. 特殊建模模式
佇列 (Queues) 和主題 (Topics)
- 錯誤方式: 在中間放一個巨大的「訊息匯流排 (Message Bus)」容器,所有服務都連接到它(中樞與輻射式)。這會隱藏誰產生以及誰消費了什麼訊息。
- 選項 1(建議): 將每個佇列或主題建模為一個容器(一個訊息資料儲存)。生產者寫入,消費者讀取或訂閱。
- 選項 2: 針對直接的點對點耦合,省略佇列方框,並將關係標記為
"Publishes order events via Queue orders [AMQP]"。可選擇性地使用與 HTTP 呼叫不同的線條樣式(請在圖例中說明)。
範例:Order API --"Publishes OrderPlaced to [Kafka]"--> [(orders topic)] --"Reads OrderPlaced from [Kafka]"--> Fulfilment Worker。
微服務 (Conway's Law 規則)
- 單一團隊擁有整個軟體系統: 將每個微服務建模為該系統邊界內的一組容器(API 容器加上其自己的資料庫綱要容器,或一個單一的無狀態 Lambda 容器)。
- 不同團隊擁有各自的服務: 將每個獨立擁有的服務提升為其自己的軟體系統 (Software System),每個系統都有自己的系統脈絡圖和容器圖。明確說明跨系統邊界的佇列/主題擁有權。
4. 圖表目錄
核心靜態層級
| 層級 | 圖表 | 建議 | 範圍 | 受眾 | 顯示/省略 |
|---|---|---|---|---|---|
| 1 | 系統脈絡 (System Context) | 是 | 1 個軟體系統 | 技術與非技術人員 | 系統周圍的人物與外部系統。省略低階技術與協定 |
| 2 | 容器 (Container) | 是 | 1 個軟體系統 | 技術與營運人員 | 主要技術選擇與程序間協定。省略叢集、負載平衡器、容錯移轉 |
| 3 | 元件 (Component) | 否:僅在能帶來明顯價值時使用(最好是自動化產生) | 1 個容器 | 架構師、開發人員 | 單一容器內的元件及其互動 |
| 4 | 程式碼 (Code) | 否:在 IDE 中按需產生 | 1 個元件 | 開發人員 | UML 類別圖或 ER 圖 |
輔助圖表
| 圖表 | 建議 | 用途 |
|---|---|---|
| 系統全景 (System Landscape) | 是,適用於組織和投資組合 | 企業或部門層級的地圖,顯示所有系統和人員。一張沒有單一焦點系統的脈絡圖 |
| 動態 (Dynamic) | 否:謹慎使用 | 複雜的執行時期協作。可使用編號協作風格或 UML 順序圖風格 |
| 部署 (Deployment) | 是 | 1 個環境(生產、暫存、開發)。巢狀部署節點(實體機、VM、Docker、Kubernetes、執行時期)包含系統/容器實例,以及基礎設施節點(DNS、負載平衡器、防火牆) |
相容性
- arc42: 脈絡與範圍 (Context & Scope) -> L1;建構區塊層級 1 (Building Block level 1) -> L2;建構區塊層級 2 (Building Block level 2) -> L3;建構區塊層級 3 (Building Block level 3) -> L4。
- UML: 使用 UML 狀態圖、順序圖和 ER 圖來補充 C4,用於工作流程、狀態機和資料模型。
縮放規則
當圖表變得雜亂時,不要試圖將數十個方框塞進一個畫布中。應按業務領域、限界上下文、功能或單一服務焦點(焦點服務及其入站和出站鄰居),在相同的抽象層級上進行拆分。
5. 記號法規則
圖表
- 標題需說明圖表類型和範圍:
Container diagram for Checkout System。 - 務必包含一個圖例 (key/legend) 來說明形狀、顏色、邊框、線條類型、箭頭和縮寫。
- 保持嚴格的抽象層級純粹性:永遠不要混合抽象層級(例如,在 L2 容器圖中放入「元件」方框),並且永遠不要在 L1 系統脈絡圖中放入協定或內部實作步驟(例如
[HTTPS]、masked packet、tool_runner)。 - 在比較競爭或歷史架構時,請明確標示邊界標題(例如
Option A (Superseded)與Option B (Current)),並在需求或假設變更時更新文件中的所有圖表。
元素
- 名稱、明確的元素類型(
Person、Software System、Container、Component、Database、Deployment Node),以及簡潔的職責描述。 - 每個容器、元件和部署節點都需要明確的技術堆疊。
關係
- 僅使用單向箭頭。 絕對不要用
<-->。如果資料是雙向流動的,請顯示發起者的方向,並在標籤中描述回應。 - 使用具體主動動詞的標籤。永遠不要只寫「Uses (使用)」。請寫
Submits orders to、Reads seat map from。 - 在容器對容器的關係上標註協定/技術:
[JSON/HTTPS]、[SQL]、[gRPC]、[AMQP]。
6. Markdown 中的 Mermaid
預設使用 flowchart(flowchart TB 或 LR),而不是 Mermaid 原生的 C4Context/C4Container。原生的 C4 語法仍在實驗階段,經常無法在 Markdown 檢視器中正確渲染。僅在使用者明確要求並確認渲染器支援時才使用它。
流程圖慣例:
- 使用
subgraph作為系統邊界(容器/元件)或部署節點。 - 使用
[(...)]表示資料庫、資料儲存、佇列和主題。 - 使用包含 HTML 的標籤:
"<b>Name</b><br/>«Container: Tech»<br/>Short responsibility"。 - 使用包含標籤的箭頭:
A -->|"Action [Protocol]"| B。 - 每種元素類型使用一個
classDef,並一致地套用。 - 當使用顏色、圓柱形狀或多種線條樣式時,需要一個緊湊的
Legend子圖(未連接的節點,透過一個不可見的bottomNode ~~~ Legend連結固定在底部,以防 Dagre 將其放置在頂部);在程式碼區塊正上方放置一個標題或Title: ...行。 - 動態圖表:使用
sequenceDiagram,或使用帶編號箭頭標籤的flowchart(例如1. Submits order [JSON/HTTPS])。 - 部署圖:在
flowchart中使用巢狀subgraph。 - 當標籤包含括號、方括號或冒號時,務必使用引號。
- 絕對不要在
sequenceDiagram或stateDiagram-v2的標籤中放入未跳脫的分號(;)(Mermaid 會將;視為陳述式終止符,並將剩餘文字分割成錯誤的狀態或解析錯誤);在sequenceDiagram中,使用<br/>包裹較長的Note區塊,以防止文字在視口邊緣被裁剪。
範本:L1 系統脈絡圖
標題:System Context diagram for Ticketing Platform
flowchart TB
customer["<b>Customer</b><br/>«Person»<br/>Buys tickets for events"]
ticketing["<b>Ticketing Platform</b><br/>«Software System»<br/>Lets customers browse events and buy tickets"]
payments["<b>Payment Provider</b><br/>«Software System, external»<br/>Charges cards"]
email["<b>Email Service</b><br/>«Software System, external»<br/>Delivers confirmation emails"]
customer -->|"Browses events and buys tickets using"| ticketing
ticketing -->|"Requests card charges from"| payments
ticketing -->|"Sends confirmation emails using"| email
email -->|"Delivers confirmation emails to"| customer
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef system fill:#1168bd,stroke:#0b4884,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class ticketing system
class payments,email external
subgraph Legend
direction LR
l1["Person"]:::person
l2["Software System (in scope)"]:::system
l3["Software System (external)"]:::external
end
範本:L2 容器圖(含佇列容器)
標題:Container diagram for Ticketing Platform
flowchart TB
customer["<b>Customer</b><br/>«Person»<br/>Buys tickets for events"]
payments["<b>Payment Provider</b><br/>«Software System, external»<br/>Charges cards"]
subgraph boundary["Ticketing Platform [Software System]"]
spa["<b>Web App</b><br/>«Container: React SPA»<br/>Event browsing and checkout UI"]
api["<b>Order API</b><br/>«Container: Java, Spring Boot»<br/>Validates and places orders"]
db[("<b>Orders DB</b><br/>«Container: PostgreSQL»<br/>Stores orders and tickets")]
topic[("<b>orders topic</b><br/>«Container: Kafka topic»<br/>OrderPlaced events")]
worker["<b>Fulfilment Worker</b><br/>«Container: Python»<br/>Issues tickets and sends emails"]
end
customer -->|"Browses and buys using [HTTPS]"| spa
spa -->|"Submits orders to [JSON/HTTPS]"| api
api -->|"Writes orders to [SQL/TCP]"| db
api -->|"Publishes OrderPlaced to [Kafka]"| topic
worker -->|"Reads OrderPlaced from [Kafka]"| topic
worker -->|"Updates ticket status in [SQL/TCP]"| db
api -->|"Requests card charges from [JSON/HTTPS]"| payments
classDef person fill:#08427b,stroke:#052e56,color:#fff
classDef container fill:#438dd5,stroke:#2e6295,color:#fff
classDef store fill:#2e6da4,stroke:#1b4f72,color:#fff
classDef external fill:#999,stroke:#6b6b6b,color:#fff
class customer person
class spa,api,worker container
class db,topic store
class payments external
subgraph Legend
direction LR
l1["Person"]:::person
l2["Container"]:::container
l3[("Data store / queue / topic")]:::store
l4["External system"]:::external
end
圖例說明:箭頭從發起者指向目標。標籤說明了動作和通訊協定 [protocol]。
範本:部署圖
標題:Deployment diagram for Ticketing Platform (Production)
flowchart TB
users["<b>Customer browser</b><br/>«Deployment Node: Chrome»"]
subgraph aws["AWS «Deployment Node: Cloud, us-east-1»"]
dns["<b>Route 53</b><br/>«Infrastructure Node: DNS»"]
lb["<b>Load Balancer</b><br/>«Infrastructure Node: ALB»"]
subgraph eks["EKS «Deployment Node: Kubernetes cluster»"]
subgraph pod["order-api pod «Deployment Node: Docker, x3»"]
api["<b>Order API</b><br/>«Container instance: Java, Spring Boot»"]
end
end
subgraph rds["RDS «Deployment Node: PostgreSQL 16»"]
db[("<b>Orders DB</b><br/>«Container instance: PostgreSQL schema»")]
end
end
users -->|"Resolves hostname using [DNS]"| dns
users -->|"Sends requests to [HTTPS]"| lb
lb -->|"Forwards requests to [HTTP]"| api
api -->|"Reads and writes orders in [SQL/TCP]"| db
如果您使用了預設以外的顏色或樣式,請加入一個 Legend 子圖。
範本:動態圖(序列圖)
標題:Dynamic diagram (sequence style) for Order Checkout in Ticketing Platform
sequenceDiagram
autonumber
actor customer as Customer
participant spa as Web App (React SPA)
participant api as Order API (Spring Boot)
participant payments as Payment Provider
participant db as Orders DB (PostgreSQL)
participant topic as orders topic (Kafka)
customer->>spa: Clicks "Place Order"
spa->>api: POST /orders [JSON/HTTPS]
api->>payments: Charges card [JSON/HTTPS]
payments-->>api: Payment authorized
api->>db: Inserts order row [SQL/TCP]
api->>topic: Publishes OrderPlaced [Kafka]
api-->>spa: 201 Created (order confirmation)
spa-->>customer: Shows order receipt
為了確保與大多數 Markdown 檢視器的相容性,請保持 sequenceDiagram 的參與者和訊息標籤中不含未加引號的斜線、分號(;,Mermaid 會將其解析為陳述式終止符)或原始換行符。
7. Diagr
…
[已截斷以利翻譯]