交接那天,架构图为什么总是过时
Mermaid 把图表写成文本放进代码仓库,流水线步骤和对应的图在同一个 PR 里一起改。
要点速览
- Mermaid 把文本转换成图表。GitHub 可以在 issue、pull request、wiki 和 Markdown 文件里直接渲染,GitLab 也支持。
- 对 FDE 来说,最大的好处是图表和代码在同一个 pull request 里更新,交接 README 不容易与真实系统脱节。
- 先从流程图入手。架构图仍处于 beta 阶段,而且不同平台的 Mermaid 版本可能不一样。
离交接还有两周,打开设计文档,却发现架构图还是第一次研讨会时截的图。图上有一个早已弃用的队列,还有一个客户已经改了名的 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 的代码块:
flowchart LR
ERP[客户 ERP] -->|每晚导出| S3[(对象存储)]
S3 --> ING[摄取任务]
ING --> VS[(向量库)]
VS --> AG[运维 Agent]
AG --> UI[运维团队聊天]
流程图有两种基本元素:节点是图形,边是箭头或连线。第一行设定图的方向。LR 表示从左到右,适合表现数据流,读者可以从左边的数据源一路看到右边的输出。
最有价值的细节是箭头上的标签,比如上面的“每晚导出”。接手的人不仅要知道数据流向哪里,还要知道什么时候流动。把频率、格式或任务名写在边上,客户的运维团队就不必在你离开项目后再四处找你提问。
常见错误:少了一条竖线
假设交接前匆忙修改第一行,丢掉了标签右侧的竖线:
ERP[客户 ERP] -->|每晚导出 S3[(对象存储)]
边标签必须放在两条竖线之间。修复方法是把这一个字符补回来:
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 里有一张经过多次提交持续更新的数据流图,就能说明你考虑过自己离开后负责运行系统的人。面试时,打开这张图,逐条讲解每一条边。
下次发现设计文档的“架构”一节里只有一张截图时,别再用拖拽工具重画。写六行文本,和代码一起提交。
这篇文章对你有帮助吗?
感谢你的反馈!