FDE Times 数据在招 FDE 职位 924▲33 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 80在招公司 196支持远程 25%美国薪资中位数 $200k招聘最多 Databricks 107
ENVI

前线部署工程师(FDE)的专业媒体

工具

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

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

分享微博

要点速览

  • Mermaid 把文本转换成图表。GitHub 可以在 issue、pull request、wiki 和 Markdown 文件里直接渲染,GitLab 也支持。
  • 对 FDE 来说,最大的好处是图表和代码在同一个 pull request 里更新,交接 README 不容易与真实系统脱节。
  • 先从流程图入手。架构图仍处于 beta 阶段,而且不同平台的 Mermaid 版本可能不一样。
文中示例数据流图:客户 ERP、对象存储、摄取任务、向量库、运维 Agent,最后到运维团队聊天。只有从 ERP 到对象存储的箭头带有标签“每晚导出”,以橙色突出,一条引线把它连到注释:写明频率、格式、任务名。其余箭头没有标签,呈浅灰色。
在文中的示例里,这张 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 里有一张经过多次提交持续更新的数据流图,就能说明你考虑过自己离开后负责运行系统的人。面试时,打开这张图,逐条讲解每一条边。

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

这篇文章对你有帮助吗?

7 个信源
路线图上的下一篇 · 阶段 7: 项目主导海豹突击队的这条原则,让 FDE 事故会议不再甩锅两位前海豹突击队员的《极限控制》,教 FDE 在客户项目出问题时主持会议,不让它沦为追责。