外观
Mermaid 快速入门指南
解释一次下单请求时,文字容易把处理步骤、服务调用和订单状态混在一起。Mermaid 可以用文本描述这些关系,再由渲染器生成图表。渲染器就是把图表源码转换成可视图形的组件;只有 Markdown 编辑器或文档平台集成了它,代码块才会显示为图。
Mermaid 的基本用法是:选择图表类型,定义图中的对象,再描述对象之间的关系。布局由工具处理,你主要维护关系和文字。源码可以和文档一起放进代码仓库,便于比较修改和评审。
学习后端开发时,可以先用流程图说明“有哪些步骤和分支”,再用时序图说明“谁先调用谁”。类图、状态图和实体关系图分别关注对象结构、状态变化和数据关系,按需要学习即可。
1. 先画出第一张图
在支持 Mermaid 的 Markdown 编辑器中,输入下面的代码块。围栏后的 mermaid 标记告诉编辑器,这一块内容是图表源码:
markdown
```mermaid
flowchart LR
A[提出需求] --> B[设计方案]
B --> C[编码实现]
C --> D[测试上线]
```预期图示如下:
图表将在阅读到此处时加载…
先读懂这张流程图:A[提出需求] 定义一个节点,其中 A 是源码中引用它的标识符,方括号中的文字是读者看到的标签;A --> B 定义从 A 指向 B 的连线。这里的连线表示步骤的先后关系。
一段 Mermaid 代码通常先声明图表类型,再描述内容。以流程图为例:
- 第一行声明图表类型和方向,如
flowchart LR。 - 后续内容定义节点、关系和样式。
下面的方向用于流程图布局,不是所有图表类型通用的参数:
| 写法 | 含义 |
|---|---|
LR | 从左到右,适合业务流程和系统链路 |
RL | 从右到左 |
TB / TD | 从上到下,适合层级较深的流程 |
BT | 从下到上 |
2. 流程图 Flowchart
流程图用节点表示处理步骤或判断,用连线表示流向。先确定要表达的业务路径,再选择形状和连线,避免只有方框却看不出流程。
2.1 节点形状
查看 Mermaid 源码
markdown
```mermaid
flowchart LR
A[矩形:处理步骤]
B(圆角:开始或结束)
C{菱形:条件判断}
D[(圆柱:数据库)]
E((圆形:连接点))
F[[子流程]]
```图表将在阅读到此处时加载…
对应语法:
text
A[矩形]
B(圆角矩形)
C{菱形}
D[(数据库)]
E((圆形))
F[[子流程]]同一张图中,用简短稳定的 ID 引用节点,例如 pay[支付服务] 中的 pay。显示文字负责说明含义,ID 负责连接关系;修改标签时,也更容易保持连线不变。上面的形状用途是建模约定,矩形或圆柱本身不会执行处理或数据库操作。
2.2 连线与文字
连线文字说明这条路径在什么条件下发生。下面用“库存充足”和“库存不足”区分两条分支;虚线与粗线用于视觉区分,具体业务含义需要通过文字或图例说明。
查看 Mermaid 源码
markdown
```mermaid
flowchart LR
A[提交订单] --> B[校验库存]
B -->|库存充足| C[创建订单]
B -.->|库存不足| D[返回提示]
C ==> E[发起支付]
```图表将在阅读到此处时加载…
常用连线:
text
A --> B 实线箭头
A --- B 实线,无箭头
A -.-> B 虚线箭头
A ==> B 粗线箭头
A -->|说明文字| B 带文字的连线2.3 分组 subgraph
subgraph 是子图,用来把一组节点放进同一个边界,end 结束分组。下面将客户端和服务端分开,便于看出请求从哪里进入系统,以及哪些组件属于服务端。分组表达的是图中的边界,不会自动决定实际部署方式。
查看 Mermaid 源码
markdown
```mermaid
flowchart LR
subgraph Client[客户端]
Web[Web]
App[App]
end
subgraph Server[服务端]
API[API 网关]
Order[订单服务]
DB[(数据库)]
end
Web --> API
App --> API
API --> Order --> DB
```图表将在阅读到此处时加载…
3. 时序图 Sequence Diagram
时序图适合描述接口调用、用户交互和服务间协作。横向排列的是参与者,例如前端、订单服务和数据库;消息从上到下排列,表示交互的先后顺序。因此,它能解释调用顺序,但不能仅凭图上的距离推断耗时。
查看 Mermaid 源码
markdown
```mermaid
sequenceDiagram
autonumber
actor User as 用户
participant Web as 前端
participant API as 订单服务
participant DB as 数据库
User->>Web: 提交订单
Web->>API: POST /orders
activate API
API->>DB: 保存订单
DB-->>API: 保存成功
API-->>Web: 返回订单号
deactivate API
Web-->>User: 展示下单结果
```图表将在阅读到此处时加载…
在这个下单示例中,前端先请求订单服务,订单服务保存数据后返回订单号。参与者下方的竖线称为生命线,表示它在交互过程中的存在;activate 和 deactivate 标出处理活动的区间。
常用语法如下。示例约定实线消息表示请求、虚线消息表示响应:
text
participant A as 系统 A 定义参与者
actor U as 用户 定义人物角色
A->>B: 请求 实线请求
B-->>A: 响应 虚线响应
activate B 激活生命线
deactivate B 结束激活
autonumber 自动添加消息序号理解单条调用链后,再用块结构表达不同路径:alt / else 表示条件分支,loop 表示重复交互,par / and 表示并行交互,每个块由 end 结束。下面的“每 30 秒”是循环说明,不会让 Mermaid 实际启动定时任务。
查看 Mermaid 源码
markdown
```mermaid
sequenceDiagram
participant C as 客户端
participant S as 服务端
C->>S: 请求数据
alt 登录有效
S-->>C: 返回数据
else 登录失效
S-->>C: 返回 401
end
loop 每 30 秒
C->>S: 发送心跳
end
par 查询订单
C->>S: 查询订单
and 查询消息
C->>S: 查询消息
end
```图表将在阅读到此处时加载…
其他常用块:opt 表示可选步骤,critical 表示关键区段,break 表示中断流程。
4. 类图 Class Diagram
类图描述类的属性、方法和类之间的关系。领域模型是对业务概念及其关系的表示,例如订单包含订单项、订单处理需要支付服务。它关注结构,不表达一次请求的调用先后;只列与当前问题有关的成员,避免把类图变成字段清单。
查看 Mermaid 源码
markdown
```mermaid
classDiagram
class Order {
+Long id
+OrderStatus status
+pay() void
+cancel() void
}
class OrderItem {
+Long productId
+int quantity
+calculateAmount() Decimal
}
class PaymentService {
<<interface>>
+pay(Order order) PaymentResult
}
Order "1" *-- "1..*" OrderItem : 包含
Order ..> PaymentService : 使用
```图表将在阅读到此处时加载…
示例中,class Order 定义订单类,花括号内列出属性和方法;<<interface>> 标记支付服务是接口。关系两端的数字称为多重性,表示关联对象的数量:"1" *-- "1..*" 在这里表达一个订单包含一个或多个订单项。
这些是模型描述,不是可执行的业务代码。OrderStatus、Decimal 和 PaymentResult 等名称用于表达类型,具体定义由业务实现决定。
常见关系:
| 语法 | 关系 |
|---|---|
| `A < | -- B` |
A *-- B | 组合:B 的生命周期依赖 A |
A o-- B | 聚合:A 包含 B,但 B 可独立存在 |
A --> B | 关联 |
A ..> B | 依赖 |
| `A .. | > B` |
可见性符号:+ 公开、- 私有、# 受保护、~ 包级可见。
5. 状态图 State Diagram
状态图适合表达订单、工单、任务等对象的生命周期,也就是对象从创建到结束经历的状态变化。流程图关注“做什么”,状态图关注“对象当前处于什么状态,以及什么事件使它改变”。
查看 Mermaid 源码
markdown
```mermaid
stateDiagram-v2
[*] --> 待支付
待支付 --> 已支付: 支付成功
待支付 --> 已取消: 用户取消
待支付 --> 已关闭: 支付超时
已支付 --> 配送中: 商家发货
配送中 --> 已完成: 用户签收
已取消 --> [*]
已关闭 --> [*]
已完成 --> [*]
```图表将在阅读到此处时加载…
[*] 出现在起始箭头一端时表示起点,出现在结束箭头一端时表示终点。示例中,“支付成功”使订单从“待支付”转为“已支付”。建议在连线上标明触发事件,节点只写状态,清楚区分“现在是什么”与“为什么发生变化”。
6. 实体关系图 ER Diagram
ER 是 Entity Relationship(实体关系)的缩写。实体是要描述的业务对象,例如用户和订单;在数据库设计中,可以用 ER 图说明表之间的关系。它关注数据如何关联,不描述请求的执行顺序。
下面的字段按“类型、名称、约束标记”排列:PK 表示主键,FK 表示外键,UK 表示唯一键。它们是图中的说明,不会在数据库中创建约束;bigint、string 等也是图中的类型描述,不是一套可直接执行的建表语句。
查看 Mermaid 源码
markdown
```mermaid
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
PRODUCT ||--o{ ORDER_ITEM : referenced_by
USER {
bigint id PK
string name
string email UK
}
ORDER {
bigint id PK
bigint user_id FK
string status
}
ORDER_ITEM {
bigint order_id FK
bigint product_id FK
int quantity
}
```图表将在阅读到此处时加载…
基数表示关系一端允许关联多少个实体。读两端符号,才能区分“每个订单必须属于一个用户”和“用户可以没有订单”:
| 符号 | 含义 |
|---|---|
| ` | |
| `o | ` |
| ` | {` |
o{ | 零个或多个 |
关系由两端组合而成,例如 USER ||--o{ ORDER 表示:一个用户可以有零到多个订单,每个订单属于一个用户。
7. 甘特图 Gantt
甘特图把任务放在时间轴上,适合展示项目计划和任务依赖。下面是一份示例计划:dateFormat 指定输入日期格式,axisFormat 指定时间轴标签格式,section 将任务按阶段分组。
查看 Mermaid 源码
markdown
```mermaid
gantt
title 新功能交付计划
dateFormat YYYY-MM-DD
axisFormat %m-%d
section 设计
需求确认 :done, req, 2026-09-21, 2d
技术方案 :active, design, after req, 3d
section 开发
后端开发 :backend, after design, 5d
前端开发 :frontend, after design, 4d
section 交付
联调测试 :test, after backend, 3d
正式上线 :milestone, release, after test, 0d
```图表将在阅读到此处时加载…
常用任务标记包括 done(已完成)、active(进行中)、crit(关键任务)和 milestone(里程碑)。例如 after design, 5d 表示在 design 任务之后安排一个持续 5 天的任务。用 ID 表达依赖,前置任务调整时就不必逐项手算后续开始日期。
这份计划让前后端开发都依赖技术方案,但联调测试只写了 after backend。如果联调必须等待前后端都完成,计划中也应表达这一条件,不能仅从任务名称推断依赖。
8. 饼图与思维导图
8.1 饼图
饼图用扇区表示各分类相对总量的占比。下面的数字是示例数据;showData 用于显示数值,不代表实际缺陷统计。
查看 Mermaid 源码
markdown
```mermaid
pie showData
title 缺陷类型分布
"业务逻辑" : 42
"接口问题" : 28
"页面样式" : 18
"其他" : 12
```图表将在阅读到此处时加载…
饼图只适合展示少量分类的占比。分类过多时,表格或柱状图通常更容易阅读。
8.2 思维导图
思维导图把主题组织成树状层级,适合整理知识分类。下面从根主题 Mermaid 展开用途,而不是表示这些图表之间存在调用或执行关系。
查看 Mermaid 源码
markdown
```mermaid
mindmap
root((Mermaid))
流程建模
流程图
状态图
系统设计
时序图
类图
ER 图
项目管理
甘特图
```图表将在阅读到此处时加载…
思维导图主要依靠缩进表示层级,混用 Tab 和空格可能导致结构错误。
9. 如何画得更优雅
9.1 先选对图,再开始画
| 想表达的内容 | 推荐图表 |
|---|---|
| 步骤、分支、处理链路 | 流程图 |
| 谁在什么时间调用谁 | 时序图 |
| 对象结构与关系 | 类图 |
| 状态和状态迁移 | 状态图 |
| 数据表关系 | ER 图 |
| 时间、进度和任务依赖 | 甘特图 |
一张图只回答一个核心问题。不要试图用一张“万能架构图”同时说明业务流程、部署结构和接口时序。
9.2 使用有含义的 ID
推荐:
text
gateway[API 网关] --> orderService[订单服务]不推荐:
text
A[API 网关] --> B[订单服务]图变大以后,有含义的 ID 更容易搜索和修改。简单的教学示例使用 A、B 没问题,正式文档应尽量使用稳定名称。
9.3 控制节点数量
可以先把一张图控制在 5~15 个主要节点,作为便于阅读的起点,而不是语法限制。节点和连线增多后,读者需要反复追踪关系,此时可以:
- 使用
subgraph按模块分组; - 拆成“全景图 + 局部详图”;
- 隐藏与当前主题无关的实现细节;
- 用连线文字解释关系,而不是增加说明节点。
9.4 让方向符合阅读习惯
- 业务步骤和调用链优先使用
LR; - 组织结构、分层架构和决策树优先使用
TB; - 同一篇文档中的同类图尽量保持相同方向;
- 避免大量交叉线,必要时调整节点顺序或拆图。
9.5 克制地使用颜色
颜色应传递含义,而不只是装饰。比如统一约定:蓝色表示正常处理,绿色表示成功,红色表示异常。
查看 Mermaid 源码
markdown
```mermaid
flowchart LR
Start([开始]) --> Check{校验通过?}
Check -->|是| Success[继续处理]
Check -->|否| Error[返回错误]
classDef normal fill:#e8f1ff,stroke:#3975c6,color:#17365d
classDef success fill:#e8f7ee,stroke:#2e8b57,color:#185c37
classDef danger fill:#fff0f0,stroke:#d14b4b,color:#8b1e1e
class Start,Check normal
class Success success
class Error danger
```图表将在阅读到此处时加载…
classDef 定义可复用样式,class 将样式应用到节点。例如 class Success success 把成功样式应用到 Success 节点。fill、stroke、color 分别设置填充、边框和文字颜色。先定义正常、成功、异常等少量语义,再统一使用颜色,读者才不必为每张图重新猜测含义。
9.6 用配置统一主题
节点样式控制局部外观,主题配置控制整体外观。在支持初始化配置的渲染环境中,可以在图表开头使用下面的写法;themeVariables 是主题变量,用于集中设置颜色和字体:
markdown
```mermaid
%%{init: {
"theme": "base",
"themeVariables": {
"primaryColor": "#e8f1ff",
"primaryTextColor": "#17365d",
"primaryBorderColor": "#3975c6",
"lineColor": "#64748b",
"fontFamily": "Arial, Microsoft YaHei, sans-serif"
}
}}%%
flowchart LR
A[需求] --> B[设计] --> C[实现]
```常见主题有 default、neutral、dark、forest 和 base。其中 base 最适合通过 themeVariables 自定义。
注意:部分平台会出于安全或兼容性考虑,限制初始化配置和 HTML 标签。
9.7 使用注释记录设计意图
以 %% 开头的行是注释:
text
%% 这里只展示主链路,重试和补偿流程见另一张图
flowchart LR
A --> B注释不会显示在最终图中,但能帮助后续维护者理解取舍。
10. 常见问题
10.1 文字包含特殊字符时报错
当文字中包含括号、冒号等特殊字符时,用双引号包裹文字:
text
A["调用接口(异步)"]
B{"状态 == SUCCESS?"}10.2 中文节点无法正常显示
先检查源码中的中文是否正常,再检查渲染环境是否有可用的中文字体。若文字显示为方框,字体是一个排查方向。可以在主题配置中指定候选字体,但指定名称不会安装字体,最终是否生效仍取决于运行环境。下面是配置片段,需要放入完整配置中:
text
"fontFamily": "Microsoft YaHei, PingFang SC, sans-serif"10.3 在某个平台中无法渲染
不同平台支持的 Mermaid 版本不同,新图表类型或新语法可能不可用。遇到问题时:
- 先在 Mermaid Live Editor 验证语法;
- 查看目标平台支持的 Mermaid 版本;
- 尽量使用稳定、基础的语法;
- 必要时导出 SVG 或 PNG 后插入文档。
在线编辑器能渲染,只能说明它所使用的环境支持这段源码,不能保证目标平台也支持。还应区分“整个 Mermaid 代码块未被识别”和“某种语法解析失败”:前者先检查平台集成,后者再检查版本与语法。SVG 是矢量图,PNG 是位图;导出图片适合无法直接渲染 Mermaid 的文档环境。
10.4 图太宽或布局混乱
- 将
LR改为TB; - 缩短节点文字,把详细解释移到正文;
- 使用
subgraph分组; - 调整语句顺序,Mermaid 会参考定义顺序布局;
- 拆成多张各有主题的小图。
11. 可直接复用的模板
下面三份模板分别描述业务路径、接口交互和系统分层。复用时先替换业务名称,再核对分支、状态码和组件关系是否符合实际系统;图表用于说明设计,不会执行业务逻辑。
11.1 带异常分支的业务流程
查看 Mermaid 源码
markdown
```mermaid
flowchart LR
Start([开始]) --> Validate{参数有效?}
Validate -->|否| Reject[返回参数错误]
Validate -->|是| Process[执行业务处理]
Process --> Result{处理成功?}
Result -->|是| Success[返回成功结果]
Result -->|否| Error[记录异常并返回失败]
Reject --> End([结束])
Success --> End
Error --> End
```图表将在阅读到此处时加载…
11.2 REST 接口调用时序
REST 是一种 Web 接口设计风格;这里用 HTTP 请求与响应展示客户端、API 服务和数据库的交互。模板用 200 表示成功,用 4xx/5xx 表示客户端或服务端错误类别。实际状态码和响应体应由接口契约决定,不能把所有成功响应都固定为 200。
查看 Mermaid 源码
markdown
```mermaid
sequenceDiagram
autonumber
actor User as 用户
participant Client as 客户端
participant API as API 服务
participant DB as 数据库
User->>Client: 发起操作
Client->>API: HTTP 请求
activate API
API->>DB: 查询或写入数据
DB-->>API: 返回结果
alt 处理成功
API-->>Client: 200 + 响应数据
Client-->>User: 展示成功结果
else 处理失败
API-->>Client: 4xx/5xx + 错误信息
Client-->>User: 展示错误提示
end
deactivate API
```图表将在阅读到此处时加载…
11.3 简洁的系统架构图
查看 Mermaid 源码
markdown
```mermaid
flowchart TB
subgraph Access[接入层]
Web[Web 客户端]
App[移动端]
end
subgraph Service[服务层]
Gateway[API 网关]
UserService[用户服务]
OrderService[订单服务]
end
subgraph Data[数据层]
Cache[(缓存)]
DB[(数据库)]
end
Web --> Gateway
App --> Gateway
Gateway --> UserService
Gateway --> OrderService
UserService --> Cache
UserService --> DB
OrderService --> DB
```图表将在阅读到此处时加载…
12. 快速入门路线
可以安排约 20 分钟完成第一轮练习,先熟悉基本写法,再按需要扩展:
- 用
flowchart LR画一个包含判断分支的业务流程; - 用
sequenceDiagram画一次前端、后端和数据库的调用; - 用
subgraph给流程图划分系统边界; - 用
classDef定义正常、成功、异常三种样式; - 根据实际需要再学习类图、状态图、ER 图或甘特图。
记住三个原则就已经足够开始:选对图、少放内容、统一语义。Mermaid 的价值不在于画得复杂,而在于让图表像代码一样容易编写、评审和持续更新。