Excalidraw 架構圖(EIP 表示法) 是做什麼的?
圖即是一個小型的 JSON 規格 — 節點、邊、群組 — 加上一個產生器,它會將這些內容以 Hohpe & Woolf 表示法進行佈局。規格是事實的唯一來源;.excalidraw 檔案與預覽用的 .svg 是建置產物。
<skill-dir> 是此技能安裝所在目錄 — 例如 ~/.omp/agent/skills/excalidraw-architecture、~/.claude/skills/excalidraw-architecture 或 .agents/skills/excalidraw-architecture — 以及 https://github.com/jamescarr/diagram-skill 倉庫中的 skills/excalidraw-architecture 目錄。
使用時機
- 被要求繪製、草擬或視覺化一個服務、事件或訊息架構。
- 解釋訊息如何傳遞:哪條通道、哪個端點、失敗時發生什麼事。
- 在脈絡、流程或端點層級記錄限界上下文的整合表面。
- 審查訊息導向的設計,圖中必須揭露遺失的 DLQ、關聯 ID 或等冪性。
不使用時機
- UI 模型、線框圖、簡報、自由形式白板。
- 顯示單一程序內部呼叫的序列圖。
- 任何交付成果不是
.excalidraw檔案的項目。
工作流程
-
盤點 — 在繪製前列出:
- 參與者:服務、外部系統、角色、儲存庫;
- 通道:名稱、點對點 vs 發布-訂閱、金鑰/分區/排序、持久性、DLQ;
- 訊息:名稱(命令 = 祈使句,事件 = 過去式,文件 = 名詞)和類型;
- 每個服務的端點:閘道、寄件匣/交易、消費者樣式、競爭數量、等冪性、持久性、選擇性;
- 路由和轉換步驟;
- 請求-回覆配對:回覆通道、關聯、TTL;
- 管理:探針、存放區、控制匯流排。
如果已安裝
enterprise-integration-patterns技能,在模式選擇不明確時應閱讀該技能。
-
挑選層級 —
context(脈絡):角色、服務、外部系統、代理器視為message-bus、rpc/data邊。flow(流程,預設):以端到端的方式呈現一個業務流程,包含通道與 EIP 元件。endpoint(端點):在單一服務內部 — 閘道 → 寄件匣 → 通道,或消費者 → 等冪接收器 → 啟動器。每個圖一個流程,最多 20 個節點;否則按流程拆分。 -
撰寫規格 — 在圖表將存放的資料夾(預設為
docs/architecture/)旁建立<name>.spec.json,使用下方的速查表。執行node <skill-dir>/scripts/eip_excalidraw.mjs kinds以取得完整的分類目錄。 -
建置 —
node <skill-dir>/scripts/eip_excalidraw.mjs build <name>.spec.json會寫出<name>.excalidraw和<name>.svg。修正所有error:(退出碼 2);將warning:視為佈局缺陷(--strict會使警告導致退出碼 1)。--check會驗證與佈局但不寫入檔案。 加上--png [OUT.png]可額外匯出由 Excalidraw 本身渲染的 PNG(手繪風格、Excalifont 字型、場景嵌入檔案中,因此可重新拖放到 excalidraw.com)— 適合嵌入 README、文件或部落格文章。它需要 Chrome 或 Chromium(CHROME環境變數可覆蓋查找路徑)以及對 esm.sh 的網路存取;它透過scripts/export_png.mjs驅動瀏覽器。匯出失敗時退出碼為 3,但仍會寫入場景。 -
檢視 — 若有建置 PNG 則
read <name>.png,否則read <name>.svg:img;然後進行審查清單檢查。 -
修正 — 每次規格變更後重新建置:
症狀 規格變更 箭頭穿過節點 route: "ortho"或"below",或固定row標籤與節點重疊 縮短 message/label,或將節點的row固定到遠離箭頭的位置箭頭縮小 該欄間距中箭頭過多:將一個路線設為 below/above,或固定row以減少共用該垂直線的箭頭數量反向箭頭雜亂 route: "above"回覆箭頭在整個圖下方迴圈 route: "ortho",或將回覆通道放在請求通道旁邊欄位擁擠 添加 lanes,或拆分圖表節點標籤過長 將細節移至 sub群組成員分散 固定 col/row使成員相鄰框架包含非成員 固定 col/row或使用lanes使群組成員形成連續區塊 -
交付 — 交付
.spec.json、.excalidraw和.svg(若曾建置 PNG 則包含.png)。說明規格是事實來源:編輯後應重新產生。之後在 Excalidraw 中手動編輯是可以的,但重建會覆寫這些編輯。
建模規則
每條規則都是一個圖表必須可見的主張;當無法成立時,應明確繪製例外狀況。
- 每個通道都要顯示其類型標籤以及金鑰/分區/排序標籤(
tags)。 - 每個至少傳送一次通道的消費者都必須帶有
idempotent— 或者圖表必須說明原因。徽章僅存在於應用程式家族節點上,因此 saga、路由器或聚合器必須在sub中說明其去重規則(dedupe by orderId)。 - 每個消費者可能失敗的通道都有一個
dead-letter-channelshadow;驗證失敗則獲得一個invalid-message-channel。對於未繪製或故意省略的 DLQ,必須在通道的sub或note中說明。 - 請求-回覆 = 一個帶有
reply_to和correlation的命令邊,加上一條虛線的回覆邊回來。 - 聚合器、分散-收集和 saga 節點必須在
sub中帶有完成規則(計數/逾時)。 - 交易內的發布 = 一個
outbox徽章或outbox節點,絕不能是提交後的裸發布。 - 轉換器位於限界上下文邊界(框架)上。
- 競爭消費者顯示
competing:N;持久訂閱帶有durable。 - 探針是以
tap邊連接到message-store。 - 智慧端點,愚蠢管道:路由邏輯存在於路由器節點中,絕不能暗示在通道內部。
- 同步呼叫是
rpc邊,並且是例外情況,而非預設方式。 - 跨越邊界的內部記錄需要一個
content-filter或claim-check參考。
規格速查表
按 EIP 章節分類的節點 — 完整的分類對照表在 references/spec.md 中:
| 章節 | 種類 | 使用時機 |
|---|---|---|
| 通道 | channel p2p-channel pubsub-channel datatype-channel dead-letter-channel invalid-message-channel message-bus control-bus | 訊息在參與者之間移動;選定 p2p 或 pub-sub,然後設定失敗通道。 |
| 訊息 | message command-message document-message event-message | 訊息本身是主題,而非端點。 |
| 路由 | content-based-router message-filter dynamic-router recipient-list splitter aggregator resequencer composed-message-processor scatter-gather routing-slip process-manager saga | 一個訊息有多個可能的目的地,或需要重新組合各部分。 |
| 轉換 | message-translator envelope-wrapper content-enricher content-filter claim-check normalizer | 有效負載或其封裝在跳躍之間發生變化。 |
| 端點 | message-endpoint messaging-gateway messaging-mapper transactional-client polling-consumer event-driven-consumer competing-consumers message-dispatcher selective-consumer durable-subscriber idempotent-receiver service-activator channel-adapter | 服務如何連接到通道並消費它。 |
| 系統管理 | wire-tap detour message-history smart-proxy test-message channel-purger | 可觀測性、探測與操作。 |
| 基礎設施 | message-broker messaging-bridge outbox inbox | 代理器本身、代理器間連結、交易性發布/消費。 |
| 參與者與儲存庫 | service external-system actor datastore message-store schema-registry note | 誰擁有通道端點;狀態、結構描述與註解存放何處。 |
徽章(僅適用於應用程式家族節點;藥丸形狀呈現簡短文字):
| 群組 | 徽章 |
|---|---|
| 端點 | gateway(訊息閘道)、mapper(訊息映射器)、activator(服務啟動器)、adapter(通道配接器) |
| 消費 | polling(輪詢消費者)、event-driven(事件驅動消費者)、competing / competing:N(競爭消費者,在最多三個方塊的堆疊上呈現 competing ×N)、dispatcher(訊息分派器)、selective(選擇性消費者)、durable(持久訂閱者) |
| 交易 | tx(交易用戶端)、outbox(交易性寄件匣)、inbox(交易性收件匣)、idempotent(等冪接收器) |
| 韌性 | bulkhead、retry、circuit-breaker — 韌性模式,非 EIP |
邊:
| 邊種類 | 筆畫 | 寬度 | 箭頭 | 標記 |
|---|---|---|---|---|
message(無類型) | 實線 #1e1e1e | 2 | → arrow | 無 |
message type: command | 實線 | 2 | → triangle | «C» |
message type: event | 實線 | 2 | → arrow | «E» |
message type: document | 實線 | 2 | → arrow | «D» |
message type: reply | 虛線 | 2 | → arrow | «R» |
rpc | 實線 | 1 | → arrow | 無 |
data | 點線 | 1 | → arrow | 無 |
tap | 點線 | 1 | circle → arrow | 無 |
dlq | 虛線 #c92a2a | 1 | → arrow | 無 |
control | 虛線 #868e96 | 1 | ┤ bar | 無 |
邊的欄位:from、to、kind、type、message、label、seq、route、correlation、reply_to、ttl、sequence、style、color。節點欄位:id、kind、label、sub、badges、tags、group、lane、col、row、shadow、attach、link。
審查檢查清單
- 存在標題;它命名的是流程,而非整個系統。
- 每條箭頭都標有訊息或呼叫。
- 每條通道都帶有它的種類標籤和金鑰/分區標籤。
- 每條通道的 DLQ 決策都可見。
- 當出現超過 6 種種類時,必須有圖例。
- 建置後沒有留下
warning:。 - 群組框架僅包含它們的成員。
- 最多 20 個節點。
技術堆疊映射
| 技術堆疊 | 繪製方式 |
|---|---|
| Kafka 主題 | pubsub-channel;消費者群組 → competing:N;持久訂閱 → durable |
| RabbitMQ 佇列 | p2p-channel;交換器 → message-broker 或 content-based-router;DLX → dead-letter-channel |
| SQS / SNS | p2p-channel / pubsub-channel |
| EventBridge 規則 | content-based-router |
| Step Functions | process-manager 或 saga |
| Lambda 消費者 | 帶有 event-driven 的 service |
| 資料庫 | datastore;稽核/重播副本 → message-store |
| 合作夥伴 API | external-system,虛線 |
手動編輯
references/excalidraw-format.md 列出了在進行手動編輯後,能保持 Excalidraw 的綁定、文字和框架有效的 JSON 不變項。