Mermaid.js 架构图语法与布局指南

架构图提供了一个结构化的蓝图，供系统架构师和 DevOps 团队用来可视化基础设施设置、云微服务以及结构布局配置。基于 architecture-beta 引擎，这个基于文本的工具通过自动排列结构服务组、数据库集群、网关和边缘路径，将其转化为清晰且可预测的系统布局，取代了手动拖拽操作。

基本语法结构

每个图表都以 architecture-beta 声明头开始。您可以通过使用 service 关键字定义单个节点元素，并通过指定精确的方向坐标端口（T上，B下，L左，R右）通过冒号和双连字符分隔。

Mermaid 在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
architecture-beta
  service gateway(internet)[网关标签]
  service server(server)[应用服务器]
  
  gateway:B -- T:server
Edit Mermaid in VPasCode
在 VPasCode 中编辑 Mermaid

语法参考

下表分解了在 Mermaid.js 中构建架构工作区地图所使用的主数据组件、格式化关键字和连接器属性。

语法组件 类型要求 描述与使用规则
声明 关键字标识符 初始化基础设施映射工作区画布。必须使用确切的 架构-beta 块。
服务节点 关键字 + 身份块 声明一个架构实体。使用语法：service id(icon)[显示标签].
组包装器 容器关键字 将相关服务分组到一个视觉容器中。使用语法：group id(icon)[组标签].
In 关键字 赋值修饰符 显式地将一个服务节点分配到特定声明的组包装器内：service id(icon)[标签] in groupId.
连接节点 关键字标识符 建立一个结构对齐的中心点，用于整洁地路由复杂的多方向连接路径：junction id.
连接边 端口方向操作符 通过将连接固定到特定节点边（T、B、L、R）来配置方向追踪路径：source:side -- side:target。支持方向箭头尖端（-->).

高级分组与端口边缘路由

为了精确控制链接在元素之间传输的方式而不显得杂乱，架构引擎需要显式的端口绑定。相关的节点可以组织在结构组内，以明确系统的边界。

1. 精确端口绑定规则

您通过在相应节点标识符后附加冒号和边缘方向标志来定义连接线离开和进入组件的位置（”T, B, L, R) 来指定相应的节点标识符：

  • db:R -- L:server：连线从数据库的**右侧**离开，并以一条直线水平进入服务器的**左侧**。
  • db:T -- L:server：连线从数据库的**顶部**离开，并自动以一个干净的90°弯角进入服务器的**左侧**。
  • src:B --> T:proc：连线从源节点的**底部**离开，并向下延伸进入处理器的**顶部**，带有方向箭头。

2. 使用组来构建系统

要声明一个视觉组（例如虚拟私有云或数据库集群），请使用 group关键字，并通过 in修饰符将节点分配给它：

Mermaid 在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
architecture-beta
  group cloudNetwork(cloud)[私有云]
    service auth(server)[认证节点] in cloudNetwork
    service api(server)[API端点] in cloudNetwork
Edit Mermaid in VPasCode
在 VPasCode 中编辑 Mermaid

对齐同级元素（v11.16.0+）

当多个不同的服务共享相同的边缘路由路径时（例如，三个解耦的数据源同时流入一个消息工作者），布局算法有时会将它们聚集在一起。使用 align row 和 对齐列指令强制引擎将这些同级元素均匀分布在特定的轴线上。

Mermaid 在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
architecture-beta
  服务 src1(server)[源 1]
  服务 src2(server)[源 2]
  服务 proc(server)[处理器中心]

  src1:B --> T:proc
  src2:B --> T:proc

  对齐行 src1 src2
Edit Mermaid in VPasCode
在 VPasCode 中编辑 Mermaid

现实世界蓝图：微服务集群蓝图

此蓝图展示了高度可靠、企业级的云架构。通过将主 API 引擎置于中心，并将认证和异步任务水平向两侧分支，布局利用对称设计原则避免线条重叠。整个数据流从公共网关可预测地下行至整齐对齐的数据存储层，利用双重对齐行指令将组件锁定在清晰、可预测的水平轨道上。

Mermaid 在 VPasCode 中编辑 Mermaid
Mermaid Edit Mermaid in VPasCode 
architecture-beta
  标题 "高可用性微服务架构"

  %% 外部入口层
  服务 cloudflare(internet)[Cloudflare WAF]
  服务 alb(server)[AWS 应用负载均衡器]

  %% 核心应用集群
  组 appCluster(cloud)[托管 EKS 微服务]
    服务 authService(server)[认证服务] 在 appCluster
    服务 apiService(server)[核心 API 引擎] 在 appCluster
    服务 workerNode(server)[异步任务工作节点] 在 appCluster

  %% 受保护的存储层
  组 dataCluster(database)[受保护的数据层]
    服务 redis(disk)[Redis 缓存集群] 在 dataCluster
    服务 postgres(database)[PostgreSQL 主节点] 在 dataCluster

  %% 1. 垂直流：流量从公网向下进入计算核心
  cloudflare:B --> T:alb
  alb:B --> T:apiService

  %% 2. 水平流：核心 API 对称地向左和向右分支
  apiService:L --> R:authService
  apiService:R --> L:workerNode

  %% 3. 基线流：应用工作节点直接下落到各自的数据槽位
  authService:B --> T:redis
  workerNode:B --> T:postgres

  %% 布局轴对齐以实现完美网格
  对齐行 authService apiService workerNode
  对齐行 redis postgres
Edit Mermaid in VPasCode
在 VPasCode 中编辑 Mermaid

常见语法陷阱与系统限制

编写基础设施代码时，请牢记这些特定的配置验证规则，以防止解析错误：

  • 标签方括号顺序： 显示文本字符串必须使用方括号 [标签文本] 并直接跟随图标括号，中间不加空格：服务 id(server)[文本] 是正确的。在括号内使用引号将导致解析器失效。
  • 端口大小写敏感： 连接边端口锚点必须使用大写字母书写（T, B, L, R).小写字母（t, b, l, r) 无法识别，会导致布局生成崩溃。
  • 前置声明规则： 边路径语句中使用的每个节点或连接点标识符都必须在它上方的单独一行中显式声明。连接到隐式节点名称将无法构建。
  • 对齐成员限制： 使用 对齐行 或 对齐列 对齐定位指令时，必须在命令行中提供至少两个或更多有效且先前声明的服务或连接点标识符。
滚动至顶部