Mermaid.js 语法基础

在深入研究复杂的流程图或时序时间线等特定架构布局之前，理解控制它的基础规则至关重要Mermaid 手册Mermaid 依赖于一种简洁且高度直观的文本标记系统。一旦你理解了引擎如何初始化画布类型、命名结构组件以及路由方向箭头，编写任何复杂的系统布局都会变得完全自然。

本快速入门涵盖了适用于 VPasCode 工作区中几乎所有 Mermaid 图表类型的全局结构语法机制。

1. 必须的图表类型包装器

Mermaid 代码的每一行块都必须在第一行明确声明其图表类型。这告诉 VPasCode 解析器在预览画布中启动哪个结构引擎：

  • graph TD — 指定从上到下的流程图布局。
  • sequenceDiagram — 指定按时间顺序运行的时序图。
  • classDiagram — 指定结构化的面向对象软件蓝图。

与其他文本转图表引擎不同，Mermaid 不需要尾部结束标签。解析器只需读取第一行的结构声明，并编译代码块容器中直接嵌套在其下方的所有内容。

2. 声明元素：ID 与显示标签

在建模软件系统时，你将创建各种结构元素，如组件、数据库或微服务。在 Mermaid 中，你通过定义一个简短的内部字母数字 ID，紧接着是控制其视觉形状的方括号样式，以及一个用户友好的显示名称来声明一个元素：

microservice_id[支付处理 API]
db_id[(用户交易 SQL)]

为什么这是最佳实践： 使用简短、清晰的内部 ID（例如microservice_id）可以让你在后续绘制关系线时快得多。如果你需要将面向客户的标签从“支付处理 API”更改为“全球结账服务”，你只需在声明该标签的单行中修改即可，而无需在脚本的数十行中逐一更新。

3. 掌握关系箭头与方向路由

系统节点之间的连接使用连字符（-）、等号（=）和箭头括号（>）的组合来绘制。你的线条样式会隐式地控制自动布局引擎如何缩放你的图表：

  • A --> B 绘制一个标准的有向箭头，从元素 A 直接指向元素 B。
  • A --- B 绘制一条平直的无方向连接线，没有箭头，非常适合简单的关联关系。
  • A -.-> B 创建一个虚线依赖关系，这是表示异步依赖或网络 Webhook 的行业标准。
  • A ==> B 创建一条粗体连接线，非常适合突出显示主要的数据处理路径或关键基础设施连接。

4. 内联添加上下文：标签和代码注释

清晰的文档很大程度上依赖于在你的视觉连线和文本脚本周围添加适当的上下文：

为连接线添加标签

你可以通过在两组破折号之间插入文本字符串，或者在关系映射后附加管道字符（”|Text|）来直接在任意连接线上添加解释性文本：

client_id -- "HTTPS POST /v1/checkout" --> api_id
client_id --> |HTTPS POST /v1/checkout| api_id

编写代码注释

如果你想在脚本文件中留下管理备注、设计署名或架构说明，而不在画布上渲染出视觉框，可以使用双百分号（%%）。这会告诉引擎完全跳过对该行的解析：

%% TODO: 一旦 DevOps 迁移完成，我们需要更新这个边界框
[遗留单体] --> [新微服务]
滚动至顶部