Archimaid 是做什麼的?
Archimaid 將 ArchiMate 3.2 新增至 Mermaid,成為 archimate-beta 圖表類型。以純文字編寫圖表、使用 archimaid CLI 進行檢查,並將其渲染為 SVG。
工作流程
- 決定檢視所需的 ArchiMate 元素與關係。使用元素類型和關係來建模意義,而非使用註解。
- 在
.mmd檔案中或 Markdown 的圍欄式mermaid區塊中編寫圖表。 - 驗證它並修正所有錯誤,然後再次驗證:
使用npx --yes archimaid validate 路徑/至/圖表.mmd-驗證標準輸入。問題會以檔案:行數:欄數: 訊息的格式印出。警告以warning:開頭且不會導致執行失敗。 - 檢查 ArchiMate 3.2 是否允許每條關係在其來源與目標類型之間(附錄 B)。驗證器目前尚未檢查此項。
- 當目標主機無法載入外掛時,例如 GitHub Markdown(請參閱渲染),則渲染 SVG。
語法
以 archimate-beta 開頭,每一行放置一個宣告。
archimate-beta
direction LR
accTitle: 訂單管理
accDescr: 訂單管理套件包含一個帳務元件。
element applicationComponent 套件 "訂單管理套件" {
element applicationComponent 帳務 "帳務"
}
description 帳務 "處理發票。"
click 帳務 href "https://wiki.example.com/billing" "開啟帳務手冊"
套件 *-- 帳務
note review "確認重試行為" on 套件
- 元素:
element <類型> <識別碼> "名稱"。60 個類型鍵(businessProcess、applicationComponent、node等)列於 references/reference.md 中。每當不確定某個鍵時,請閱讀該文件。 - 識別碼: 唯一,以字母或底線開頭,並包含字母、數字、底線和連字號。
- 字串: JSON 風格的雙引號,絕不能為空。使用
\n表示換行。長名稱會自動換行。 - 無障礙功能: 務必加入
accTitle:。加入accDescr:,或使用accDescr { … }表示多行內容。 - Frontmatter: 允許以
---行包圍的前置 YAML 區塊,例如config: { theme: dark }。
關係
簡寫形式:<來源> <連接符> <目標>,可選擇性地加上 : "標籤"。左端點永遠是模型的來源。
| 連接符 | 關係 |
|---|---|
*-- | 組成 |
o-- | 聚合 |
@==> | 指派 |
..|> | 實現 |
--> | 服務 |
.. / <.. / ..> / <..> | 存取:未指定 / 讀取 / 寫入 / 讀寫 |
-.-> | 影響 |
--- / --/ | 關聯:無向 / 有向 |
==> | 觸發 |
-.=> | 流程 |
--|> | 特殊化 |
manage <.. order表示 manage 讀取 order:存取者在左側。- 陳述式開頭的識別碼不會被解讀為
o--字形。請寫o o-- b,而非o--b。 - 不要重複相同的簡寫行。
- 長形式:
relationship <類型> <識別碼> <來源> -> <目標>,可選擇性地接著access read|write|readWrite|unspecified或directed,然後label "文字"。當另一個宣告必須參考該關係的識別碼時,請使用長形式。
巢狀結構
- 在
element … {和}內部宣告子元素,每個子元素各佔一行。區塊可以巢狀,並可包含元素、描述、關係、註解、nest和click,但不能包含圖表設定。 - 巢狀結構不需要關係。當恰好有一個父子關係支援巢狀結構時,該封閉區域代表該關係,且其連線會被隱藏。組成、聚合、指派、實現和存取的指向是從父元素到子元素。特殊化則是從子元素指向父元素。
nest <子元素> in <父元素> [via <關係識別碼>]是線條形式。當多個關係可能支援巢狀結構時,使用via。每個子元素只有一個視覺上的父元素,且巢狀結構不得形成循環。
註解與連結
note <識別碼> "文字"宣告一個獨立註解。附加on <元素識別碼>可將其附加至元素。註解可以作為關係的端點。click <識別碼> href "<網址>" ["工具提示"] [_blank|_self|_parent|_top]連結一個元素。URL 必須是 http、https、mailto 或相對路徑。若無工具提示,懸停時會顯示description。
版面配置
- 預設,或
layout architecture:由上至下的層次(策略、業務、應用、技術與實體、實施與遷移),動機層則靠近與其連接的項目附近。較適合跨層視圖。 layout framework:相同的層次,但具有固定的被動結構、行為與主動結構欄位,動機層在右側。layout graph,或獨立的direction TB|BT|LR|RL:由關係驅動的放置方式。較適合小型單層視圖與鏈狀結構。
超出範圍
不支援接合點、作為端點的關係、替代圖形、視點和模型交換。請勿為它們發明語法。告知使用者並使用最接近的受支援結構。
渲染
渲染需要在專案中安裝 Playwright Chromium:
npm install --save-dev archimaid mermaid playwright
npx playwright install chromium
npx archimaid render diagram.mmd diagram.svg --theme default --background theme
對於未註冊此外掛的主機(GitHub、GitLab),請將 .mmd 原始碼提交至 SVG 旁,並嵌入 SVG:。
對於網頁,請使用 Mermaid 12.3 或更新版本註冊此外掛:
import mermaid from 'mermaid';
import { archimate } from 'archimaid';
mermaid.initialize({ startOnLoad: false, securityLevel: 'strict' });
await mermaid.registerExternalDiagrams([archimate]);
若要快速與使用者檢查語法,請引導他們前往瀏覽器遊樂場:https://try.archimaid.org
範例
references/examples.md 包含三個完整且有效的圖表:
- 訂單管理: 指派、實現、服務與讀取存取
- 跨層關係: 架構佈局,包含巢狀的索賠處理
- 巢狀元件: 組成、附加與獨立註解、跨邊界流程