如何使用 Mermaid 与产品沟通、与 devs 架构并同步记录所有内容

发布: 0个月前 (2026年4月7日 GMT+8 13:04)

11 分钟阅读

原文: Dev.to

Source: Dev.to

几乎每个开发者的职业生涯中都会有这么一个时刻：你会意识到代码已经不再是最难的问题。最难的问题是向产品人员解释系统为何如此运作，或者说明看似简单的改动实际上隐藏着十个不易察觉的影响。

很长一段时间，我用来解决这个问题的工具还是老一套：一块白板、一份匆忙准备的演示文稿，或者在最好的情况下，用 draw.io 画的一个图表——它的制作时间往往比它变得过时的时间还要长。这些工具的问题不在于它们不好——而是它们与代码、仓库以及系统的真实状态脱节。一旦有任何变动，图表就会失真。

发现

直到我看到一些改变了我的工作方式的东西。

是我的老板第一次向我展示了 Mermaid 能做到的事。他写了一个 Python 脚本，读取数据库模式并自动生成 Mermaid 的 Entity Relationship Diagram（ERD）。该图表存放在代码仓库中，并通过 GitHub Actions 工作流在每次更改时自动更新。

第一次看到它时，我呆住了。并不是因为它是魔法——代码非常简单——而是因为它连接了我一直分开对待的两个世界：文档和真实系统。一个从真相来源生成的图表不可能说谎。它是活的文档。

还能做什么？

这让我看到了更大的可能性：如果我可以自动生成 ERD，那么使用一个能够理解文本并生成图表的工具还能做什么？如果我不仅仅用它来为开发者编写文档，而是用来与产品团队沟通，会怎样？

答案在一个具体项目中出现。我正在为另一个国家的团队重新设计一个计费系统——我在前一篇关于 event‑driven 与计费的文章中有更详细的说明——而起点是一份包含超过 10 个业务场景的列表，产品团队把它们当作独立的案例来处理。

技术团队按照产品的描述对这些场景进行了建模。结果是一个脆弱的系统，出现了大量重复的逻辑和不断出现的边缘案例。当我真正开始分析领域时，发现所有这些场景其实只是 4 个真实业务事件 的变体。

挑战在于说服产品团队接受这一点。光说不练不行——我必须展示给他们看。

我使用的两种 Mermaid 图表

1. 时间线 – 用于展示时间中的模式

第一个图表是一个 时间线，展示了在债务生命周期中，团队处理的 10 多个场景实际上是同四个时刻的实例的重复。看到时间分布的模式立刻让原本文字中看不见的东西变得可见：复杂性是偶然的，而非本质的。

2. 序列图 – 用于解释四个事件的工作方式

第二个图表是一个 序列图，以功能性且无代码的方式展示了四个事件如何在系统中流动：谁触发它，涉及哪些组件，产生什么结果。

sequenceDiagram
    actor Usuario
    participant Sistema
    participant EventBridge
    participant Facturacion as "Servicio de Facturación"

    Usuario->>Sistema: Realiza pago parcial
    Sistema->>Sistema: Valida monto y deuda
    Sistema-->>Usuario: Confirma recepción del pago
    Sistema->>EventBridge: Publica evento PagoParcialRegistrado
    EventBridge->>Facturacion: Entrega evento PagoParcialRegistrado
    Facturacion->>Facturacion: Actualiza saldo de la deuda
    Facturacion->>Facturacion: Genera registros contables
    Facturacion-->>EventBridge: Publica evento DeudaActualizada
    EventBridge-->>Sistema: Notifica actualización de deuda
    Sistema-->>Usuario: Muestra nuevo estado de la deuda

产品团队在同一次会议上就理解了模型。并不是因为图表好看——而是因为它用他们的语言说话：流程、时间、角色、结果。没有多余的技术术语。

Source: …

Mermaid 在我的工作流中变得永久化

在那个项目之后，Mermaid 成为了我工作方式中的常驻工具。我最常使用的两种图表是：

时序图 — 我最喜欢用来与非技术人员沟通的方式

这是在业务领域为我带来最大价值的图表。它能够在高层次且无需代码的情况下，展示不同组件之间的通信方式：外部供应商与我们的服务、用户与系统、事件触发的一连串反应。

它特别有用的原因在于它同时在 两个层面 起作用：

对产品人员：展示端到端的功能流程。
对开发者：提供需要触及哪些组件以及顺序的指南。

一个图表，两个受众。

流程图 — 用于流程和决策分支

当我需要展示带有分支、条件和备用路径的流程时，flowchart 是自然的选择。我既用它向产品团队解释业务流程，也用它为技术团队记录算法和决策流。

flowchart TD
    A[Evento recibido] --> B{Tipo de evento}
    B -->|Adquisición| C[Procesar adquisición]
    B -->|Pago parcial| D[Aplicar pago parcial]
    B -->|Cierre de mes| E[Generar cierre de mes]
    B -->|Liquidación| F[Calcular liquidación]

    C --> G[Registrar en auditoría]
    D --> G[Registrar en auditoría]
    E --> G[Registrar en auditoría]
    F --> G[Registrar en auditoría]

    G --> H[Publicar eventos derivados]

集成和我发布图表的地点

Mermaid 的最大优势之一是 不局限于单一工具。根据不同的情境，我会使用：

工具	优势
GitHub Wikis	图表与代码一起存放，使用 Git 进行版本管理，任何开发者都可以在修改系统的同一个 PR 中更新它。
Confluence 和 Microsoft Loop	两者都内置了 Mermaid 可视化工具，适用于文档存放在企业工具中的场景。
draw.io	它有一个插件可以嵌入 Mermaid 代码，将 draw.io 的灵活性与自动生成图表相结合。

使用 Mermaid，我已经 缩短了开发与产品之间的鸿沟，提供了系统行为的清晰、始终最新且可视化的视图。如果你还没有尝试，我鼓励你给它一个机会：初始投入很小，沟通和对齐方面的收益可能非常巨大。

Mermaid：用于文档和演示的活图

一个生成器，接受 Mermaid 代码并生成可视化图表，适用于演示或正式文档。

同一篇博客中，我直接集成了 Mermaid 查看器，所以你在本文看到的图表都是实时渲染的 Mermaid 代码。Hashnode 也原生支持它。dev.to 目前还没有该查看器——在那里代码块会以纯文本形式出现。

其通用性是真实的：相同的文本块在大多数环境中都会生成图表。无需重新制作、导出或维护两个版本。

关键优势

可版本化
这是一段代码，因此可以版本化。图表存放在仓库中，随一次 commit 而改变，其变更历史即系统的历史。当有人问“六个月前它是怎么工作的？”时，图表本身就能给出答案。
可自动化
正如我老板展示的 ERD：你可以从唯一真实来源生成图表，并通过 GitHub Actions 或任何 CI 流水线自动更新。文档会自行保持最新。
兼容 AI
如今，用大语言模型生成或修改 Mermaid 图表非常简单。用自然语言描述流程，即可得到图表代码。入门门槛已经消失。

如何开始

如果从未使用过 Mermaid，打开 mermaid.live，编写你的第一个时序图。
语法易读——15 分钟内即可得到可用的图表。

实际应用

内部项目 – 如果你已经了解它但尚未在业务中使用，下一个需要向非技术人员解释流程的项目就是你的机会。在制作演示之前，先尝试绘制 sequence diagram。你会惊讶于理解速度提升的程度。
CI/CD – 若想把文档提升到更高层次，可在 CI 流水线中添加一步，从代码生成或校验图表。自动化 ERD 的同样原理同样适用于任何可以用结构化文本描述的系统产出。

Mermaid 不仅仅是一个绘图工具。
它让图表不再是会老化的文档，而是系统的活生生的一部分。

向社区提问

你在日常工作中使用 Mermaid 吗？有没有我这里未提及的使用案例？欢迎在评论中分享。