90k star，像写 Markdown 一样画流程图，这个开源工具太牛了！

阅读全文

⭐⭐⭐ Spring Boot 项目实战	⭐⭐⭐ Spring Cloud 项目实战
《Dubbo 实现原理与源码解析 —— 精品合集》	《Netty 实现原理与源码解析 —— 精品合集》
《Spring 实现原理与源码解析 —— 精品合集》	《MyBatis 实现原理与源码解析 —— 精品合集》
《Spring MVC 实现原理与源码解析 —— 精品合集》	《数据库实体设计合集》
《Spring Boot 实现原理与源码解析 —— 精品合集》	《Java 面试题 + Java 学习指南》

摘要: 原创出处 http://www.iocoder.cn/Fight/mermaid-markdown-diagram/ 「芋道源码」欢迎转载，保留摘要，谢谢！

🙂🙂🙂关注微信公众号：【芋道源码】有福利：

RocketMQ / MyCAT / Sharding-JDBC 所有源码分析文章列表

RocketMQ / MyCAT / Sharding-JDBC 中文注释源码 GitHub 地址

您对于源码的疑问每条留言都将得到认真回复。甚至不知道如何读源码也可以请教噢。

新的源码解析文章实时收到通知。每周更新一篇左右。

认真的源码交流微信群。

一张架构图最常见的死法是，评审时画一版塞进文档，两周后接口改了图没改，再过两周没人敢动它。图烂得比代码快，是因为它存错了地方。

图片是二进制，进不了版本控制，一根箭头改了也看不出差异，评审时更没法对着图提意见。

Mermaid 换掉的正是这个位置。图不再以图片的形式存在，它变成一段能放进仓库的文本。这个项目 2014 年就开了源，现在 GitHub 上有九万上下的 Star。

仓库首页实时截图，Star 与 Fork 计数同时可见

它的做法是把图从图片变成文本

Mermaid 本身是 JavaScript 生态里的一个库，靠一段 Markdown 风格的文本定义加一个渲染器出图。官方把目的写得很直白，让文档跟上开发的步伐。

它跟绘图软件不在一个赛道上。Visio 那类工具解决的是怎么把图摆好看，它解决的是图放在哪里才能被人持续维护。文本能进 Git、能进评审、能跟接口改动写在同一个提交里。

代价是你交出了拖拽的自由，节点位置交给布局算法决定。

到底有多少种图，官方自己给了三个数

这是我看得最乐的地方。来源列了十种，官方 README 只敢写「20+ 种图」，而仓库里 packages/mermaid/src/diagrams 下实际躺着 33 个实现。

来源那十种是流程图、序列图、类图、状态图、实体关系图、甘特图、饼图、用户旅程图、Git 图和需求图。官方另外还有思维导图、时间线、看板、雷达图、桑基图、象限图，以及 9 月新加的用例图与 agentflow。

三分钟出第一张图，两条路都走一遍

浏览器里最快的一条路是这样。

<pre class="mermaid">
  graph LR
    A[需求评审] --> B(技术设计)
    B --> C{复杂度评估}
    C -->|高| D[拆分任务]
    C -->|低| E[直接开发]
</pre>
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@12/dist/mermaid.esm.min.mjs';
</script>

存成 .html 双击打开就能看到图。第二条路是在编辑器里写，装上插件之后能实时预览、导出 PNG 与 SVG 与 PDF，还有语法提示。

五种常用图，代码和结果对着看

流程图是最常用的，长这样。

flowchart LR

A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]

上面那段定义渲染出来的流程图

序列图写的是谁在什么时候给谁发了什么消息。

sequenceDiagram
Alice->>John: Hello John, how are you?
loop HealthCheck
    John->>John: Fight against hypochondria
end
Note right of John: Rational thoughts!
John-->>Alice: Great!
John->>Bob: How about you?
Bob-->>John: Jolly good!

上面那段定义渲染出来的序列图

甘特图把任务的起止和并行关系排上时间轴。

gantt
    section Section
    Completed :done,    des1, 2014-01-06,2014-01-08
    Active        :active,  des2, 2014-01-07, 3d
    Parallel 1   :         des3, after des1, 1d
    Parallel 2   :         des4, after des1, 1d
    Parallel 3   :         des5, after des3, 1d
    Parallel 4   :         des6, after des4, 1d

上面那段定义渲染出来的甘特图

类图记的是类的属性和方法，以及继承与组合的样式差别。

classDiagram
Class01 <|-- AveryLongClass : Cool
<<Interface>> Class01
Class09 --> C2 : Where am I?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
class Class10 {
  <<service>>
  int id
  size()
}

上面那段定义渲染出来的类图

饼图最简单，三个数值三块扇形。

pie
    "Dogs" : 386
    "Cats" : 85.9
    "Rats" : 15

上面那段定义渲染出来的饼图

把它接进工作流，收益才真正出现

在线编辑器适合试手，接进仓库还得靠命令行。

npm install -g @mermaid-js/mermaid-cli
mmdc -i input.mmd -o output.svg

它还能把 Markdown 里嵌的图表块转成图片再回写引用，放进 CI 就能每次构建重画。GitHub 从 2022 年起也原生渲染这段文本。

仓库地址是 https://github.com/mermaid-js/mermaid ，配置与安全说明在 mermaid.ai/open-source 上。

有两件事得提前知道，默认值都变过

9 月发布的 12.0.0 把 ELK 扶正成默认布局并打进主包。流程图、状态图、类图这些类型只要没写 layout，排布就会变，想保留老外观就写 layout 设成 dagre。

同一版还把默认主题换成 redux-color、默认外观换成 neo，覆盖十类图。老图升级之后看着变了，不是你的错觉。

另一件是安全等级。默认的 strict 会把文本里的 HTML 标签转义掉，同时禁用点击；要在图里放可点的链接得改成 loose 或 antiscript。这是安全与功能的取舍，不是配置写错了。

几十行的流程图、时序图、架构图，它几乎是现在最省事的画法；要做精细的视觉排版就不合适。如果图要跟代码一起活很久，它值得进仓库。

图片待确认

TODO @芋艿：IMG-001 未使用——这是账号订阅引导横幅（640x80 的两帧 GIF），画面内容是引导点蓝字和加星标，属于文末导流同一类物料，不是图表信息，需要你确认是否在本地留档。
TODO @芋艿：IMG-007 未使用——这是文末「后端专属技术群」的入群二维码，属于导流物料且带水印，与正文信息无关，需要你确认是否在本地留档。