該儲存庫是使用 C4 模型建立軟體架構圖的示例。
圖表應該易於建立和更新，確保每個人都能獲得最新的資訊
我們都經歷過加入一個複雜的專案，解讀程式碼庫就像讀一整本小說一樣。工程師是程式碼奇才，但即使是最好的工程師也會迷失在雜亂無章的程式碼中。挑戰在於架構圖（如果存在的話）通常是過去時代的過時遺物。
這就是為什麼建立和維護清晰的圖表應該毫不費力。最新的視覺效果可確保每個人都在同一頁面上，從而消除混亂和浪費時間。
C4 模型
C4 模型的建立是為了幫助軟體開發團隊描述和交流軟體架構。
C4 代表“上下文、容器、元件和程式碼”。
這四個層次足以描述一個複雜的系統。
解釋這一概念的最佳方式是思考我們如何使用 Google 地圖。當我們在 Google 地圖上探索某個區域時，我們通常會先縮小地圖以幫助我們瞭解背景資訊。一旦我們找到我們感興趣的大致區域，我們就可以放大地圖以獲得更多細節。
第一級：Context背景
這一層級是最為縮小的，它是系統在世界背景下的鳥瞰圖。該圖集中於參與者和系統。
Context圖：該圖描繪了任務管理軟體系統與外部系統以及使用它的不同使用者組的互動。
第 2 級：容器
容器級別是系統的更詳細檢視（不要將 C4 容器與 Docker 容器混淆）。
它揭示了各種功能單元（如應用程式和資料庫）如何協同工作並分配職責。此外，該圖還突出顯示了所採用的關鍵技術並展示了這些容器之間的通訊流程。它以技術為中心的簡化檢視展示了系統的核心元件及其互動。
如果您有微服務架構，那麼每個微服務都將是一個容器。
容器的示例包括：
- 單頁應用程式
- 網路伺服器
- 無伺服器函式
- 資料庫
- API
- 訊息匯流排
- ETC。
容器圖：
本章深入探討任務管理軟體系統的內部組成。它展示了組成系統的各種容器（例如使用者介面、資料儲存）及其互動方式。
第 3 級：元件
下一個放大級別是元件。這顯示了應用程式的主要結構構建塊，通常是應用程式的概念檢視。這裡的元件一詞比較寬泛。它可以表示控制器或包含業務邏輯的服務。
該圖重點介紹任務管理軟體系統中 API 容器的內部結構。它表明 API 容器包含關鍵功能，例如用於資料操作和使用者身份驗證機制的 CRUD 操作（建立、讀取、更新、刪除）。
第四級：程式碼
最深層次的縮放是程式碼圖。雖然存在此圖，但由於程式碼描繪的畫面非常相似，因此通常不使用。
補充圖表
除了以上 4 張圖之外，還有一些值得一提的：
圖表即程式碼
C4 的強大之處在於它採用了圖表即程式碼的方法，這意味著您可以將圖表視為程式碼庫：
- 版本控制：將它們儲存在原始碼控制系統（如 Git）中，以便於跟蹤和協作。
- 協作：使用拉取請求共同處理圖表，類似於程式碼審查。
- 自動化：將它們整合到您的構建管道中，以便使用您喜歡的工具進行自動渲染。
有一些工具可以幫助進行建模和繪圖，但是現在最流行的是帶有自定義 DSL（領域特定語言）的Structurizr 。
你只需要熟悉 DSL 語法，它非常簡單。只要你習慣了，你就能立即建立或更新圖表。
下面您可以看到我們的任務管理軟體系統的縮短的 DSL。
workspace {
model {
# Actors
customer = person "Customer" "" "person"
admin = person "Admin User" "" "person"
# External systems
emailSystem = softwareSystem "Email System" "Mailgun" "external"
calendarSystem = softwareSystem "Calendar System" "Calendly" "external"
# Task Management System
taskManagementSystem = softwareSystem "Task Management System"{
webContainer = container "User Web UI" "" "" "frontend"
adminContainer = container "Admin Web UI" "" "" "frontend"
dbContainer = container "Database" "PostgreSQL" "" "database"
apiContainer = container "API" "Go" {
authComp = component "Authentication"
crudComp = component "CRUD"
}
}
# Relationships (Actors & Systems)
customer -> webContainer "Manages tasks"
admin -> adminContainer "Manages users"
apiContainer -> emailSystem "Sends emails"
apiContainer -> calendarSystem "Creates tasks in Calendar"
# Relationships (Containers)
webContainer -> apiContainer "Uses"
adminContainer -> apiContainer "Uses"
apiContainer -> dbContainer "Persists data"
# Relationships (Components & Containers)
crudComp -> dbContainer "Reads from and writes to"
webContainer -> authComp "Authenticates using"
adminContainer -> authComp "Authenticates using"
}
}
|
在 CI 中自動渲染
由於我們可以在 Github 上託管我們的模型，因此可以非常輕鬆地使用您選擇的工具自動化渲染圖表的流程。
在我們的案例中，Structurizr 有一個 Github Action，允許您執行structurizr-cli ，這是一個 Structurizr 的命令列實用程式，可讓您使用文字領域特定語言 (DSL) 基於 C4 模型建立軟體架構模型。
我們的示例儲存庫包含一個工作流程，它只是生成一個靜態頁面並將其釋出到 Github Pages。
name: Deploy static content to Github Pages
on:
push:
branches: ["main"]
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
jobs:
build:
runs-on: ubuntu-latest
container:
image: ghcr.io/avisi-cloud/structurizr-site-generatr
options: --user root
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Create site
run: |
/opt/structurizr-site-generatr/bin/structurizr-site-generatr generate-site -w diagram.dsl
- uses: actions/upload-artifact@v3
with:
name: website
path: build/site
deploy:
needs: build
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- uses: actions/download-artifact@v3
with:
name: website
path: build/site
- name: Setup Pages
uses: actions/configure-pages@v3
- name: Upload artifact
uses: actions/upload-pages-artifact@v1
with:
path: "build/site"
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v2
|
資源
- C4 模型
- DSL 語言參考
- C4 DSL Visual Studio 程式碼擴充套件