“diagram-design”看到这个词我就想起自己第一次完整负责一个系统架构图时的状态对着白板画了擦、擦了画最后用画图软件拖了一晚上方框和箭头第二天讲方案时还是被问得支支吾吾。后来我逐渐明白图表设计这件事技术含量从来不在“把框画出来”而在“把思考过程可视化”。一个方框放在哪、一条连线怎么走、一组节点用什么颜色背后全是信息层级和逻辑关系的决策。这篇文章我打算把这一整套东西拆开揉碎从最基础的认知讲到工具选型再讲到具体怎么落地一张图最后把我在实际项目中踩过的坑一并列出来。适合所有做技术方案、写文档、做产品梳理的人参考不管你是刚接触的新手还是已经被各种图折磨过的老手。1. 先把认知对齐图表设计到底在设计什么人人都能画图但不是人人都在“设计”图。diagram-design 表面看是一个技能点实际上是一种把复杂信息压缩成可读视觉符号的能力。我在团队里见过很多同事写代码很强但一到画架构图就歇菜画出来的图两种极端一种是信息量巨大、互相交叉连放大镜都救不了另一种是过分追求好看大量渐变阴影和高饱和度色彩但根本不知道想表达什么。核心原因其实一样没有想清楚这张图要替哪个“观点”说话。1.1 图表是工程师的“第二语言”写过代码的人都知道代码本身就有结构化表达能力。但代码对阅读者是有门槛的它要求读者具备语法基础还要愿意逐行去读。图表就不一样一个方框加一个箭头普通人也能看出“A调用了B”。所以图表的本质是一种翻译——把代码、系统、流程甚至是商业逻辑翻译成一眼能看懂的视觉语言。我经常跟团队说一句话如果你画不出一张图大概率不是画图能力的问题而是你对自己负责的东西还没真正理清楚。我见过有人画同一个模块的流程图第一版画了十几个分支图面很复杂等到他把需求彻底想透之后第二版只有五个节点却把所有异常路径都覆盖了。这才是 diagram-design 的真正价值它逼着你把模糊的概念结构化。1.2 不同图型的“设计哲学”完全不同mermaid、PlantUML 这类工具支持几十种图型但绝大多数人经常用到的就那么五六种。我的经验是每种图都有它自己的“表达偏好”用对了事半功倍用错了怎么画都别扭。架构图的核心是分层与边界。你要表达的是系统的组成结构和职责划分所以上下左右的位置关系是有语义的。比如在常规架构图中上面是客户端、中间是网关、下面是业务服务这种“上南下北”式的布局本身就是一种潜规则读者会下意识认为是流量方向。如果你把服务画在上面、客户端画在下面哪怕你加粗了箭头读者的第一反应还是“怪怪的”。流程图的核心是顺序与分支。它表达的是“一件事从开始到结束的路径”所以分支判断框、开始结束标记、循环回边这些都是约定的符号语言。很多人把流程图画成“大箭头串起所有小框”完全没有分支汇聚的层次感那其实不是流程图只是带箭头的便签。时序图的核心是对象间的交互顺序。它天然适合表达接口调用链、消息传递、分布式事务等场景。时序图有一个容易踩的坑很多人把不该出现在同一张图里的对象硬塞进来导致生命线交叉得跟蜘蛛网一样这时候你该做的是拆图而不是硬排。还有 ER 图、状态图、甘特图每一种都有一套“怎么表达才不别扭”的约定。我的建议是画图之前先问自己一句我想让读者从这张图里收获什么结论想表达流程就优先选流程图想表达状态迁移就选状态图想表达组成关系就选架构图。工具是服务于表达意图的别本末倒置。1.3 读者是谁直接决定设计尺度还有一个大家经常忽略的问题这张图是给谁看的。给研发团队看的架构图可以画到服务级别甚至画到类级别给老板看的架构图只需要三层——接入层、业务层、数据层再多了就是在为难对方。我做方案评审时有一个习惯同一套系统我会准备两份图。一份是“汇报级”的干净极简只有核心组件和关键链路用来3分钟内讲清楚整体形态一份是“落地级”的包含所有重要依赖和中间件用来跟后端同学逐项对齐细节。这不是工作量翻倍而是我清楚地知道不同读者对信息的接收带宽完全不一样。给老板看细节等于让他忽略重点给研发看概括等于让他没有抓手。2. 工具选型与渲染方案图表设计的基础设施聊完认知该落地了。diagram-design 这个领域早就过了“用手画”的阶段现在的工具生态非常丰富。但工具选型这件事恰恰是很多人最容易纠结的地方。我见过太多人把时间花在比较工具上而不是花在思考图表本身。我的态度是不要先选工具再想画什么而是先想清楚你的图表从哪里来、到哪里去再决定用什么工具。2.1 文本化图表语言的横向对比文本化图表语言最近几年特别火最典型的就是 Mermaid、PlantUML、D2 和 Graphviz。它们最大的优势是可以放在 Git 仓库里做版本管理代码评审的时候顺带把图的变更也审了。这一点对技术团队来说太重要了我见过太多 Docs 里的架构图“画在图上、烂在图上”因为源文件找不到了。简单聊聊我对这几个工具的体感Mermaid 是我最常用的命令式语法学习曲线很缓你只需要写下graph TD然后一行一个节点定义就能得到一张基本可用的图。它生态也很好GitHub 仓库直接渲染 Markdown 里的 Mermaid 代码块Notion、语雀也原生支持团队协作时代入成本极低。但它的弱点同样明显复杂布局下自动布局算法容易“放飞自我”节点一多连线就会变得不可控。PlantUML 是时序图和 UML 图的老牌王者语法也更贴近 UML 标准。如果你要画严格的时序图、类图、用例图PlantUML 的默认风格比 Mermaid 正统很多。缺点是它的依赖是 Java本地环境重一些不过如果是服务端渲染性能倒是还可以。D2 是比较新的选手主打“声明式布局”它对布局的控制比 Mermaid 细腻同类节点会有更合理的位置计算代码可读性也比 PlantUML 好。但生态起步晚社区和官方渲染平台相对少。Graphviz 是祖师爷级别的布局算法非常强大尤其擅长画有向图。它用 DOT 语言描述图结构处理复杂 DAG有向无环图的时候Graphviz 的 layout 能力能让不少新一代工具自愧不如。代价是你得接受它偏底层的 API 和比较“实验室风格”的输出样式。下面用一个很小的维度做对比方便快速感受维度MermaidPlantUMLD2Graphviz上手难度很低中低中时序图/类图支持一般强中弱自动布局能力中中中强强版本管理友好度高高高高生态/平台支持很广较广起步老牌稳定2.2 交互式画布方案拖拽、连线与实时编辑文本画图适合“确定性”场景也就是你已经想清楚要画什么了。但实际工作里还有另一类场景探索阶段思维还在发散你希望像在白板上一样自由摆放、随手连线、随时调整。这时候文本工具反而会限制你因为你每改一个节点位置都要改代码交互成本太高。我要推荐两个方向diagrams.net老名字叫 draw.io和 Excalidraw。diagrams.net 是桌面级和 Web 端都能用的绘图工具它的优势是“专业感”。内置了大量图标库云厂商图标、网络设备图标、UML 符号都有可以直接拖拽使用跟 Visio 的体验比较接近。我画需要粘贴进 PPT 的架构图时通常优先用它因为成品可以直接导出 PNG/SVG输出效果接近“正经设计稿”。Excalidraw 走的是“手绘风”路线线条有笔触感看起来很随意但它恰恰是思维梳理的好帮手。因为它不追求像素级精准所以你在上面画任何草稿都不觉得有压力反而更敢于冒出来表达。用来做头脑风暴、事件风暴、方案预演这类场景里 Excalidraw 完胜所有“正经”绘图工具。如果要做真正嵌入产品能力的图表设计功能比如在自己的系统里提供“在线画流程图”能力我一般会看 React Flow。React Flow 是目前前端领域比较成熟的图编辑框架节点自定义能力强缩放、拖拽、连线、小地图这些交互组件都给你封装好了适合做内部工具的面板。如果你需要更完整的多人在线协作白板能力可以考虑基于 tldraw 这类开源项目改造它能支持多人实时协同编辑但定制成本会高一些。2.3 文本生成还是拖拽画布一个避开纠结的决策依据很多项目启动时都会纠结到底该选 Mermaid 还是选 React Flow我觉得这个问题可以简化为三个判断条件第一这张图要不要随着代码一起做版本管理如果要选文本化方案是唯一合理路径。因为图片文件的 diff 几乎没法 review而 Mermaid 代码的 diff 跟代码 diff 一样清晰。第二使用者是否是专业内容生产者如果目标用户是研发、产品经理、架构师他们习惯写文档文本方案上手更快如果目标用户是运营、销售、普通用户那拖拽式可视化更友好因为大家更熟悉“鼠标拖拽”这个动作。第三图的规模和复杂度是否可控文本工具在节点数量到 100 以上时一般就开始力不从心了布局、连线、可读性全面下降这时候图编辑器的优势会体现出来。我见过一个挺可惜的案例有个团队花了大力气用自研拖拽组件做了一套架构图编辑器结果项目下线后所有图都变成死图片没人能再编辑。因为他们的图数据存在私有格式里没有和代码仓库打通。如果当初选 Mermaid 存进 Markdown至少图还在可维护性会高很多。2.4 关于自研图表能力的几条实用经验如果你所在团队最终决定要自己做一套图表设计功能而不是直接接开源方案我给你分享几条踩坑换来的经验。第一图数据结构要松耦合。图的存储格式最好和渲染引擎解耦我用 JSON 描述节点和边节点 id、坐标、样式分离这样就算将来换渲染引擎数据也不用重来。第二坐标系统一用逻辑坐标不要直接存像素值要做缩放适配和高清屏适配才能在不同分辨率的显示器上保持一致效果。第三预留“自动布局”入口手动摆放虽然自由但面对大批量初始数据时一键布局能大幅提升效率。说到自研我特别提醒一点图表编辑器的真实工作量比看起来大得多。你以为是做几个方框和箭头实际上你要处理撤销重做、复制粘贴、对齐分布、缩放手势、连线锚点、国际化换行……每一项都够写一阵子的。所以我的建议永远是先评估能不能直接改造开源项目不要在基础版图上重复造轮子。3. 实操核心环节一用文本描述快速产出高质量图表工具选完了接下来就是硬功夫。我最推荐的日常技术文档图表路径是Mermaid Markdown。这一节我说清楚 Mermaid 的语法细节、布局技巧和常见样式坑。3.1 从零开始一个简单的流程图长什么样Mermaid 最基础的流程图用graph关键字声明。上下左右四个方向都可以指定TB表示从上到下LR表示从左到右。我会先给出完整示例再逐行说重点graph TB A[发起请求] -- B{参数校验} B --|通过| C[调用业务逻辑] B --|失败| D[返回错误码] C -- E[落库] E -- F[返回结果]这段描述生成的就是一张几乎是“标准答案”的流程图一个开始节点、一个判断分支、两条返回路径。注意几个细节节点文本可以不写引号但包含括号、特殊符号时需要引号包裹。关系符号--表示带箭头连线---表示无箭头连线-.-表示虚线箭头表示粗箭头。分支条件写在连线标签里B --|通过| C表示在连线上显示“通过”这个标签。这些语法加起来不到十种但覆盖了绝大多数日常场景。3.2 节点造型与语义让框的形态替你说第一句话Mermaid 里节点可以用不同形状表达不同含义。这个能力被太多人忽略了但实际上对图表的可读性影响巨大。A[矩形]常规处理节点表示一个动作或者一个处理步骤。A{判断}菱形判断节点表示条件分支。A([圆角矩形])柔和边界常用于开始/结束节点或者表示“状态”。A[(圆柱)]数据库节点画存储相关时非常形象。A不对称形状]常用于表示“输出”或“回调”虽然用得少但很贴切。我画系统架构图时会固定把“外部系统”用矩形、“内部服务”用圆角矩形、“存储”用圆柱、“判断”用菱形。篇幅一多读者不用读文字只看形状就能分辨元素类型。这件事看起来很小长期坚持下来文档的一致性会明显提升。3.3 子图复杂架构图的分层表达节点超过 15 个之后扁平排列就开始显得乱。这时应该用子图subgraph做视觉分区。Mermaid 中子图的语法是graph TB subgraph 接入层 A[网关] B[负载均衡] end subgraph 服务层 C[订单服务] D[用户服务] end A -- C A -- D B -- A子图的语义不仅是“好看”它其实是把你的分层思路直接暴露给读者。我自己画架构图时第一件事不是画节点而是先在纸上列出有哪些层、每层有哪些组件。用子图把这些“层”嵌套进去后整张图的层级感就出来了。3.4 中文支持、换行与主题定制Mermaid 对中文的支持在纯前端渲染时通常没问题但如果是在一些服务端渲染环境要注意字体配置。最常见的坑是中文变成方块多半是 SVG 渲染环境缺少中文字体需要指定 CSS 字体栈比如font-family: PingFang SC, Microsoft YaHei, sans-serif;。我自己用的方式是能 CSS 覆盖就 CSS 覆盖不要依赖工具默认设置。换行是一个容易跌跟头的地方。Mermaid 默认不会自动换行你在节点文本里写换行符有时会被忽略。我的经验是短文本尽量控制在一行实在需要多行可以用br/手动换行。但要注意节点文案越多图越大尽量把每段文案控制在 6 个核心词以内不然读者很难快速扫描信息。主题定制方面新版 Mermaid 支持主题变量你可以把主色、描边色、字体调整成你自己的品牌色。我自己的习惯是给不同层级节点设置不同填充色但同一张图里颜色尽量不超过三种不然视觉噪音比信息增量还大。颜色是有语义的不要拿它做纯粹的装饰。3.5 布局控制从“自动布局”到“手动干预”Mermaid 的自动布局在大多数场景下都够用但有一种情况必须手动干预节点间交叉连接太多时自动布局会出现“长线跨越全图”的诡异现象。这类问题通常是因为你的图结构不是严格的层级图存在反向边或者环状依赖。我的经验是优先调整声明顺序。Mermaid 布局高度依赖节点声明顺序把上下游关系在代码里按“从上到下、从左到右”排列生成的图通常更规整。其次是用direction关键字改变子图内部流向比如子图里的节点用LR从左到右能让宽度更均衡。如果试完还不行再考虑把图拆成两张不要在一棵树上吊死。4. 实操核心环节二从需求到成图一张架构图的设计全过程理论讲了一堆现在我用一套“最常见的中小型系统架构图”作为案例把从需求到成图的完整流程走一遍。我会尽量以“如果现在有人让我画这张图我会怎么做”的口吻把思考过程都说出来。4.1 第一步确定图的边界与信息量接到“画一下系统架构图”这个需求时我第一件事不是打开画图工具而是问三个问题图的读者是谁图要表达什么结论图里必须出现的元素有哪些以这张示例图为例我假设读者是来参与方案评审的同事我要表达的核心结论是“新系统分为三层用户流量从入口进来经过网关到业务服务数据落在 MySQL 和 Redis”。基于这个结论我决定图里只需要元素客户端、Nginx、网关服务、订单服务、用户服务、MySQL、Redis。其余像监控、配置中心这类和核心链路关系不大的组件我这次先不画进去。这一步我称之为“信息降噪”。很多架构图难看不是画得差而是包含的信息太多了。你要有勇气对不重要或者与当前诉求无关的部分做裁剪。画图跟做产品一样少即是多。4.2 第二步设计节点、分组与连线关系确定元素后我会先画一张素稿不做任何样式只把节点关系用最简单的方式排出来。这一步我建议直接在纸上或者白板上做因为调整成本最低。我的素稿大概是这样最上面是“客户端”它连到“Nginx”。“Nginx”连到“网关服务”。“网关服务”分别连到“订单服务”和“用户服务”。两个业务服务都连到“MySQL”其中“订单服务”还连着“Redis”。这个阶段不碰样式只用最朴素的方框和箭头。一旦关系在这个层级理清了后面做样式才是顺势而为。关系没理清就直接上手做图大概率会在画到一半时推倒重来。4.3 第三步套用模板与视觉分层素稿定稿后我会进入 Mermaid 编写最终文本。这里实践一个关键技巧用子图把“层”表达出来。我把整个图放在三个 subgraph 里接入层、应用层、数据层。代码如下graph TB Client[客户端] subgraph 接入层 Nginx[Nginx 网关] Gateway[统一网关] end subgraph 应用层 Order[订单服务] User[用户服务] end subgraph 数据层 MySQL[(MySQL 主库)] Redis[(Redis 缓存)] end Client -- Nginx Nginx -- Gateway Gateway -- Order Gateway -- User Order -- MySQL User -- MySQL Order -- Redis这段代码生成的图其实已经“能看”了但我会继续做三处视觉优化第一给子图添加direction LR让服务在应用层里横向排列整体图的宽度会更均衡。第二调整节点文字统一不加多余语气词例如“MySQL 主库”就很清晰。第三让不同层的节点填充色有区分接入层浅灰、应用层浅蓝、数据层浅绿图例在描述里写明颜色代表什么。4.4 第四步反复权衡连线的“直”与“绕”文本代码生成后我会重点关注两条信息通道连线的长度与交叉次数。Mermaid 自动布局经常会把 MySQL 这条线拉得很长跨越整个图。我的处理思路很直接把数据层子图放在最底部业务服务子图尽量贴近数据层的上方这样连线下落的距离最短。你不需要每一步都精确控制坐标只要层级和声明顺序合理布局算法通常会给你一个相当可以接受的结果。还有一个经常被忽略的细节连线的方向要和阅读方向一致。在中文技术文档里读者习惯从左到右、从上到下扫描信息。所以架构图中我一般把最外侧的入口放在左上角数据存储放在底部流程图里则把开始节点放在顶部结束节点放到底部。方向一乱读者第一眼就会迷路。4.5 第五步导出与嵌入的“最后一公里”图做好了绕不开导出。如果是在线文档里使用优先用内置的 Mermaid 渲染不需要导出图片。但如果要放进 PPT 或外部文档务必导出 SVG 而不是 PNG。SVG 是矢量图放大多少倍都清晰而且文件体积小。用 Mermaid CLI 或在线工具导出 SVG 时我一般还会把字体替换成常见系统字体不然换个电脑打开字体不对版式就全乱了。如果你走的是 diagrams.net 这类拖拽工具导出规则更讲究。嵌入 Word 或 Notion 时可以导出 PNG 但把 DPI 调高一些一般 2 倍缩放就能让大多数显示器下足够清晰另外记得导出时勾选“包含背景色”否则透明背景在深色主题的文档里会显得很突兀。5. 常见问题与排查技巧实录图表设计里那些“地雷”技术类文章最有价值的部分永远是“问题排查”。因为工具官方文档只会告诉你语法不会告诉你“为什么我照着写了还是乱”。这一节我盘点自己在 diagram-design 实践里踩过、帮别人排查过的高频问题每一个都附上解决思路。5.1 布局混乱节点乱飞、连线横穿这是文本生成图工具最大的痛点。Mermaid 自动布局在大图上容易崩坏核心原因通常是图中存在反向依赖或环状结构而自动布局算法对 DAG 最友好。我的排查顺序是先数节点数量超过 20 个先拆图然后把所有连线列出来找出“反向边”也就是从下层指向上层的边尽量用设计手段消除它如果环状逻辑确实存在比如任务重试可以考虑用子图把环压缩成一个小单元不让它参与全局布局。最后如果以上都不行我只能说这张图可能真的不适合用 Mermaid 画换拖拽工具手动排版反而更快。5.2 中文乱码与字体问题中文乱码在本地 CLI 导出时容易出现。主要原因就是渲染时找不到中文字体于是在 SVG 里生成了乱码或方框。解决方法指定字体。用 Mermaid CLI 时可以在puppeteerConfigFile里配置 Chrome 的字体路径用 Docker 跑 CLI 时镜像里要先装fonts-noto-cjk这类中文字体包。如果你是在 Vitepress、Docusaurus 这类静态站点里渲染 Mermaid则通常不会乱码因为浏览器自己会匹配系统字体。此时真正要注意的是字体渲染风格Windows 下默认中文字体是微软雅黑Mac 下是苹方两边看起来粗细不一样。为了让文档在跨平台时观感一致我会在全局样式里设置font-family为固定的中英文字体栈。5.3 导出清晰度为什么我的图放大后全是马赛克有太多人直接在浏览器里对图截图然后塞进文档里被老板投影到大屏上之后模糊到没法看。根本原因是位图的分辨率不足。我的建议很简单优先导出 SVG任何矢量图工具都支持如果工具只支持位图导出就用 2 倍或 3 倍 DPI 导出。还有一个小技巧导出时不要带多余留白很多工具的“严格边界导出”选项能自动裁掉空白边缘插入文档时比例更协调。5.4 大型图表性能问题卡顿和渲染失败当单张图的节点数量超过 100 个时无论是 Mermaid 的浏览器渲染还是 diagrams.net 的大画布编辑都可能出现明显的卡顿。我的处理策略是分而治之把一张大图拆成“总览图 细节图”的组合。总览图里只画模块框每个模块内部细节用一张独立的细节图表达。两张图用链接互相跳转阅读体验反而更好。这里我还想强调一个工程思维图表维护是长期成本。如果你维护一张巨大的、好几周没打开过的图模块边界一变图很容易就失效了。有了总览图和细节图的拆分后总览图很少变化细节图按模块独立更新整体维护成本会大幅下降。5.5 多人协作与版本管理图的“维护”比“生成”更重要图表界的“孤儿现象”太常见了某次架构升级后代码改了三轮架构图纹丝不动。为什么因为大多数人是把图当成一次性的“设计交付物”而不是持续维护的“项目资产”。正确的做法是把图表的源文件纳入仓库和代码一起走评审流程。如果是 Mermaid 这类文本图天然适合放进 Git如果是 diagrams.net 文件它的格式本质是 XML也能存 Git但 diff 的可读性极差所以用这种工具时更需要在团队里约定“谁负责更新图什么时机更新图”。我还建议在图的注释或描述里写上“上次更新时间”和“维护负责人”这一条小约定能让文档的存活率提升很多。6. 关于图表设计最后想分享的一点体会图表设计这个能力说到底是把“思维可视化”的能力。工具永远在迭代今天的主流方案可能过两年就落伍但一个核心能力不会过时你能否通过方框、箭头、颜色和布局准确地承载一个复杂逻辑并让读者在三十秒内抓住重点。我给团队培训时常说画图的时候你不要把自己当成一个画图的而是要当成一个“信息结构的剪辑师”。你手里的每个节点都是素材你的工作不是把素材全部堆上去而是裁剪、排序、划重点。这个视角转换之后你的图会从“记录”变成“表达”从“能看”变成“好用”。如果你最近正在做一套系统设计、写技术方案或者只是想把一个拖延了很久的流程梳理清楚我建议你从今天起就用 Mermaid 或者其他画图工具把那个脑内混乱的“大东西”拆成一张清晰的小图。先画出来再慢慢调图上每一个框框和箭头最终都会倒逼你把问题想得更透。这大概就是 diagram-design 带给我的最大乐趣。