架構圖表
所謂「理解」一張圖,是指圖中呈現的內容能與讀者已知的知識對接。資深開發者會從圖中讀取頂層流程與接縫。一個區塊是一個黑箱:它的設計模式、職責、擁有者,以及其內部細節均隱藏不露。一個區塊透過接縫提供給另一個區塊的,就是它的介面:包含有參數與回傳型別的作業、錯誤、跨越接縫的資料型別及其欄位,以及一個具體的範例——說明實際跨越的內容及其樣貌。傳輸方式(REST、OPC UA、程序啟動)是介面的一個屬性,絕不能取代介面本身。
在開始繪圖之前,請先閱讀 EXAMPLE.md:一個完整的變更,以兩種形式呈現。
步驟
1. 讀者的詞彙
一個新的術語無法對接任何既有知識。在開始之前,先收集讀者已經擁有的詞彙:從他們在此對話中的訊息、他們撰寫的文件(專案說明、架構頁面、詞彙表、命名對照表),以及與圖表進行比較的每個模型中收集。建立詞彙表:事物名稱、讀者對它的稱呼、其他會閱讀此圖表的各方對它的稱呼、程式碼中的名稱,以及圖表本身使用的詞彙。
- 使用讀者的詞彙來標示每個區塊與介面;程式碼名稱則並列在一旁。
- 若兩個詞彙衝突,或一個詞彙用於錯誤的事物,請選擇其中一個,在詞彙表中說明為什麼,並在旁邊一次性地標示另一個詞彙。
- 不要創造新詞。一個在程式碼中沒有名稱的介面,就用它的兩端來稱呼,例如
前端 -> 後端。 - 從讀者已有的圖像開始——他們自己的圖表及其層級與名稱——並將新內容放入其中。
完成條件:圖表上的每個標籤都來自詞彙表,並且每個對讀者來說是新的術語,都與它所屬的已知詞彙一同出現在詞彙表中。
2. 問題
寫下讀者的問題,每行一個。他們來選擇視圖。
| 問題 | 視圖 |
|---|---|
| 有哪些部分,每個部分負責什麼,誰擁有它,誰呼叫誰? | 構建區塊視圖 |
| 哪個介面連接兩個部分,且實際跨越的是什麼? | 介面、其資料型別與每個接縫上的範例 |
| 在關鍵的場景中,事件發生的順序為何? | 執行時視圖:一個序列 |
| 每個部分在哪裡運行? | 每個區塊上的 host:;若問題涉及網路或信任邊界,則使用部署視圖 |
| 變更做了什麼,或者兩個設計之間有何差異? | 以相同格式呈現每個狀態,然後說明差異 |
完成條件:每個視圖都有對應的問題,並且該問題作為標題置於視圖上方。
3. 目錄
在開始繪製任何圖之前,從來源資料中填寫四個列表。
- 區塊:讀者的詞彙與程式碼中的名稱、原型、一句話描述其職責、擁有者、主機。
- 介面,每個接縫一個:提供者、消費者、每個作業以簽章形式呈現
名稱(參數: 型別) -> 型別、錯誤、傳輸方式。 - 資料型別:簽章中提到的每個型別,及其欄位、單位與預設值。
- 範例,每個介面一個:訊息實際跨越時的樣貌,請以其實際格式呈現請求和回應:指令行與其輸出、JSON 主體、資料表的一行。從一次執行、錄製、測試固件或資料中取得。若範例是根據程式碼拼湊而成,請在第一行說明。
每個條目都須附帶其來源:程式碼參考 路徑:行號,或一個標籤(如下)。他人繪製的狀態、模型檔案或草圖,須原樣以其自身的詞彙重現;其遺漏的部分標記為 [undefined],而你所新增的內容則放入一個獨立的狀態中。
完成條件:每個區塊都有其職責描述,每個接縫都有介面且其簽章來自程式碼或已標記,每個簽章中的型別都有其欄位,每個介面都有其範例,且每個條目都有參考或標籤。
4. 層級
一個狀態中的區塊是同級單位:可以獨立部署、擁有或替換,數量在五到九個之間。檔案、函式以及區塊內部的步驟,都是它的內部細節。放大是指更進一步的圖表,往下一層,針對問題所關注的那一個區塊來繪製。
完成條件:狀態中的任何區塊都不包含另一個區塊,且每個放大圖都標明它所回答的問題。
5. 形式
- 聊天形式,寬度不超過 78 欄:構建區塊視圖,在每條邊上標示介面的名稱及其主要簽章,然後是表格形式的目錄與程式碼區塊形式的範例。適用於單一狀態或小幅變更。
- 畫布形式,一個靜態 HTML 頁面,包含所需寬度的文字圖表:每條邊旁邊完整顯示其介面、範例,以及資料型別及其欄位。適用於多個狀態,或當需要完整顯示超過三個接縫時。此頁面由一個與之並存的產生器腳本建構;聊天回答中須指明檔案名稱,用幾句話說明比較結果顯示了什麼,並列出未決定的項目。
- C4 形式,使用 LikeC4 繪製的相同模型,以頁面呈現,每個狀態一個分頁,區塊可以點擊並放大查看。文字圖表是其原型:先確定詞彙、區塊、介面與範例,然後再進行渲染。適用於其他人會開啟的結果。請閱讀 LIKEC4.md。
6. 繪製
使用此資料夾中的三個檔案來繪製,使區塊對齊,且每行寬度不超過其畫布。每個檔案的 docstring 即為其使用手冊,執行它會顯示一個範例。
| 檔案 | 提供 |
|---|---|
grid.py | Grid(含分隔區的區塊、線條、箭頭)、sequence(執行時視圖)、table |
canvas.py | glance(每個狀態一行)、overview(狀態並排,每個層級一行)、panel(單一狀態:區塊、含範例的介面、資料型別) |
page.py | html_page:圍繞圖表的頁面,包含顏色與 id 之間的連結 |
likec4/ | 用於 C4 形式:template.c4、build.sh、含 tabs.js 的分頁頁面 index.html,以及 clicktest.py |
一個頁面的組織方式,從十秒鐘就能掌握的概覽,到細節:總覽、詞彙表、閱讀指南、概觀、每個狀態一個面板、每個接縫的差異以表格呈現、未決定的項目、詞彙表、來源。
7. 檢查
- 每個區塊都來自目錄中的區塊,每條邊都來自介面,每個型別框都來自資料型別;刻意從圖表中省略的條目,須有正當理由。
- 每個程式碼參考都可解析:檔案存在且該行顯示了名稱。
- 同一個區塊在每個狀態中都位於相同的位置。某個狀態缺少的區塊,以虛線框表示。
- 整個頁面的螢幕截圖,逐塊檢視:邊界吻合,無內容被裁切,顏色承載其意義。
- 來源資料須說明:讀取了哪些內容、在哪個 commit、哪些範例是真實的,以及哪些內容未被讀取。
狀態
狀態可以是程式碼的現狀、某人繪製的目標,或是一個提案。透過位置來比較狀態:同一個區塊在 glance 的同一欄,且在 overview 的同一列,這樣兩個狀態的空白處就會顯示它們如何互補。
一個接縫有一個 ID,由狀態的字母和一個數字組成,例如 (I4)。在一個接縫處定義的介面或資料型別,在其他地方都透過此 ID 來引用;其欄位只撰寫一次。
差異以表格呈現,每個接縫一行,每個狀態一列。未決定的項目也以表格呈現:問題、選項、由誰決定。
標籤與原型
| 標籤 | 意義 |
|---|---|
[code] | 存在於程式碼中;參考資訊並列在一旁 |
一個來源標籤,例如 [c4] | 由某個來源模型所陳述;在閱讀指南中說明此標籤 |
[proposed] | 此處提案,尚不存在於任何地方 |
[new] [changed] [moved] | 當僅有現狀與未來狀態時,用來表示變更的影響 |
[undefined] | 該狀態未定義此項目 |
[?1] | 一個未決定的項目,並列出其編號 |
原型用來命名區塊所扮演的設計模式角色:<<ui>>、<<client>>、<<gateway>>、<<facade>>、<<service>>、<<port>>、<<adapter>>、<<repository>>、<<external>>。當程式碼扮演該角色時使用。沒有原型的區塊,比使用錯誤原型的區塊要好。Port 是一種由消費者擁有、提供者實作的介面:<<port>> 放在介面上,<<adapter>> 放在實作該介面的區塊上。來源模型自有的種類,則按照其原文引用。
說明手段
以下每種手段都應有其價值,用來回答讀者原本可能必須提出的問題。請節制使用。
- 閱讀指南:一個小型圖表,說明如何閱讀面板,以及標籤的含義。
- 程式碼參考:每個介面與資料型別都附上,方便讀者查閱。
- 簡短說明文字:在狀態上方用一段話說明該狀態的重點;在介面框內,當讀者可能會問「為什麼」的地方加上註解。
- 詞彙表:涵蓋詞彙表中未包含的術語,每個一行。
- 顏色:僅用於標籤、ID,以及一兩個在所有狀態間保持不變的「關鍵」名稱。顏色標記狀態間共享與相異之處;其他內容不使用顏色。
說明文字使用對話進行的語言。來自程式碼和來源模型的名稱則保持原樣。