diagram-design 进阶指南：从代码化绘图到架构可视化体系

diagram-design 这个词，你在 GitHub 上能看到一堆同名仓库，在 Figma 社区里也能搜到同名插件，但真要问一句“它到底是干什么的”，十个人能给你八个答案。我自己折腾了几年架构图、流程图、时序图，从最开始的 Visio 画到吐，到后来用代码写图、用白板工具随手勾，再到现在团队里把 diagram-design 当基础设施来搭，最大的感受是：图的本质不是“画得好看”，而是“把关系说清楚”。这篇文章我不打算只聊某一个工具，而是把 diagram-design 当成一个完整的技术方向来拆，讲清楚它解决什么问题、有哪些靠谱的落地路径、实操中会遇到什么坑，以及怎么在自己的项目里快速用起来。

如果你正在做技术文档建设、系统设计评审、团队知识库整理，或者单纯被“画图两小时、改动五分钟”折磨过，这篇文章应该能帮上忙。我会从思路、工具选型、实操流程、踩坑实录四个角度展开，尽量做到看完就能上手。

1. 内容整体设计与思路拆解

1.1 先想清楚：你画的是图，还是沟通协议

很多人一上来就纠结用哪个工具，其实顺序反了。diagram-design 的第一个核心问题不是“用什么画”，而是“这幅图给谁看、回答什么问题”。

我给团队做技术方案评审的时候，最常遇到的情况是：一张架构图塞了三十个组件、十几条箭头，乍一看很唬人，仔细看谁也不知道核心链路是什么。这就是典型的“把图当画来设计”，而不是“把图当沟通协议来设计”。

站在从业者的角度，我把 diagram-design 的目标拆成三层：

• 记录：把已经存在的系统结构、业务流程、接口关系固化下来，方便后续查阅。
• 推演：在设计阶段，用图来验证方案的可行性，提前暴露依赖关系、单点故障、数据流向等问题。
• 对齐：让不同角色（老板、产品、研发、运维）在同一个视觉框架下达成一致，减少口头沟通的模糊地带。

这三层目标对应着不同的设计侧重点。记录型图表重准确性，元素不能缺；推演型图表重逻辑，箭头方向和数据流向必须严谨；对齐型图表重表达，要控制信息密度，突出关键路径。

我自己踩过的坑是：一上来就追求“全量全景图”，结果图越画越大，最后没人愿意打开看。后来我给自己定了一个规矩：一张图只回答一个核心问题。如果你的系统复杂到一张图说不完，那就拆成多张图，用层级索引把它们串起来。

1.2 为什么“代码化绘图”正在成为主流方案

diagram-design 近几年最大的变化，是“用代码写图”逐渐取代了“用鼠标拖图”。我能明显感觉到，GitHub 上跟 diagram 相关的开源项目，热度几乎都集中在 Mermaid、D2、Graphviz、PlantUML 这类代码驱动方案上。

核心原因有三个：

• 版本管理：图是跟随代码走的，架构调整了，图也要更新。用代码写图，可以直接进 Git 做 diff，review 的时候一眼就能看出改了什么。而拖拽画图工具导出的文件，基本没法做有意义的差异对比。
• 自动布局：手拖图的痛点是“挪一个方块，所有线都要重拉”。代码化绘图把布局算法交给了工具，你只需要描述节点和关系，工具帮你算位置。虽然不算完美，但大多数场景够用。
• 复用和生成：代码是文本，可以被脚本批量处理。比如我写了一个 Python 脚本，扫描 Kubernetes 的 Ingress 配置，自动生成服务调用关系图——这种能力是手动画图永远做不到的。

当然，代码化也不是银弹。它的学习曲线比拖拽工具陡，自由排版能力也差一些。我的经验是双轨并行：正式文档里的架构图、时序图用代码写，方便维护；头脑风暴、方案速写用 Excalidraw 这类白板工具，追求的是快和随意。

1.3 信息架构：好图是“设计”出来的，不是“画”出来的

如果把 diagram-design 当成一门设计学科来看，它跟 UI 设计有相通之处：都在处理信息层级、视觉节奏、注意力引导。

我画图之前会先列一个信息清单，这个习惯是从写技术方案文档带过来的：

• 核心实体有哪些？
• 实体之间的关键关系是什么？（依赖、调用、继承、聚合……）
• 哪些是读者必须第一眼看到的？
• 哪些是细节，可以折叠或用注释标注？

然后才是视觉设计的部分。这里我借鉴了一些平面设计的基本原则：用颜色区分层级，但一个图里不超过三种主色；用箭头粗细表达流量主次；用分组边框表达边界和归属。这些说起来都是基本功，但实际见过太多图是“五彩斑斓的黑”——颜色用得越多，信息传达效率越低。

2. 核心类型解析与工具选型要点

2.1 搞清楚你需要的图属于哪个类别

diagram-design 不是一个单一的图形类型，而是一整族视觉表达方式的集合。把类型搞混，后续一切的选型都会跑偏。

按我日常的高频用途，可以分成四类：

有一个很容易被忽视的点：同一个工具，在不同图形类型上的表现力差距极大。比如 Mermaid 的流程图和时序图都很好用，但画复杂架构图时布局控制力就偏弱；Graphviz 的图论布局算法很强大，但默认样式很丑，需要花心思调样式。所以正经做 diagram-design，通常不是“只用一个工具”，而是“按图选工具”。

2.2 代码化绘图工具怎么选

这块我把市面上主流的方案都试过一遍，说点真实体会。

Mermaid应该是目前生态最火的选择。优点是语法简单、十分钟就能上手，而且 GitHub 原生支持、Notion 内置、各种文档平台都嵌入了它的渲染引擎。缺点是复杂布局控制力有限，节点坐标基本不可控，遇到精英网状的复杂调用关系会乱成一团。

D2是这几年的新秀，定位是“现代声明式图表语言”。它的语法也很简洁，但布局引擎比 Mermaid 聪明，尤其是画架构图时，能自动做容器分组和边界计算。C4 风格的架构图用 D2 来画非常顺手。缺点是生态还在成长，社区模板和示例比 Mermaid 少很多。

Graphviz是老牌经典，核心思想是“描述图结构，由布局引擎自动计算位置”。它的 dot 语言功能非常强大，适合画依赖关系图、状态机图。但默认输出确实丑，而且学习曲线比较陡，那套属性语法够你研究一阵子。

PlantUML在 Java 生态里地位很高，尤其是时序图和活动图的语法设计得很优雅。缺点是渲染速度偏慢，遇到大图容易卡。

Structurizr是 C4 模型的开源实现，严格来说它不是画图工具，而是一个“把架构描述成代码”的 DSL。它的思路是：你先用代码定义系统、容器、组件、人与人之间的关系，然后工具自动生成多层级架构图。适合做长期演进的架构治理，但初期投入成本比较高。

我把选择逻辑整理成一个简单判断：

• 只是想快速画图、发给别人看 → Mermaid
• 认真做架构文档、希望自动布局好看 → D2
• 画数据关系/依赖图谱、需要算法布局 → Graphviz
• 团队协作、长期维护架构资产 → Structurizr

2.3 白板和手绘类工具的价值不可替代

代码化方案讲了这么多，但我不建议完全抛弃手动工具。diagram-design 里有一部分工作是“探索性”的，这时候用 Excalidraw、draw.io、Figma 反而效率更高。

Excalidraw 是我个人最常用的速写工具。它的手绘风格天然带一种“草稿感”，反而降低了读者对美观度的预期，让人更聚焦内容本身。画架构草图、画方案对比、画 UI 线框图，都非常好用。而且它支持端到端加密的多人协作，临时拉个链接就能一起画。

draw.io（现在叫 diagrams.net）是老牌免费方案，胜在功能全面、支持离线、集成丰富。VS Code 有它的插件，可以直接在编辑器里编辑 .drawio 文件。不过界面确实有点老旧，但作为免费工具，已经很良心了。

说一个我的工作习惯：探索阶段用 Excalidraw，最终沉淀到文档里用 Mermaid 或 D2。前者是用来“想”的，后者是用来“存”的。两个用途不要混在一起，否则你会在“追求美观”上浪费大量时间。

3. 实操过程：从零到一搭一套可演进的 diagram-design 工作流

3.1 搭建本地绘图环境

实操这部分，我会以“在 VS Code 里用 Mermaid 画图并沉淀到项目文档”为主线，因为这是上手成本最低、收益最明显的一条路径。

首先需要准备环境。我用的是 VS Code，配合官方插件：

1. 安装 VS Code 后，在扩展商店搜索Mermaid，安装支持 Mermaid 的 Markdown 插件（我推荐 Markdown Preview Mermaid Support，也有集成度更高的 mermaid-in-editor 之类的插件，按喜好选就行）。
2. 准备一个测试用的.md文件，写一个基本示例：

# 订单模块流程 ```mermaid graph TD A[用户提交订单] --> B{库存校验} B -->|通过| C[创建订单] B -->|不通过| D[返回错误] C --> E[支付] E --> F[完成]

3. 打开 Markdown 预览，正常的话就能看到自动渲染出来的流程图。 这个流程本身很简单，但我还是要强调“环境即工作流”的思路。把绘图语言嵌入 Markdown 文档，意味着图表跟文档正文共用一个文件、同一套版本管理、同一个 review 流程。技术人员在看设计文档的时候，改了代码顺手把图也改了，而不是等到文档评审前临时补一张架构图，然后很快就过期了。 ### 3.2 用 D2 画一张可读性更高的架构图 如果你对图表的美观度有更高要求，我建议直接学 D2。它的上手成本跟 Mermaid 差不多，但默认样式的专业感高出一大截。 安装 D2 很简单，macOS 上可以直接 `brew install d2`，或者下载预编译二进制。装完以后，写一个 `architecture.d2`： ```d2 direction: right 用户: 用户端 网关: API 网关 服务A: 用户服务 服务B: 订单服务 服务C: 库存服务 数据库A: 用户库 数据库B: 订单库 数据库C: 库存库 用户 -> 网关: HTTPS 网关 -> 服务A: gRPC 网关 -> 服务B: gRPC 网关 -> 服务C: gRPC 服务A -> 数据库A 服务B -> 数据库B 服务C -> 数据库C

在终端执行：

d2 architecture.d2 architecture.svg

生成 SVG 之后，可以直接放进文档或 PPT。D2 会自动做容器布局和连接的排线，画出来的效果比我手拖出来的还整齐。

这里有一个实用技巧：D2 支持把对象嵌套到容器里，用来表达“服务部署在哪个环境”非常直观：

云环境: { K8s集群: { 服务A 服务B } RDS: { 数据库A 数据库B } }

用这种方式，架构图天然就有了“环境边界”这一层语义，读者一眼就能看出哪些组件在同一个部署单元里，这是传统手绘拖拽很难表达的。

3.3 用 Mermaid 画时序图梳理接口调用

时序图在技术文档里出现频率极高，因为它能讲清楚“谁先调谁、消息长什么样、异常怎么走”。Mermaid 的时序图语法非常直观，基本就是“参与者 + 实线/虚线 + 消息描述”。

我举一个真实的例子：排查支付回调幂等性问题时，我用时序图把正常回调、重复回调、超时补偿三条路径画在一起，问题瞬间就清晰了。

sequenceDiagram participant C as 客户端 participant G as 网关 participant P as 支付服务 participant O as 订单服务 participant DB as 数据库 C->>G: 支付请求 G->>P: 转发支付 P->>P: 幂等校验 P->>O: 异步回调 O->>DB: 更新订单状态 O-->>P: 确认收到 P-->>C: 返回支付结果

画这种图有一个需要注意的逻辑要点：谁发起调用，谁就是箭头起点。很多人画时序图喜欢按“数据从哪来”当起点，结果把箭头方向画反，看的人要猜很久。时序图表达的是“控制权转移”，不是“数据流向”。

3.4 让图表纳入文档自动化流水线

单张图画得再好，如果不能跟文档构建流程打通，最终也难逃“过期”的命运。

我的做法是把绘图文件的生成纳入 CI/CD 流程。具体来说：

• 在docs/diagrams目录下维护.d2或.mmd源文件。
• 通过 pre-commit 钩子或 CI 任务，自动把源文件编译成 SVG/PNG。
• 生成的图片输出到docs/assets，然后在 Markdown 文档里引用。

这样团队在改架构的时候，只需要改.d2源文件，提交时 CI 会重新渲染图片，文档站点自动更新。这个流程的核心价值是：图跟上代码节奏，而不是靠人记忆去维护。

如果你用 D2，GitHub Actions 里可以这样简写：

- name: Render D2 diagrams run: | for file in docs/diagrams/*.d2; do d2 "$file" "docs/assets/$(basename "${file%.d2}").svg" done

放到docs构建的上游，就完成了自动化。对于小团队来说，这十分钟的配置投入，回报是长期不用再为“文档图和代码不一致”吵架。

4. 常见问题与排查技巧实录

4.1 Mermaid 中文乱码与样式问题

Mermaid 在中国开发者这里最常见的问题就是中文乱码。这个问题的根源不在 Mermaid 本身，而在渲染环境的字体配置。浏览器渲染时如果找不到合适的中文字体，就会显示成豆腐块。

我的排查套路是：

• 先确认用的是什么渲染器。VS Code 的 Markdown 预览用的是系统字体，一般没这个问题；但如果用 Puppeteer 做服务端渲染导出图片，就非常依赖容器的字体。
• Docker 环境里记得装中文字体，比如fonts-noto-cjk（Debian/Ubuntu 系）或者wqy-zenhei。
• 如果还是乱码，检查一下 HTML 容器的lang属性和 CSS 的font-family，把中文字体显式指定上去。

另一个高频问题是graph TD默认布局下节点挤压。我的经验是：节点文字里不要塞太多内容，每个节点只放核心关键词，细节放段落里解释。实在控制不住，可以给出节点样式配置：

graph TD A[下单] --> B[支付] B --> C[发货] style A fill:#e1f5fe,stroke:#0288d1 style C fill:#c8e6c9,stroke:#388e3c

适当用颜色区分状态，图表会好读很多。

4.2 布局乱成一团：代码图不是万能的

代码化布局算法虽然方便，但遇到节点太多、连线交叉密集的图，效果往往不尽人意。我画微服务调用关系图的时候踩过不少坑——画三四十个服务节点，布局算法排出来的图跟蜘蛛网一样，完全没法看。

这时候我会回头审视一个问题：是不是一张图承载了太多信息？

一个比较实用的解决方案是分层拆分。把“所有服务的调用关系全景图”拆成“按领域拆分的多张局部图”，再加上一张“领域间依赖的粗粒度图”。从可读性来讲，一张不完美的局部图，比一张完全准确的蜘蛛网要有用得多。

另外也可以利用 Mermaid 的subgraph显式分组，把相关的节点包在一个组里，让布局引擎先做组内排布，再做组间排布：

graph TD subgraph 订单域 A[订单服务] B[支付服务] end subgraph 库存域 C[库存服务] end A --> C B --> A

4.3 导出图片模糊或空白

导出环节最容易出问题。很多人写好了 Mermaid，想在文档里放高清大图，却发现导出 PNG 模糊或者白屏。

Mermaid CLI（mmdc）导出高清图的参数，我常用的有两种：

mmdc -i input.mmd -o output.png --scale 3 mmdc -i input.mmd -o output.svg

用--scale 3可以放大渲染分辨率，适合输出到 PPT 或印刷。如果导出 SVG 后图片空白，通常是渲染引擎或权限问题。这时候优先检查 CLI 的版本是否跟 mermaid 内核版本匹配，mmdc的版本迭代很快，旧 CLI 配新语法是兼容性问题的重灾区。

另外一个容易被忽视的点：很多图表平台（如 GitHub）对 Mermaid 的安全策略越来越严，某些你可能已经习惯的“前端交互语法”在平台上会被屏蔽。所以重要的图建议在本地渲染成 SVG 再提交到文档，而不是依赖平台动态渲染。

4.4 团队协作时“图的分歧比代码还多”

最后说一个团队层面的问题，这其实是我写 diagram-design 这么久以来觉得最有价值的部分。

代码有编译器和 linter 做强制约束，图没有。一个人画图的时候，节点叫“用户服务”，另一个人叫“User Service”，第三个人叫“用户端”，一张架构图里三个名字一混，读者就懵了。

我的建议是给团队定一套“图形元素命名规范”，哪怕只有一条也行：

• 所有系统/服务必须使用官网或代码仓库中的统一名称，不能自创简称。
• 方向定义要统一：箭头统一表示“调用/依赖方向”，如果没有特殊说明，时间流默认从左到右、从上到下。
• 颜色语义要统一：红色只能表示异常或重点警示，绿色只能表示正常或已实现，灰色表示规划中。如果颜色不统一，图表的表达力会大打折扣，甚至误导人。

这些规则听起来很基础，但效果立竿见影。我们团队用了这套规范之后，图表的 review 成本大幅下降，大家把精力放在“画得对不对”而不是“画的什么玩意儿”。

5. 从图到体系：diagram-design 的进阶方向

5.1 用 C4 模型解决“一张图说不清”的难题

前面提到过 Structurizr，背后是 Simon Brown 提出的 C4 模型。它的核心思想是：不要试图用一张图描述整个系统，而是用四个层级来递进表达：

• Context（语境）：系统在人、外部系统之间的位置。
• Container（容器）：系统由哪些可独立部署的进程/存储组成。
• Component（组件）：容器内有哪些主要模块。
• Code（代码）：组件内部的关键类或接口关系（这一层一般仅在必要时画）。

这种分层思路对设计文档的演进特别友好。我也是在自己设计一个中大型系统时开始用 C4，发现它给我最大的启发不是“多了一种画图方式”，而是逼我先想清楚“我到底在哪个层级讨论问题”。

日常讨论系统时，很多人把“网关调用用户服务”这种容器级关系和“用户服务内部有 controller/service/mapper”这种组件级关系混在一张图里讨论，永远吵不清。C4 模型天然规避了这个问题。

如果你不想引入 Structurizr 的重型 DSL，用 D2 手动维护 C4 分层图也很容易。第一张图只画“用户、企业系统、我们的系统、第三方支付”，第二张图再展开容器，第三张图展开组件，每张图信息密度都不高，但合在一起能把系统讲透。

5.2 让图“活”起来：从静态图到交互式图表

diagram-design 还有一个容易被忽视的进阶方向，是让图表从静态文件变成可交互的信息系统。

大概两年前，我用过 Mermaid 的点击事件能力，让图中的节点可跳转。它的基本用法是：

graph LR A[订单服务] --> B[订单数据库] click A href "https://github.com/org/order-service" _blank

这样架构图就变成了一个导航入口，看文档的人点节点就能跳到对应代码仓库或详细设计页。在内部 wiki 系统里，这种体验比翻目录高效得多。

更进一步，如果团队有自己的前端开发资源，可以考虑 D3.js 或 AntV G6 这类可视化库。它们已经不是“画图工具”的范畴，而是图表可视化开发框架，能实现拖拽、缩放、聚焦高亮、实时数据绑定等能力。我自己用 G6 做过一个服务依赖排查工具，把 SkyWalking 的调用链数据拉下来，实时渲染成依赖图，点击服务节点能看到上下游所有依赖——这在生产环境的故障排查中帮了大忙。

当然，G6 的接入成本比 Mermaid 高一个数量级，适合属于“图的消费者较多、且存在动态变化”的场景，比如监控大屏、运维拓扑、数据分析平台。如果你只是写技术文档，完全没必要上这种重量级方案。

5.3 与 AI 结合：自然语言生成图的边界

最后提一嘴 AI 生成图表的现状。说实话，现在用 LLM 生成 Mermaid 代码已经很成熟了。你让 AI “画一个用户下单的序列图”，它通常能给出基本可用的 Mermaid 代码。我也经常用这种方式快速生成初稿，再手动调整逻辑和细节。

但要泼一盆冷水：AI 能生成“像样的图”，但很难生成“对的图”。因为它不了解你系统里真正的服务名称、依赖关系、异常分支，它只会根据训练数据里的常见模式来猜测。所以我的建议是把 AI 当加速器，不要当设计者。用 AI 搭骨架、出草稿，用人的领域知识去修正和定稿，这才是目前性价比最高的模式。

我也测试过让 AI 直接生成 D2 或 Graphviz 代码，效果比 Mermaid 稍弱，因为这类语言生态小、训练语料少，但是基本的结构生成问题不大。近一年这个方向的迭代速度很快，说不定再过段时间，AI 生成图的准确度会有明显提升，到时 diagram-design 的入门门槛会更低，但设计判断力依然是人类的价值所在。

写到这里，我想起自己最开始折腾 diagram-design 的动机。当时团队刚拆微服务，系统一多，文档里的架构图全过期了，没人说得清服务间到底谁调谁。我就花了一个周末研究 Mermaid 和 D2，把核心链路都画了出来，又设计了一套自动化渲染的流程。之后每次系统演进，我都逼自己同步改图。这个习惯一开始很别扭，但坚持几个月后，我再也不需要靠脑子记整个系统的结构，翻开文档看图就行。

我个人最大的体会是：diagram-design 的难点从来不在工具，而在于你有没有把“信息准确、层级清晰、表达克制”当回事。工具最多帮你把线画直，但把哪两个点连起来、用什么颜色、以什么层级呈现，永远是需要人来判断的。

如果你也想在团队里落地这套思路，别贪多，挑一个工具，从一张核心架构图开始。画完以后，问自己一个问题：一个刚入职的新人，不看任何代码，只看这张图，能不能复述出系统里有哪些模块、它们之间怎么协作？如果能，这幅图就成功了。