diagram-design实战：从架构图到流程图的清晰可维护绘图方法

围绕 diagram-design 这件事这些年我在不同项目里画过不下上百张技术图。最直观的感受是大多数团队不是缺画图工具而是缺一套把图画得清楚、可维护、能协作的方法。diagram-design 并不是指把节点和线条排得有多好看而是让一张图在评审会上三十秒内就能被看懂、在文档里三个月后还能被改懂。这篇东西写给所有需要画架构图、流程图、时序图的人不管你是后端、前端、运维还是技术管理只要有过“图越画越多越画越乱”的经历应该都能找到一些能直接抄用的方法。1. diagram-design到底在解决什么问题1.1 图表的本质是降低沟通摩擦很多人把画图当成一种“交付物”觉得只要在方案文档里塞几张图就算完成了设计。实际上 diagram-design 解决的核心问题只有一个把复杂系统的结构、流程和关系变成人眼可以快速扫描的信息。举个例子你给团队讲一个消息队列的消费链路用嘴巴说五分钟大家可能还是一脸茫然。但如果你画一张图把生产者、队列、消费者、死信队列、重试机制摆在那里别人十秒钟就能看出数据往哪儿走、瓶颈在哪儿、失败之后会发生什么。这不是因为图比文字更漂亮而是因为人类大脑对空间关系的处理速度远远快于对线性文字的处理速度。一张合格的图本质上是一张“认知地图”它让读者不用在脑子里临时搭模型直接把现成的模型喂给他。我见过不少团队花了大量时间在 Word 和 PPT 里堆文字方案却不愿意花半小时把结构画清楚。结果评审会上所有人都在反复问同样的问题这个模块到底依赖哪个服务数据流是从左往右还是从右往左失败分支怎么处理这些问题的根源不是表达能力差而是没有用 diagram-design 的思路把信息结构化。说到底画图不是为了应付文档规范也不是为了显得专业。它是把“我脑子里想明白了”变成“大家脑子里都想明白了”的最短路径。想清楚这一点后续所有的工具选择、布局习惯、配色规则都会变得有方向。1.2 三张图覆盖九成设计场景做了这么多年 diagram-design我统计过自己实际画过的图发现真正高频使用的其实只有三大类。第一类是结构图典型代表是系统架构图、模块依赖图、ER 图。这类图回答的问题是“系统由哪些部分组成它们之间是什么关系”。画这类图的核心难点在于分层你需要决定把哪些细节放在图里哪些细节留在图外。很多架构图画得密密麻麻就是因为作者把所有层次的东西一股脑塞进一张图结果谁看了都头疼。第二类是流程图典型代表是业务流程图、时序图、状态机图。这类图回答的问题是“某个过程按什么顺序发生每个环节的分支和异常如何处理”。画这类图最容易犯的毛病是过度追求完整性把极其边缘的分支也画进去导致主路径被淹没。好的流程图应该让人一眼看到主干再看分支。第三类是部署与拓扑图典型代表是网络拓扑图、容器部署架构图。这类图回答的问题是“组件实际跑在哪里流量怎么流转”。它和架构图的区别在于多了物理位置和网络分层的维度如果不用统一的图例说明很快就会变成一团乱线。我在团队里做 diagram-design 规范时通常会明确告诉大家先判断当下要画的图属于哪一类然后只保留这一类需要的信息。结构图不要画流程流程图不要画依赖拓扑图不要画业务逻辑。混搭是图变得难看的头号原因。1.3 什么时候不该画图这一点很少有人提但我认为它是 diagram-design 里非常重要的判断力。并非所有信息都适合用图画出来有些场景用表格更高效有些场景用文字反而更清晰。我的经验是当关系数量超过十个、且关系种类超过三种时图就会开始失控。比如一张图里有服务、数据库、缓存、消息队列、定时任务五种节点又有依赖、调用、订阅、写入四条边再加上每个节点三四个属性这张图基本没法看了。这时候更好的做法是把静态属性放进表格把动态调用关系画成图。另一个不适合画图的场景是信息还在快速变化的时候。项目刚开始需求每天都在调整组件说加就加、说删就删。此时花两小时精心画一张架构图第二天就过时了成本很高。正确的做法是先画一张极简的、只有核心模块的草图让团队围绕这张草图讨论等结构稳定下来再投入精力细化。判断要不要画图我给自己定的规则是如果一段话超过三句话才能讲清楚关系考虑画图如果一段话三句话以内能说明白先别画用文字写下来。图应该用来解决“关系复杂”的问题而不是用来解决“懒得写”的问题。2. 工具选型不同场景下的方案怎么选2.1 主流工具的横向对比聊到 diagram-design工具永远是绕不开的话题。我见过有人为了一个流程图专门学复杂的建模软件结果学了三天还没画出一张像样的图也见过有人坚持用代码画图结果团队里只有他一个人能改。工具选型的核心原则应该是“团队大多数人能上手”排在第一位而不是“功能最全”排在第一位。这里按使用场景把常见的工具分成三类。画布类工具适合交互式绘制最常见的有 draw.io开源流程绘图工具、Excalidraw、Figma。这类工具的特点是所见即所得上手成本极低适合画架构图、网络拓扑图和业务流程草图。其中 draw.io 胜在免费、离线可用、和 GitHub 集成方便Excalidraw 胜在手绘风格、颜值高、适合快速画草稿和头脑风暴Figma 胜在协作实时性强、适合需要 UI 细节的图但对纯技术图来说略重。文本生成类工具适合与代码库一起维护典型代表是 Mermaid文本描述图表的脚本语言 和 PlantUML文本描述 UML 图表的工具。这类工具用代码描述节点和连线可以放进 Git 仓库做版本管理也能直接嵌入 Markdown 文档自动渲染。缺点是绘制复杂布局时控制力弱而且语法需要学一下。专业建模类工具比如 Enterprise Architect专业建模工具和各类 UML 工具功能非常重适合严谨的 UML 建模和大型系统架构治理。对绝大多数互联网团队来说这类工具都过于笨重画一张简单的时序图要建一堆模型我把它们归类为“特定场景才会用到”。我个人的建议是默认团队里准备两个工具一个画布类用于日常讨论和方案设计一个文本生成类用于沉淀到文档和代码仓库。两者互补而不是二选一。2.2 不同团队的选型思路工具选型不能只看工具本身还要看团队的协作习惯和已有技术栈。如果是后端为主的团队仓库里已经有大量 Markdown 文档那文本生成类工具一定要纳入标配。把架构图、时序图用文本描述放在 docs 目录下改动走代码评审流程历史记录一目了然。我在一个项目里吃过亏当时用画布工具画了架构图后来架构调整图在本地被改得乱七八糟Git 里全是二进制冲突根本没法合并。换成文本生成类工具之后图的变更和代码一样可 review这个问题彻底消失。如果是产品、设计、研发混合协作的团队那更看重实时协作和低门槛。Figma 或者 Excalidraw 这类在线画布工具更合适因为产品经理和设计同学不需要写语法直接拖拽就能参与讨论。这种场景下图的“时效性”比“规范性”更重要画得稍微丑一点没关系重点是大家能实时改。如果是做对外交付的技术方案比如给客户做架构设计文档那我建议用画布类工具配合严格的模板规范导出成高清图片或 PDF。客户不一定能打开你的源文件但看得懂你的图。此时还建议在图上加上图例、版本号和日期避免客户拿到图之后不知道是不是最新版。提示工具可以很多但图应该只有一个“源文件”。不管你选哪种工具都要固定下来不要出现同一张架构图在三个工具里各存一份的情况。这也是团队协作里最容易翻车的地方。3. 从零画好一张架构图实操步骤与设计规范3.1 画图前的信息整理很多人画图一上来就开画画到一半才发现漏了一个模块或者多了一条逻辑上不存在的连线。正确做法是先做信息整理再动手画。我习惯用清单来梳理画图所需的信息。第一步列出图里必须出现的所有核心节点。比如画一个订单服务的架构图脑子里先把订单接口、订单处理、支付回调、库存扣减、消息通知这些节点列出来。第二步标出哪些节点是外部依赖、哪些是内部服务、哪些是数据存储。第三步画出节点之间的关系区分清楚是同步调用、异步消息、还是数据读写。第四步明确这张图的边界哪些内容属于当前范围哪些内容只是背景。这一步做完画布上会呈现什么样子心里基本有数了。这时候再做减法如果一个节点只能算背景信息而不是核心链路的一部分就果断拿掉。信息整理阶段的核心原则是“宁可少不可乱”。一张图上超过 15 个核心节点就值得拆成两张图了。还需要注意节点的命名统一。同一类节点用同样的词比如“用户服务”不要在这一块叫“用户中心”、在另一块叫“账户模块”。命名不统一是图看起来乱的一个重要原因而且这种乱是潜移默化的读者不一定能说出哪里不对但就是觉得不舒服。3.2 布局、连线与配色的落地方法信息整理完之后开始进入布局阶段。布局是整个 diagram-design 里最考验经验的部分我总结了几个可以直接套用的规则。第一主流程优先占主导位置。如果是流程图主流程从左上到右下或者从顶部到底部异常分支放在侧边。如果是架构图读图顺序一般是“上到下”或“左到右”外部依赖放最上核心业务放中间基础设施放底部。第二节点之间保留足够的间距。至少是节点宽度的一半。间距太窄整个图显得拥挤间距太宽图会变得松散读者很难把相关节点视觉上关联起来。把相关节点就近摆放形成一个个视觉小组组与组之间留白比用框线框起来更自然。第三连线尽量走正交线不要画斜线。斜线在视觉上会制造混乱感让人感觉交互很复杂。正交线虽然看起来不那么“自由”但清晰度远高于斜线。连线交叉时尽量绕开如果不小心出现交叉说明布局顺序可能需要调整。配色方面我的经验是同一类节点用同一色系而不是每个节点都换一个颜色。比如服务类节点都用蓝色系数据存储用绿色系外部系统用灰色系异常链路用红色系。全图颜色数控制在三到四种最多不超过五种。颜色是分类工具不是装饰工具用多了反而等于没用。3.3 文字、尺寸与导出规范文字是 diagram-design 里最容易被忽视的细节。字号大小要分层级图标题最大容器名次之节点名再次之注释文字最小。如果一张图里所有文字都一样大读者就分不清哪里是重点。节点名称尽量控制在五个字以内长名称要么缩写要么拆成两行。实在无法缩短的可以把详细说明放进注释或旁边的小字里。连线上的标签文字一句话能说清楚的绝不放两句话比如“调用”“订阅”“读写”就非常清晰了。尺寸与导出规范很多人踩过坑。日常讨论用的图画布大小没有严格要求但一旦要放进正式文档就要注意分辨率和留白。导出图片时优先选择 SVG 格式。SVG 是矢量格式放多大多缩放都不会模糊比 PNG 更适合文档和演示。如果一定要导出 PNG至少把缩放倍数调到 2 倍以上保证在屏幕上放大看也清晰。还需要在图纸四个方向留出边距不要让节点“顶到”画布边缘。建议四周留出至少 20 像素以上空白这样图放进文档时不需要额外裁切。4. 一个完整案例拆解某业务系统的架构图设计4.1 案例背景与信息骨架用一个具体案例走一遍完整流程。假设现在要为某业务系统画一张技术架构图背景是团队准备做一个版本升级需要给团队和项目干系人讲清楚现有系统的整体结构。按照前面的方法第一步不是开画而是先整理信息骨架。经过初步梳理系统包含以下内容前端应用Web 端、管理后台、接入层入口网关服务、业务层用户模块、订单模块、支付模块、数据层主数据库、缓存、中间件消息队列、外部依赖第三方支付服务以及基础设施日志收集、监控告警。经过筛选真正需要在这张图里体现的核心节点大概有十个左右。外部依赖里第三方支付服务是核心链路的一部分保留日志收集和监控告警不属于业务主链路但因为要说明系统可观测性放在底部基础设施层。这样信息骨架就变成了四层外部依赖、接入与业务层、数据与中间件、基础设施。我建议这种层级划分用一张草稿先试画。不需要精致的配色只要确认层次关系无误再在正式工具里绘制。这个过程能帮你省掉后面大量返工的时间。4.2 分层设计与元素摆放在正式画布上我先把画布从上到下分成四块区域用虚线框标出每一层的大致范围。注意虚线框只作为分组暗示不需要给每个节点都画一个实实在在的大实线框那样看起来像套娃反而显得笨重。外部依赖层放在最顶部只有两个节点第三方支付服务和第三方登录服务。接入与业务层放中间偏上位置入口网关服务放在最上方用户模块、订单模块、支付模块依次从左到右排开体现一个横向的业务链路。数据层放在业务层下方主数据库和缓存分别放在对应模块的下方用连线指向对应服务。中间件消息队列放在数据层右侧不与任何一个业务模块绑定表示它被多个模块共用。基础设施层放在底部放日志收集、监控告警两个节点。摆放的时候我把经常产生调用关系的节点尽量就近放置。比如支付模块靠近第三方支付服务的方向因为支付模块要调外部支付接口这样连线短图面也清爽。节点大小不用强求完全一致但同一层的节点保持相似尺寸否则视觉权重会失衡。这一步做下来整张图的结构已经比较完整了。此时我一般会停下来缩小画布看整体检查有没有哪条连线跨了很长的距离。如果发现某条线从最左边拉到最右边说明布局有问题应该考虑调整节点位置或者调整层次结构。4.3 配色连线与最终交付结构稳定之后开始做统一的样式规范。我对这个案例的配色方案是接入层用蓝色业务层用青色数据与中间件用绿色外部系统用灰色基础设施用灰蓝色。异常或高亮路径暂不涉及所以全图只出现四种主色整体风格比较克制。连线方面接入层到业务层用实线表示同步调用业务层到数据层用虚线表示数据读写业务层到消息队列用带箭头的虚线表示异步消息。每一类连线的含义在图右下角加一个小的图例说明。这一步很重要尤其是图要发给不熟悉项目的人看时图例能让理解成本大幅下降。文字规范也同步处理网关、用户模块这类节点名保持在五个字以内主数据库标明是“主库、只读库”用括号补充第三方服务用官方简称。整体字号分三层容器名称 16 号节点名称 14 号注释与图例 10 号。最后导出 PNG 时我把缩放倍数调到 2 倍同时保留了 SVG 源文件。交付时除了提供图片版本还附上了源文件链接和版本号。这样做的好处是下一次架构调整时团队可以直接基于同一个源文件修改而不是重画一遍。5. 常见问题与排查技巧实录5.1 图又乱又挤的排查思路几乎每个画图的人都会遇到“图画到后期越来越乱”的困境。我总结了三个最常见的诱因和对应的排查思路。第一个诱因是节点太多。图里超过 20 个节点一定会显得拥挤。排查方法是回到信息整理阶段问一问哪些节点可以合并。比如多个配置项、多个底层工具完全可以用一个“基础设施”节点概括。把图当作分层地图一层只展示最重要的元素。第二个诱因是连线交叉过多。交叉线是视觉噪音的主要来源。排查方法是检查布局顺序尽量保证同一个方向的连线平行。举例来说所有数据流都从上往下走所有调用流都从下往上走交叉概率就会大幅下降。如果还是交叉尝试交换某一列节点的位置。第三个诱因是多余的修饰元素。很多人喜欢给节点加阴影、渐变、图标、超链接图标这些在精修阶段可以留着但在画图过程中全是干扰。我画图过程中只保留最简单的矩形和文字等结构和连线全部确定之后再做视觉修饰。注意如果你发现某张图怎么调整都还是乱不要硬撑。把图拆成两张一张总览图只展示最高层级的模块一张明细图专门展示其中一个模块的内部结构。拆图不是妥协而是正确的设计方式。5.2 协作与版本管理问题团队协作画图时最常遇到的问题就是版本冲突和源文件混乱。基于画布类的工具即使支持多人编辑也很难处理“两个人同时改同一块区域”的情况。我的建议是把图的协作方式当成代码协作来管理。首先明确一个原则“一张图一个负责人”。这个负责人负责整张图的布局和整体结构其他成员想调整时可以先在评论区或共享文档里提意见最后统一由负责人修改。否则十个人同时拖拽节点最后的成品一定是灾难。其次如果你的团队使用 Git强烈建议把文本生成的图放到代码仓库里统一管理。这样每次改动都有清晰的 diff 记录任何一次变更都能回溯。辛苦维护的图不会因为某个人本地文件丢失而彻底找不回来。另外给文件命名时也要讲究。不要出现“架构图最终版”“架构图最终版2”“架构图最终版修复”这类命名。建议规范命名格式比如“系统名-图类型-版本号”修改时递增版本号。虽然听起来很基础但实际工作中因为命名混乱找不到正确版本的情况我见过太多次了。5.3 导出、展示与复用问题最后整理几个导出和展示环节的高频问题。导出图片模糊是最多人踩的坑。根本原因是画布的固定尺寸太小导出时没有指定高倍率。解决办法是导出时选择缩放倍率 2 倍或 3 倍或者直接导出 SVG 格式。微信公众号、Wiki、PPT 都支持 SVG这种格式能保证任何屏幕下都清晰。图片色差问题也值得提一下。画图时使用的是鲜艳的 RGB 色但导出 PDF 或者打印时颜色会偏暗。如果这张图要用于正式打印或对外交付建议在设计中就选用偏深的配色避免导出后对比度不足。关于复用我强烈建议每个团队沉淀自己的“图例库”。把常用的节点样式、颜色、图标、字体规范整理成一个模板文件。下次任何成员画图时直接基于这个模板创建而不是从零开始设置颜色和布局。这样团队里的所有图都会保持视觉一致性读者看谁的图都不会觉得陌生。我个人的经验是做 diagram-design 解决得最好的往往不是“画图当天的两小时”而是背后这套可复用的方法。工具可以换但分层思维、布局原则、命名规范、协作流程这些沉淀下来之后才是真正长期有用的资产。团队里每个人都能画出像样的图这一点比任何花哨的绘图技巧都重要。