我第一次认真对待 diagram-design 这件事是接到一个“把整个系统的架构图重画一遍”的任务。当时我以为自己有多年画图经验拖拽方框、连线、加箭头轻车熟路结果画出来的图技术评审会上被问得哑口无言这张图到底想表达什么哪个是核心链路哪个是旁路新同学能靠这张图理解系统吗我当时沉默了。从那以后我开始系统性地研究 diagram-design而不是把它当成“画图”这个动作。它其实是一套把信息结构化、视觉化的设计方法。图表的背后是逻辑布局的背后是思维颜色的背后是信息优先级。这篇内容想把我积累下来的设计思路、工具选型、实操步骤和踩坑经历完整记录下来送给所有需要画架构图、流程图、时序图又不想画得“一看就是外行”的人。1. diagram-design 到底是什么先给这个领域画个边界1.1 图表设计的真实定位从“画图工具”到“系统化表达”很多人一听到 diagram-design第一反应是“用什么软件画图”。这是一个很常见的误解。软件只是落笔的工具diagram-design 的本质是把一组信息之间的关系通过可视化方式表达出来而且要让观众在最短时间内看懂这层关系。举个例子同样描述一个订单系统你可以用五百字写清楚用户下单、库存扣减、支付回调、消息通知的流程。但如果你对着运维同事讲一张部署架构图比五百字高效十倍如果你对着研发同事讲一张时序图比文字精确十倍。diagram-design 解决的核心痛点就是信息传递过程中的“理解成本”。所以当你开始设计一张图的时候最先问自己的不是“用什么工具”而是“这张图给谁看、要传递什么结论”。目标不同图表类型不同设计手法完全不同。这一点是整套 diagram-design 方法论的基石。1.2 一张好图的标准信息准确、结构清晰、一眼能懂我见过的烂图千奇百怪但好图几乎都有共性。根据我自己的经验判断一张图是否是“合格的设计”其实就三个标准信息准确图中表达的内容没有概念错误箭头方向、依赖关系、分组边界都经得起推敲。这是底线信息不准画得再漂亮也是废图。结构清晰观众第一眼能识别出“谁是主干、谁是分支”。好的结构是层级分明而不是把二十个节点平铺在一起让人盯五分钟也找不到入口。一眼能懂不需要作者站在旁边解释也不需要看图的人去猜“这个虚线是什么意思”。图形语言的语法应该自洽读者靠常识就能理解。这三个标准看着简单实际操作中想同时满足需要大量练习。很多时候我们画图只关注“节点和连线”却忽略了“留白”“对齐”“分组”这些看似无关的设计因素。而这些因素恰恰决定了图能不能被快速读懂。2. 主流 diagram 工具怎么选别急着开画先看需求2.1 代码驱动 vs 拖拽驱动两类工具的核心差异工具选型本质上是选择一种“图表的维护方式”。市面上的 diagram 工具大致可以分成两类代码驱动型如 Mermaid、PlantUML、Graphviz、D2和拖拽驱动型如 Draw.io、Excalidraw、Figma、Visio。代码驱动型的核心优势是图表即代码。你能把图表内容放进 Git 仓库里做版本管理代码审查时顺便就审掉了一张架构图。改一个流程不需要打开画板重新拉线改一行文本重新渲染就行。优点是适合持续更新的图缺点是对排版控制力弱复杂的布局需求经常要花时间调参数。拖拽驱动型的核心优势是自由度高。你完全控制每一个方框的位置、连线的方式、视觉的细节适合做汇报材料、方案文档中的一次性配图。缺点恰恰是更新成本高改一个节点位置往往要带动周边一系列元素一起调整维护成本会随时间急速上升。我给团队定过一个简单的工具选型规则如果这张图的内容会随代码迭代而频繁变化或者需要多人协作 review优先选代码驱动如果这张图只服务一次汇报、方案、评审用过即弃那拖拽工具效率更高。2.2 我经常用来组合的方案与适用场景下图是我实际工作中常备的几种工具组合它们的定位并不冲突工具类型我的典型使用场景优缺点一句话描述Mermaid代码驱动文档内嵌的流程图、时序图、状态图、甘特图语法简单跟 Markdown 文档结合得最好但复杂布局容易乱Draw.io拖拽驱动架构图、网络拓扑、机房部署图免费、离线可用、不占资源但对审美要求高需自己把控排版Excalidraw拖拽驱动头脑风暴草图、解释性示意图、会议速记手绘风格天然有“草稿感”适合降低沟通压迫感但精致感不足D2代码驱动需要精确控制的架构图、复杂交互图布局算法比 Mermaid 强很多语法现代适合新项目引入GraphvizDOT代码驱动大规模节点关系自动布局、依赖关系分析自动布局能力极强但上手陡写 DOT 语法像编程这几款工具推荐大家不要迷信其中某一个。它们各有各的适用场景组合使用才能覆盖大多数需求。比如我经常先在 Excalidraw 里快速画草稿理清逻辑然后用 Mermaid 嵌入到项目的技术文档中最后在需要汇报时用 Draw.io 做一版更精细的图。2.3 工具选型的一个关键判断这张图的生命周期判断工具的一个重要维度是问“这张图的寿命有多长”。如果你画一张图只是为了今天下午的内部讨论会那 Excalidraw 一分钟出一张草图完全没有问题没必要上严肃工具。但如果你画的图是系统架构图、核心业务流程图未来半年会被新同学反复阅读被评审会反复引用那强烈建议选择代码驱动型工具。原因很朴素因为你未来一定会改它。系统一迭代架构图就得跟着更新。如果这张图存在一个普通文件里大家没有动力维护如果它存在于 Git 仓库随着每次代码提交自动更新维护就变成持续集成的一部分。我曾经接手过一个项目技术文档里嵌入了十几张架构图全部是某个同事用在线工具画的原文件存在他个人网盘里人离职后这些图成了“不可修改的历史文物”。后来重绘这些图花了一个多星期。这个教训让我彻底转变了观念凡是要长期存活的图坚决代码驱动坚决入库坚决纳入代码审查流程。3. 核心设计思路布局、层级、配色、样式一次说透3.1 布局先定主方向再谈细节布局是 diagram-design 里最容易被忽略、却又最影响阅读体验的环节。很多图之所以“看起来乱”不是信息量太大而是布局没有主方向。我处理布局时习惯遵循一条原则先决定图的主题流向再决定每个节点的具体位置。流程图通常采用自上而下或从左到右的流向架构图通常采用分层或分组的流向时序图则天然带有时间轴。主方向定了之后下一个关键是“对齐”。节点与节点之间的边界对齐文字与图形中心点对齐分组与分组之间的间距一致。这些细节决定了图是“专业作品”还是“随手涂鸦”。不要小看像素级对齐差的几个像素在人眼看来就是凌乱感和廉价感的分界线。从实用技术角度看代码驱动工具里可以通过行列布局参数来尽量对齐拖拽工具里Draw.io 有“对齐分布”的功能Excalidraw 也可以框选多节点后一键等距。这些都是提升布局质量的利器。3.2 层级一张图里至少要有三层信息好的图不是平面化的它有明确的视觉层级。这个概念借用了平面设计里的“视觉层”理论翻译到图表设计里我的理解是每张图中至少要有三层信息第一层是主干信息一眼就能看明白这个图在讲什么。比如流程图的开始与结束架构图的顶层入口与底层依赖。第二层是支撑信息主干节点之外的次级节点帮助观众理解主干是如何运转的。第三层是辅助信息注释、边界、分组标签、外部依赖。这一层通常是虚线框、灰色文字或小字号说明。实际操作中最有效的层级表达手段是“降低辅助信息的视觉权重”而不是一味放大主干节点。把注解信息淡化成浅灰色把弱关联节点缩小一号把主链路节点的颜色加重。通过强弱对比建立层级比单纯堆砌颜色更高级也更符合大脑阅读图形的习惯。3.3 配色与色板颜色不是装饰是信息通道我在早期的图表设计里有一个坏毛病觉得图太单调于是往里面填充各种花里胡哨的颜色。后来发现颜色多不代表好看反而让信息变得混乱。在 diagram-design 里颜色应当承担“信息编码”的功能而不是单纯的装饰功能。一个稳扎稳打的配色方案是默认情况下只使用三种颜色。一种用于强调核心节点通常用品牌色或高饱和色一种用于常规节点通常用浅灰、浅蓝等中性色一种用于警示或异常通常用橙红或红色系。这三种颜色足够覆盖大部分图表的表达需求。此外要注意颜色的可达性。红绿色盲的人群占比不低如果一张图只用红绿两色来区分状态对这部分读者就是灾难。建议用“红蓝”“橙青”这类色相对比或者同时附加形状、文字等非颜色标记来区分状态保证不依赖颜色也能读懂图。3.4 字体与间距影响观感的最隐蔽变量字体和间距不是 diagram-design 的核心内容但它们在最终的图面效果中占据的分量越来越重。我见过一些图内容逻辑很好但字号忽大忽小、字体混用宋体黑体、文字贴着边框观感一下子降到草稿水平。实用建议是所有节点内的文字尽量保持同一字号除了层级标题且文字与节点边距至少留出 20%30% 的余量跨组件的连线标签字号继续缩小一号整张图间距保持一致——节点之间的最小间距不应小于节点边长的一半。这套规则适用于绝大多数场景。还有一个实操细节代码驱动工具里很多丑陋的默认布局问题可以通过全局 CSS 或主题配置解决。给字体家族统一设置为无衬线字体如 Arial、Helvetica、PingFang SC再配置节点内边距 padding整张图立刻会“专业”不少。很多团队的自建图模板核心改动其实就藏在这些细节里。4. 实操从零完成一套体系化 diagram-design 设计4.1 准备阶段先梳理节点和关系而不是先画我见过太多人一上来就打开工具开始画框画到一半发现漏了一个关键节点又推倒重来。这个痛点的根源是跳过了“信息梳理”的阶段。推荐的做法是在一张草稿纸或者白板工具上先列出所有“名词节点”系统、模块、角色、状态再列出所有“动词关系”调用、依赖、触发、返回。把所有要素和关系摊开之后再去思考布局与呈现方式。举例来说我要画一个“订单履约系统”的架构图准备阶段我应该先罗列出订单服务、库存中心、支付网关、物流服务、消息队列、数据库、外部供应商 API、运维监控……再罗列出它们之间的调用关系。这个阶段只做两件事“我有什么”和“它们之间有什么关系”。做完之后再考虑把哪些节点放在同一层哪些关系要画实线、哪些画虚线整体采用什么布局方向。4.2 用 Mermaid 实现架构图从零到一的操作过程Mermaid 是目前我在文档内嵌图表时使用频率最高的工具。它的语法简单最快的用法是直接写graph TD加节点和连线。以订单履约系统的简要架构为例一个基础版本可能是这样的graph TD A[前端] -- B[订单服务] B -- C[库存中心] B -- D[支付网关] D -- E[第三方支付] B -- F[消息队列] F -- G[物流服务] G -- H[物流供应商] B -- I[(数据库)]写完之后把这个代码块放到支持 Mermaid 渲染的 Markdown 工具中就能立刻得到一张可读的流程图。这是最基础的用法但实际工程文档里我们通常需要更多控制用subgraph把同一层级的模块包进同一个视觉组用classDef定义不同类别的样式比如核心服务用高亮色外部依赖用灰色用--|HTTP|或-.-区分同步调用和异步依赖用direction控制子图内部布局的方向。一个加入了分组和样式的改进版大概长这样graph TB subgraph Client[接入层] A[前端] B[开放 API] end subgraph Core[核心服务层] C[订单服务] D[库存中心] E[支付网关] end subgraph External[外部依赖] F[第三方支付] G[物流供应商] end A -- C B -- C C -- D C -- E E -- F C -.-|MQ| H[消息队列] H -- G这类带分组、带区分样式的图已经能够应付大部分技术文档场景。如果团队有自己的主题审美还可以通过配置项统一设置颜色、边框、字体让所有图保持一致的视觉风格这也是 diagram-design 走向体系化的重要一步。4.3 用 Draw.io 和 Excalidraw 做精细调整代码驱动工具能解决 80% 的问题但有些细节——比如“这张架构图要给 CTO 汇报图形间距、色块面积都要有设计感”——仅靠代码工具很难控制到位。这种时候我会把代码驱动工具生成的底图导出再放到 Draw.io 或 Excalidraw 里做微调。具体操作是先用 Mermaid 生成 SVG 底图用 Draw.io 打开 SVG 后可以继续编辑路径、节点和文本。Draw.io 支持导入 SVG 之后保留可编辑语义这是一个被很多人忽略的强大功能。另一些场合我也直接在 Excalidraw 里从空白画起它的手绘风格让图面天生有一种“示意图感”适合用于需求沟通而不是最终交付。如果你需要更精细的控制Draw.io 几乎能满足全部需求支持自定义形状库、图层管理、几何约束、表格样式。在图层面板里把背景、分组名称、节点、连线放在不同层调色和排版会变得异常轻松。这是我推荐把 Draw.io 当作精细调整工具的原因。4.4 导出与发布不同场景的输出选型一张图设计完成后最后一个环节是输出。不同场景对输出格式的要求差异很大这里分享我踩过坑之后总结的导出选型策略使用场景推荐导出格式注意事项技术文档在线SVG 或内嵌 Mermaid 代码SVG 文字清晰可无限放大尽量不导 PNG技术文档离线/Word/PDF高分辨率 PNG200%注意缩放后文字是否发虚幻灯片汇报SVG 或透明背景 PNG透明背景能跟 PPT 主题融合避免白底方块打印PDF矢量格式不受缩放限制网页/微信公众号PNG压缩过控制图片体积避免文件过大加载慢如果你使用的是代码驱动工具我的习惯是把原始代码放进文档仓库把生成后的 SVG 文件也提交到仓库这样既保留了可维护性也方便在离线场景下直接引用图片。5. 常见问题与排查技巧实录5.1 布局乱飞、连线交叉严重怎么破代码驱动工具最常见的抱怨就是“布局不可控”。Mermaid 有时候会自动给你分配一个很别扭的位置D2 在复杂关系下也偶尔会有连线交叉。解决思路不是硬调坐标而是调整语义层面的结构。我的排查顺序是检查 subgraph 分组是否合理。很多交叉是因为没有分组导致节点分散在画布各处把同层级的节点包进 subgraph 后布局通常会大幅改善。减少不必要的关联线。有时候两个节点之间的关系可以通过旁注文字表达不必拉一条线出来。必要时拆分大图。如果一张图有超过 20 个节点、30 条连线别硬画一张“世界地图”拆成多张主题清晰的小图比一张复杂的巨图效果好得多。最后才考虑工具参数。Mermaid 可以调布局方向Graphviz 可以调 ranksep、nodesep 等参数但这些是最后的手段语义层面的优化优先级更高。5.2 中文字体与乱码问题在图里写中文几乎每个工具都会遇到字体问题。症状包括中文字体变成方块、导出时中文模糊、代码工具渲染时中文字体体积巨大。排查经验是分工具对待Mermaid 里在主题配置中指定fontFamily为系统中文字体如“PingFang SC”“Microsoft YaHei”能解决大多数样式问题导出 PDF/SVG 时偶尔出现乱码优先检查渲染环境是否缺少中文字体。Draw.io 导出 PDF 时中文字体丢失可以在“文件—导出为—PDF”中勾选“包含文本”为“SVG 单文本”同时检查系统中文字体已安装。Excalidraw 主要是浏览器字体渲染大部分问题通过选择正确的浏览器字号可以规避。5.3 导出模糊、边界被裁切这个问题最隐蔽也最恼火。一张图在编辑界面看着好好的导出后元素却被切掉半边或者线条发虚。这是两类原因导致的一是画布边界没有留白。很多工具的自动布局算法把元素铺满整个画布没有预留外边距。解决方法是导出前在画布四周主动加上一圈“占位空白”——我常用的做法是在画布边缘放一个透明的矩形尺寸比内容大 20 像素导出后再删除。二是放大倍率不够。导出 PNG 时尽量选择 2 倍或 3 倍缩放尤其是有小字号文字细节的图。不要觉得文件体积大现代文档平台对图片体积的容忍度还比较高清晰度损失是补不回来的。5.4 团队协作时图被改乱版本管理才是关键最后一个常见问题不是画图本身而是多人协作时图的版本管理。前面提过技术文档中我强烈推荐使用代码驱动的图表并且把图表源文件放在 Git 仓库里。这样一来任何人改图都会有 commit 记录评审时能清楚看到这次改动调整了哪些节点和关系出问题了也能回溯。我自己的实践是在仓库里建立一个docs/diagrams目录约定所有长期存活的图表都以 Mermaid 或 D2 源码存放并在代码评审中加上一条强制要求凡是涉及架构变更必须同步更新对应图表。这个习惯坚持了半年效果非常显著团队新人在做技术调研时依赖的文档可靠性高了很多。6. 从“能画图”到“设计图”一些实战心得6.1 图表设计中的“少即是多”做了大量 diagram-design 实践之后我最大的感悟是画图的关键不是把所有东西都放进去而是把不需要的东西拿出来。很多技术人画图时有一种“信息暴露癖”恨不能把所有接口名、类名、配置项都写进图里。但观众的注意力是稀缺资源。一张合格的图应当在任何一秒内只突出一个重点信息。假如你在画一张系统核心调用链路的图那就不要花精力把日志收集、监控告警这些旁路画进去。你可以用一句“监控系统另行出图”带过。压缩信息量有时比丰富信息量更难但这才是 diagram-design 真正产生价值的地方。6.2 让图“自己说话”的几个小技巧观察过很多优秀的图表之后我发现了几个让图更专业的小技巧这些不是理论都是我反复用过觉得好用的给每条连线写动作词不要只画一条线在线上标注“创建订单”“扣减库存”“回调通知”。这能让观众少猜十次。把节点命名改成“动词名词”一个节点如果是“订单服务”尽量写成“创建订单”或“查询订单”让每个节点都像一个可读的故事片段。分组边界要清晰边界虚线或背景色块可以瞬间传达出“这组是一类东西”能显著减少读者认知负担。留白是真本事别把画布填得满满当当适当留出空区让眼睛有休息的地方。6.3 关于沉淀一套“团队图规范”的建议如果你认同图表在团队协作中的价值那下一步值得做的就是建立自己的“图表设计规范”。规范不需要复杂我建议先从一个最小清单开始统一图表工具、统一代码库位置、统一基础配色、统一标题与图例格式。这套规范被团队接受后新同学加入时能快速上手产出的图表风格也保持一致。沉淀规范还有一个隐藏好处当图表成为团队知识的一部分系统的可读性、协作效率都会显著提升。我发现那些“说明文档没人看”的团队往往不是文档数量不够而是图表设计一团乱麻读起来太费劲。一个能让人三秒看懂核心架构的团队沟通成本肉眼可见地低。回头再想当初那个让我尴尬的技术评审会其实问题不在我“不会画图”而在于我从来没把 diagram-design 当做一个正经的设计学科来对待。工具技巧很快能学会真正拉开差距的是设计思维结构怎么组织、信息怎么取舍、颜色怎么表达语义、一张图应该给观众留下什么结论。这些能力会在一次次刻意练习里慢慢长出来也希望这篇分享能帮你少走一点弯路。