3.1 Mermaid：流程图、时序图与甘特图

3.1 Mermaid：流程图、时序图与甘特图

Mermaid 是写在围栏代码块里的绘图语言，围栏语言标注写 mermaid，渲染器把文本直接变成图。流程图、时序图、状态图、甘特图、饼图、类图、ER 图都能画。对技术文档来说，它是性价比最高的画图方式：源码即图，改图就是改文字。

第一个流程图：五分钟上手

```mermaid
flowchart TD
    A[收到告警] --> B{影响用户吗}
    B -->|是| C[拉起应急响应]
    B -->|否| D[记录并观察]
    C --> E[定位根因]
    E --> F[修复并复盘]
    D --> F
```
​

拆解语法要素：

• 首行声明图型：flowchart TD（TD 是自上而下，LR 自左向右）。
• 节点：A[文字] 方框、B{文字} 菱形判断、C(文字) 圆角框。
• 连线：--> 实线箭头，|标签| 给边加说明。
• 节点 id（A、B、C）只是源码内部名字，渲染显示的是方括号里的文字。

⚠️ 最重要的语法禁忌：节点方括号和边标签里不要出现括号、方括号、花括号、星号、等号、尖括号等符号——它们会被解析器当作语法。要表达"函数式(参数)"就写成中文描述"函数带参数"。这一条占了 Mermaid 渲染失败案例的大半。

时序图：谁在什么时候说了什么

```mermaid
sequenceDiagram
    participant U as 用户
    participant G as 网关
    participant S as 服务
    U->>G: 发起请求
    G->>S: 转发并鉴权
    S-->>G: 返回结果
    G-->>U: 响应
```
​

->> 实线箭头、-->> 虚线箭头（常用于返回）。参与者按声明顺序从左到右排开，消息自上而下即时间轴。排查"接口谁调谁"的问题时，我第一反应就是画一张时序图——比读一百行文字描述快。

状态图与甘特图

状态图适合"一个东西的一生"：

```mermaid
stateDiagram-v2
    [*] --> 草稿
    草稿 --> 评审中: 提交
    评审中 --> 草稿: 驳回
    评审中 --> 已发布: 通过
    已发布 --> [*]
```
​

甘特图适合排期展示：

```mermaid
gantt
    title 迁移计划
    dateFormat YYYY-MM-DD
    section 准备
    方案设计 :a1, 2025-03-01, 7d
    section 实施
    双写与切换 :a2, after a1, 10d
    section 收尾
    旧库下线 :a3, after a2, 3d
```
​

图型的选择纪律与退化信号

会画四种图之后，真正的功夫是选对图以及知道何时不该画。选型的第一问永远是"读者要回答什么问题"：读者问"流程怎么走"画流程图，问"模块谁调谁"画时序图，问"对象有哪些状态"画状态图，问"时间怎么排"画甘特图。图型选错的典型症状是图里出现大量解释性文字——流程图每条边都挂着长标签、时序图的消息写满整句话，这时图已经退化成"用线连起来的段落"，不如老老实实写正文配列表。一张健康的图，节点文字应当短到不需要换行，读者三秒能扫完主干。

规模是另一个纪律点。流程图超过十五个节点、时序图超过六个参与者，读者就再也装不下它的全局结构。超标的治理办法不是缩小字体，而是分层：顶层图只保留主干（五到七个节点），每个节点链接到一张展开的子图——正如文档需要标题分级，图也需要层级。子图之间靠引用对齐（顶层节点名与子图标题一致），读者既能鸟瞰也能下钻。还要记住 Mermaid 的自动布局是黑盒：节点多时连线会交叉重叠，这时手动指定方向（TD 改 LR）、把大图拆小，比反复微调文字长度有效得多。图和正文一样怕臃肿，删掉一个不承载信息的节点，价值常常大于加十条注释。

本节要点回顾

• 围栏标 mermaid，首行声明图型：flowchart / sequenceDiagram / stateDiagram-v2 / gantt。
• 节点与边标签里禁用括号星号等符号，公式和代码名改中文描述。
• 选图先问问题：分支答流程、调用答时序、生命周期答状态、工期答甘特。
• 源码即图：图的修改进版本历史，这是 Mermaid 相对图片文件的根本优势。

版式与可读性：让图在小屏幕上也能看

Mermaid 图最常见的失败不是语法错，而是长出来：节点标签太长、层级太多，渲染出来的图在移动端缩成蚂蚁。三条版式纪律能解决大部分问题。第一，节点标签控制在十二个字以内，长说明移到正文；第二，流程图方向用左到右（LR）而非上到下（TD），除非层级特别深——LR 图在窄屏上的横向滚动比 TD 图的纵向压缩可读性好；第三，子图分组：超过十个节点的图用 subgraph 划区，读者先看区再看节点。动手改一张溢出图：

分组后即使整体仍有十几个节点，视觉结构也已经两级化。此外，时序图的 participant 数量以五个为限，超过时拆成两张视角不同的图（比如"写路径"与"读路径"各一张），比一张大图糊脸好得多。

甘特图的实际用法与日期语法

甘特图在技术文档里最有价值的场景是发布计划与迁移窗口。一段可直接改用的骨架：

三个语法点：done/active 标状态；after a1 建立依赖而非写死日期；日期格式必须与 dateFormat 声明一致。甘特图维护成本高于流程图（日期要持续更新），纪律是只在计划仍活跃时维护，项目结束后把甘特图替换成一张时间线表格存档，避免文档里留着一张日期早已过期的"僵尸计划"。