# 交接那天，架构图为什么总是过时

> Mermaid 把图表写成文本放进代码仓库，流水线步骤和对应的图在同一个 PR 里一起改。

原文: https://fdetimes.net/zh/tools/mermaid-data-flow-diagrams-handover/

离交接还有两周，打开设计文档，却发现架构图还是第一次研讨会时截的图。图上有一个早已弃用的队列，还有一个客户已经改了名的 API。源文件存在一位已离开项目的同事的笔记本上，没人能改。

Mermaid 的作者把这个问题直接写进了官方仓库：画图和写文档会耗掉开发者宝贵的时间，而且很快就会过时。

Mermaid 由瑞典软件架构师 Knut Sveidqvist 于 2014 年创建，初衷是让写文档更轻松。它的核心至今仍以 MIT 许可证开源。

对前线部署工程师（FDE）来说，这是日常工作。进入客户的系统，打通数据，搭建 Agent 或数据管道，然后离开。剩下的运维由客户的工程团队自己负责，而他们能理解的只有交接文档里写了的内容。

## 为什么文本图表更耐用？

Mermaid 读取类 Markdown 的文本描述并据此生成图表：文本改了，图也跟着变。不需要单独维护图片或设计文件，图表就是和代码放在同一个仓库里的几行文本。

GitHub 可以在 issue、Discussions、pull request、wiki 和 Markdown 文件中渲染 Mermaid 图表，而设计文档和交接 README 恰好就放在这些地方。同事修改某个处理步骤时，会在同一个 pull request 里更新对应的描述行，评审者在一个 diff 里就能看到两处改动。

**要点:** 放在代码旁边的图会随代码一起更新；存成图片的图只会被遗忘。

## 一条数据流，六行文本

假设要为一家物流公司的运营团队部署一个问答助手。数据每晚从 ERP 导出，落到存储中，经过一个摄取任务更新向量库，最后由 Agent 从向量库读取。

在 GitHub 上，把图表放进一个语言标记为 `mermaid` 的代码块：

```mermaid
flowchart LR
    ERP[客户 ERP] -->|每晚导出| S3[(对象存储)]
    S3 --> ING[摄取任务]
    ING --> VS[(向量库)]
    VS --> AG[运维 Agent]
    AG --> UI[运维团队聊天]
```

流程图有两种基本元素：节点是图形，边是箭头或连线。第一行设定图的方向。`LR` 表示从左到右，适合表现数据流，读者可以从左边的数据源一路看到右边的输出。

最有价值的细节是箭头上的标签，比如上面的“每晚导出”。接手的人不仅要知道数据流向哪里，还要知道什么时候流动。把频率、格式或任务名写在边上，客户的运维团队就不必在你离开项目后再四处找你提问。

## 常见错误：少了一条竖线

假设交接前匆忙修改第一行，丢掉了标签右侧的竖线：

```text
ERP[客户 ERP] -->|每晚导出 S3[(对象存储)]
```

边标签必须放在两条竖线之间。修复方法是把这一个字符补回来：

```text
ERP[客户 ERP] -->|每晚导出| S3[(对象存储)]
```

别让接手的人第一个发现问题。把描述粘贴到 Mermaid Live Editor 里检查，GitLab 也推荐用这个工具学习 Mermaid 和调试图表。如果图渲染不出来，就和上一个能用的版本逐行对比，错误通常出在刚改的那一行。

第二种错误更难发现，因为图仍能正常渲染：节点只有 `ING` 这样的缩写，方括号里没有文字。节点 ID 是为了写起来快，方括号里的文字才是给客户团队看的。满是内部缩写的图，和过时的截图一样难懂。

## 局限：版本与 beta 功能

Mermaid 有专门的架构图类型，从 v11.1.0 起可用，用于展示云端或 CI/CD 部署中服务与资源之间的关系。听上去非常适合交接文档，但官方文档明确说明，这种图表类型仍处于 beta 阶段，语法可能会变。

第二个风险在于由哪个平台渲染。GitHub 建议在 mermaid 代码块里放入 `info` 命令，查看其运行的 Mermaid 版本，确认你的语法受支持。GitLab 同样能在 Markdown 中渲染 Mermaid，并声明支持 Mermaid 12 版本。

如果客户用的平台和你写图时用的不同，依赖新功能的图可能无法像在你本机上那样渲染。所以交接文档应该用流程图。只有确认架构图在客户自己的仓库里能正确渲染后，再使用它。

## 先学什么，如何写进简历

从流程图开始：节点、边、边标签和 `LR` 方向。这些足以画出在客户那里遇到的大多数数据流。养成习惯，每次修改都先在 Live Editor 里过一遍再提交，就像推送代码前先跑测试一样。

从职业发展看，交接文档是招聘方很少看到、但每个 FDE 都必须写的东西。如果作品集仓库的 README 里有一张经过多次提交持续更新的数据流图，就能说明你考虑过自己离开后负责运行系统的人。面试时，打开这张图，逐条讲解每一条边。

下次发现设计文档的“架构”一节里只有一张截图时，别再用拖拽工具重画。写六行文本，和代码一起提交。

**本周动手试试:**

- 挑一个正在部署的项目，写一张包含 5-6 个节点的 LR 流程图，展示数据从客户系统流向最终输出的过程，并放进 README
- 把图粘贴到 Mermaid Live Editor 里，提交前修复语法错误
- 在仓库里新建一个只包含 info 命令的 mermaid 代码块，查看 GitHub 运行的 Mermaid 版本

## 信源

- [About Mermaid | Mermaid (official docs)](https://mermaid.js.org/intro/)

- [mermaid-js/mermaid (GitHub repository)](https://github.com/mermaid-js/mermaid)

- [Mermaid (software) - Wikipedia](https://en.wikipedia.org/wiki/Mermaid_(software))

- [Creating diagrams - GitHub Docs](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams)

- [Flowcharts Syntax | Mermaid](https://mermaid.js.org/syntax/flowchart.html)

- [Architecture Diagrams Documentation (v11.1.0+) | Mermaid](https://mermaid.js.org/syntax/architecture.html)

- [GitLab Flavored Markdown (GLFM) | GitLab Docs](https://docs.gitlab.com/user/markdown/)
