c4-architecture

C4 架構文件

使用 Mermaid 語法的 C4 模型圖表產生軟體架構文件。

工作流程

了解範圍 - 根據目標受眾決定需要的 C4 層級
分析程式碼 - 探索系統以識別元件、容器與關係
產生圖表 - 在適當的抽象層級建立 Mermaid C4 圖表
文件化 - 將圖表寫入 Markdown 檔案並附上說明脈絡

C4 圖表層級

根據文件需求選擇適當的層級：

層級	圖表類型	目標受眾	展示內容	何時建立
1	C4Context	所有人	系統 + 外部角色	總是（必要）
2	C4Container	技術人員	應用程式、資料庫、服務	總是（必要）
3	C4Component	開發者	內部元件	僅在增加價值時
4	C4Deployment	DevOps	基礎設施節點	用於正式環境
-	C4Dynamic	技術人員	請求流程（編號）	用於複雜工作流程

關鍵洞察：「對大多數軟體開發團隊來說，脈絡圖 + 容器圖就已足夠。」只有在真正增加價值時才建立元件/程式碼圖表。

快速入門範例

系統脈絡圖（層級 1）

C4Context
  title System Context - Workout Tracker

  Person(user, "User", "Tracks workouts and exercises")
  System(app, "Workout Tracker", "Vue PWA for tracking strength and CrossFit workouts")
  System_Ext(browser, "Web Browser", "Stores data in IndexedDB")

  Rel(user, app, "Uses")
  Rel(app, browser, "Persists data to", "IndexedDB")

容器圖（層級 2）

C4Container
  title Container Diagram - Workout Tracker

  Person(user, "User", "Tracks workouts")

  Container_Boundary(app, "Workout Tracker PWA") {
    Container(spa, "SPA", "Vue 3, TypeScript", "Single-page application")
    Container(pinia, "State Management", "Pinia", "Manages application state")
    ContainerDb(indexeddb, "IndexedDB", "Dexie", "Local workout storage")
  }

  Rel(user, spa, "Uses")
  Rel(spa, pinia, "Reads/writes state")
  Rel(pinia, indexeddb, "Persists", "Dexie ORM")

元件圖（層級 3）

C4Component
  title Component Diagram - Workout Feature

  Container(views, "Views", "Vue Router pages")

  Container_Boundary(workout, "Workout Feature") {
    Component(useWorkout, "useWorkout", "Composable", "Workout execution state")
    Component(useTimer, "useTimer", "Composable", "Timer state machine")
    Component(workoutRepo, "WorkoutRepository", "Dexie", "Workout persistence")
  }

  Rel(views, useWorkout, "Uses")
  Rel(useWorkout, useTimer, "Controls")
  Rel(useWorkout, workoutRepo, "Saves to")

動態圖（請求流程）

C4Dynamic
  title Dynamic Diagram - User Sign In Flow

  ContainerDb(db, "Database", "PostgreSQL", "User credentials")
  Container(spa, "Single-Page App", "React", "Banking UI")

  Container_Boundary(api, "API Application") {
    Component(signIn, "Sign In Controller", "Express", "Auth endpoint")
    Component(security, "Security Service", "JWT", "Validates credentials")
  }

  Rel(spa, signIn, "1. Submit credentials", "JSON/HTTPS")
  Rel(signIn, security, "2. Validate")
  Rel(security, db, "3. Query user", "SQL")

  UpdateRelStyle(spa, signIn, $textColor="blue", $offsetY="-30")

部署圖

C4Deployment
  title Deployment Diagram - Production

  Deployment_Node(browser, "Customer Browser", "Chrome/Firefox") {
    Container(spa, "SPA", "React", "Web application")
  }

  Deployment_Node(aws, "AWS Cloud", "us-east-1") {
    Deployment_Node(ecs, "ECS Cluster", "Fargate") {
      Container(api, "API Service", "Node.js", "REST API")
    }
    Deployment_Node(rds, "RDS", "db.r5.large") {
      ContainerDb(db, "Database", "PostgreSQL", "Application data")
    }
  }

  Rel(spa, api, "API calls", "HTTPS")
  Rel(api, db, "Reads/writes", "JDBC")

元素語法

人員與系統

Person(alias, "Label", "Description")
Person_Ext(alias, "Label", "Description")       # 外部人員
System(alias, "Label", "Description")
System_Ext(alias, "Label", "Description")       # 外部系統
SystemDb(alias, "Label", "Description")         # 資料庫系統
SystemQueue(alias, "Label", "Description")      # 佇列系統

容器

Container(alias, "Label", "Technology", "Description")
Container_Ext(alias, "Label", "Technology", "Description")
ContainerDb(alias, "Label", "Technology", "Description")
ContainerQueue(alias, "Label", "Technology", "Description")

元件

Component(alias, "Label", "Technology", "Description")
Component_Ext(alias, "Label", "Technology", "Description")
ComponentDb(alias, "Label", "Technology", "Description")

邊界

Enterprise_Boundary(alias, "Label") { ... }
System_Boundary(alias, "Label") { ... }
Container_Boundary(alias, "Label") { ... }
Boundary(alias, "Label", "type") { ... }

關係

Rel(from, to, "Label")
Rel(from, to, "Label", "Technology")
BiRel(from, to, "Label")                        # 雙向
Rel_U(from, to, "Label")                        # 向上
Rel_D(from, to, "Label")                        # 向下
Rel_L(from, to, "Label")                        # 向左
Rel_R(from, to, "Label")                        # 向右

部署節點

Deployment_Node(alias, "Label", "Type", "Description") { ... }
Node(alias, "Label", "Type", "Description") { ... }  # 簡寫

樣式與佈局

佈局設定

UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

$c4ShapeInRow - 每行形狀數量（預設：4）
$c4BoundaryInRow - 每行邊界數量（預設：2）

元素樣式

UpdateElementStyle(alias, $fontColor="red", $bgColor="grey", $borderColor="red")

關係樣式

UpdateRelStyle(from, to, $textColor="blue", $lineColor="blue", $offsetX="5", $offsetY="-10")

使用 $offsetX 和 $offsetY 修正重疊的關係標籤。

最佳實務

基本規則

每個元素必須包含：名稱、類型、技術（若適用）與描述
僅使用單向箭頭 - 雙向箭頭會造成混淆
為箭頭標註動作動詞 - 「使用電子郵件傳送」、「從…讀取」，而非僅「使用」
包含技術標籤 - 「JSON/HTTPS」、「JDBC」、「gRPC」
每個圖表不超過 20 個元素 - 將複雜系統拆分為多個圖表

清晰度指南

從層級 1 開始 - 脈絡圖有助於界定系統範圍
每個檔案一個圖表 - 保持圖表專注於單一抽象層級
有意義的別名 - 使用描述性別名（例如 orderService 而非 s1）
簡潔的描述 - 盡可能將描述控制在 50 個字元以內
務必包含標題 - 「[系統名稱]的系統脈絡圖」

應避免的事項

詳見 references/common-mistakes.md 中的反模式：

混淆容器（可部署）與元件（不可部署）
將共用函式庫建模為容器
將訊息代理顯示為單一容器而非個別主題
加入未定義的抽象層級如「子元件」
移除類型標籤以「簡化」圖表

微服務指南

單一團隊擁有

將每個微服務建模為容器（或容器群組）：

C4Container
  title Microservices - Single Team

  System_Boundary(platform, "E-commerce Platform") {
    Container(orderApi, "Order Service", "Spring Boot", "Order processing")
    ContainerDb(orderDb, "Order DB", "PostgreSQL", "Order data")
    Container(inventoryApi, "Inventory Service", "Node.js", "Stock management")
    ContainerDb(inventoryDb, "Inventory DB", "MongoDB", "Stock data")
  }

多團隊擁有

當微服務由不同團隊擁有時，提升為軟體系統：

C4Context
  title Microservices - Multi-Team

  Person(customer, "Customer", "Places orders")
  System(orderSystem, "Order System", "Team Alpha")
  System(inventorySystem, "Inventory System", "Team Beta")
  System(paymentSystem, "Payment System", "Team Gamma")

  Rel(customer, orderSystem, "Places orders")
  Rel(orderSystem, inventorySystem, "Checks stock")
  Rel(orderSystem, paymentSystem, "Processes payment")

事件驅動架構

將個別主題/佇列顯示為容器，而非單一的「Kafka」方塊：

C4Container
  title Event-Driven Architecture

  Container(orderService, "Order Service", "Java", "Creates orders")
  Container(stockService, "Stock Service", "Java", "Manages inventory")
  ContainerQueue(orderTopic, "order.created", "Kafka", "Order events")
  ContainerQueue(stockTopic, "stock.reserved", "Kafka", "Stock events")

  Rel(orderService, orderTopic, "Publishes to")
  Rel(stockService, orderTopic, "Subscribes to")
  Rel(stockService, stockTopic, "Publishes to")
  Rel(orderService, stockTopic, "Subscribes to")

輸出位置

將架構文件寫入 docs/architecture/，命名規則如下：

c4-context.md - 系統脈絡圖
c4-containers.md - 容器圖
c4-components-{feature}.md - 各功能的元件圖
c4-deployment.md - 部署圖
c4-dynamic-{flow}.md - 特定流程的動態圖

依受眾調整細節

受眾	建議圖表
高階主管	僅系統脈絡圖
產品經理	脈絡圖 + 容器圖
架構師	脈絡圖 + 容器圖 + 關鍵元件圖
開發者	所有層級（依需求）
DevOps	容器圖 + 部署圖

參考資料

references/c4-syntax.md - 完整的 Mermaid C4 語法
references/common-mistakes.md - 應避免的反模式
references/advanced-patterns.md - 微服務、事件驅動、部署

您可能也喜歡

deployment-pipeline-design

38Kdevops-cloud

Design multi-stage CI/CD pipelines with approval gates, security checks, and deployment orchestration. Use this skill when designing zero-downtime deployment pipelines, implementing canary rollout strategies, setting up multi-environment promotion workflows, or debugging failed deployment gates in CI/CD.

wshobson

獲取

homelab-pihole-dns

238Kdevops-cloud

Pi-hole installation, blocklist management, DNS-over-HTTPS setup, DHCP integration, local DNS records, and troubleshooting broken DNS resolution on a home network.

affaan-m

獲取

cloud-design-patterns

37Kdevops-cloud

Cloud design patterns for distributed systems architecture covering 42 industry-standard patterns across reliability, performance, messaging, security, and deployment categories. Use when designing, reviewing, or implementing distributed system architectures.

github

獲取

繼續探索

瀏覽 devops-cloud 熱門 Skills 最近更新