Archimaid 是做什么的?
Archimaid 将 ArchiMate 3.2 以 archimate-beta 图表类型的形式添加到 Mermaid。可以用纯文本编写图表,通过 archimaid CLI 检查它们,并将其渲染为 SVG。
工作流程
- 确定视图需要哪些 ArchiMate 元素和关系。通过元素类型和关系来表达含义,而不是通过注释。
- 在
.mmd文件中,或在 Markdown 的围栏mermaid代码块中编写图表。 - 验证并修复每一个错误,然后再次验证:
使用npx --yes archimaid validate path/to/diagram.mmd-可从标准输入验证。问题将以file:line:column: message的格式输出。警告以warning:开头,不会导致运行失败。 - 检查 ArchiMate 3.2 是否允许源和目标类型之间的每种关系(参见附录 B)。验证器目前尚未检查此项。
- 当目标主机无法加载插件时(如 GitHub Markdown),渲染一个 SVG(参见渲染)。
语法
以 archimate-beta 开头,每行一个声明。
archimate-beta
direction LR
accTitle: 订单管理
accDescr: 订单管理套件包含一个计费组件。
element applicationComponent suite "订单管理套件" {
element applicationComponent billing "计费"
}
description billing "处理开票。"
click billing href "https://wiki.example.com/billing" "打开计费手册"
suite *-- billing
note review "确认重试行为" on suite
- 元素:
element <类型> <ID> "名称"。60 个类型键(businessProcess、applicationComponent、node等)列在 references/reference.md 中。如果不确定某个键,请阅读该文件。 - ID: 唯一,以字母或下划线开头,可包含字母、数字、下划线和连字符。
- 字符串: JSON 风格的双引号,绝不能为空。使用
\n表示换行。长名称会自动换行。 - 可访问性: 始终添加
accTitle:。添加accDescr:或accDescr { … }用于多行。 - 前置元数据: 允许在
---行之间放置一个 YAML 块,例如config: { theme: dark }。
关系
简写形式:<源> <连接符> <目标>,可选地后跟 : "标签"。左端点始终是模型的源。
| 连接符 | 关系 |
|---|---|
*-- | 组合 |
o-- | 聚合 |
@==> | 分配 |
..|> | 实现 |
--> | 服务 |
.. / <.. / ..> / <..> | 访问:未指定 / 读取 / 写入 / 读写 |
-.-> | 影响 |
--- / --/ | 关联:无向 / 有向 |
==> | 触发 |
-.=> | 流 |
--|> | 特化 |
manage <.. order表示 manage 读取 order:访问者在左侧。- 语句开头的 ID 不会被解读为
o--字形。请写o o-- b,而不是o--b。 - 不要重复完全相同的简写行。
- 长形式:
relationship <类型> <ID> <源> -> <目标>,可选地后跟access read|write|readWrite|unspecified或directed,然后是label "文本"。当其他声明需要引用关系的 ID 时,请使用长形式。
嵌套
- 在
element … {和}内部声明子元素,每个子元素单独一行。块可以嵌套,并且可以包含元素、描述、关系、注释、nest和click,但不能包含图表设置。 - 嵌套不需要关系。当恰好一个父子关系支持嵌套时,该围栏即代表它,并且该关系行会被隐藏。组合、聚合、分配、实现和访问从父指向子。特化从子指向父。
nest <子> in <父> [via <关系ID>]是行形式。当多个关系可以支持嵌套时,使用via。每个子元素只有一个可视父元素,且嵌套不能形成循环。
注释和链接
note <ID> "文本"声明一个独立注释。追加on <元素ID>可将其附加到一个元素上。注释可以作为关系端点。click <ID> href "<URL>" ["工具提示"] [_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 包含三个完整且有效的图表:
- 订单管理: 分配、实现、服务和读取访问
- 跨层关系: 使用架构布局的嵌套索赔处理
- 嵌套组件: 组合、附加和独立注释、跨边界流