很多项目不是死在代码上，而是死在沟通上。你带着一肚子方案去和团队对齐，讲着讲着对方眼神开始涣散；你憋出一篇万字需求文档，开发看完还是来问“所以这里到底谁调谁”。这种事我遇到太多次了。后来我养成了一个习惯：但凡要讲清一个系统、一条流程、一组关系，先动手画图。diagram-design 这个项目名听起来像是某个库或工具，但在我这里它是一整套方法——把脑子里模糊的架构、流程、依赖，变成一张张信息准确、层次清晰、别人一眼能看懂的图。这篇东西想聊的，就是这套方法的完整拆解，从设计思路到实操细节到避坑经验，希望对所有需要画架构图、流程图、ER图、路线图的开发者和技术文档作者有点用。

图这件事，最容易踩的坑是“把图画完”和“把图画好”混为一谈。画完只需要工具熟练，画好需要信息设计。而我见过的大部分团队，流程其实反了：一上来就打开画布拖控件，边想边画，结果是图改了八版，每次都是局部挪来挪去，最后没人愿意维护，图就成了文档里的一具化石。diagram-design 想解决的问题，就是让画图从“随缘发挥”变成“按套路生产”。

1. 先想清楚：diagram-design 的核心是信息架构，不是视觉装饰

1.1 为什么画图之前必须先做“信息分层”

很多人画图丑，不是配色的问题，是脑子里的信息没分层。一张系统架构图，从底层的存储、中间的服务、顶层的接入层，再到旁边的监控和运维，如果这些信息全部摊在同一个视觉层级上，图一定乱。反过来，只要信息分层清楚了，哪怕用最朴素的黑白框，图也是能看的。

我画图前会先做一个动作，完全脱离画布，拿纯文本把信息过一遍。比如要画一个订单系统的架构图，我不会先去拖“数据库”“微服务”这些图标，而是先把这句话写下来：用户从客户端发起请求，经过网关，进入订单服务，订单服务调用库存服务和支付服务，最后数据落到数据库。写完之后再问自己：这张图要给人看什么？是看调用链路，还是看服务部署关系，还是看数据流向？这个问题的答案决定了信息的取舍和分层。

信息分层一般可以拆成三层。第一层是骨架层，也就是图里不能被删掉的主干节点和核心连线，通常是系统的几个主模块或流程的几个主阶段；第二层是支撑层，围绕骨架展开的依赖、配置、副作用，比如缓存、消息队列、定时任务；第三层是注解层，说明性的文字、端口号、协议类型、注意事项。画布上动笔之前，先在心里把这层判断做完，后面画起来完全不用卡壳。

1.2 常用图表类型与场景选择对照

diagram-design 的另一个基本功，是知道什么场景用什么图。我发现很多图之所以没人看，是因为图类型选错了。你非要在一张架构图里画出调用时序，信息密度必然爆炸；你在汇报PPT里放一张精细到每个字段的ER图，听众只会觉得你在炫技，根本记不住。

我给自己定了一张选择表，现在基本不用想，瞄一眼就知道该画哪种：

这张表的意义不在于分类学，而在于逼你在画图之前先问一句“我到底要表达哪种关系”。有一次我帮一个同事复盘线上问题，他一开始想画一张流程图，把服务调用的先后、数据返回的路径、缓存失效的分支全塞进去，结果画了一下午没画完。我让他换成了时序图，十五分钟完事，问题链路一眼就清楚了。工具熟练度没变，只是图类型选对了，效率是数量级的差别。

2. 一套可直接复用的图表设计规范

2.1 布局与网格：让信息在“看不见的格线”上站队

图要好看，最廉价的手段就是对齐。不对齐的图给人的感觉就是“哪里不对劲”，但你说不出来；一旦对齐了，哪怕内容一般，观感立刻上一个档次。这里说的对齐不是目测差不多，而是让元素真正落在同一个网格系统里。

现在主流绘图工具基本都有网格吸附功能，draw.io（开源绘图工具）默认开着，Figma（在线协作设计工具）也可以开启网格显示。我的经验是，网格间距统一设成 20px 或 24px，所有节点的位置、大小、间距都控制在网格的整数倍上。这样出来的图，节点之间、分层之间天然就有一种秩序感。

具体操作上，我一般分三步。第一步，先排大框架，把图里最核心的几个区块按水平或垂直方向摆开，区块之间留出固定的间隔，比如上下层之间留 40px，左右模块之间留 60px。第二步，局部对齐，每个区块内部的节点要么左对齐，要么居中对齐，不要一会儿左一会儿中。第三步，全图统一，再一次选中所有节点，清理掉那些明显偏离网格的孤儿元素。这三步做完，图的基本骨架就立住了。

注意一个细节：连线也要对齐。很多图节点对齐了，但连线歪七扭八，什么直角、曲线混着来。我的规范是，同一张图里只用一种连线风格：架构图用直角线，看起来利落；流程图用曲线或直线都可以，但绝对不能混用。连线要对齐，最直接的做法是让连线尽量走水平和垂直方向，斜线只有真有必要时才用。

2.2 配色方案：三色原则与语义色

配色是最容易让人上头的地方。我见过有人图里用了十二种颜色，每个方块一个色，最后图的主题是什么完全看不清。色彩在图表里的作用，是用来区分层级的，不是用来装饰的，所以颜色越克制越好。

我自己长期用的规范叫“三色原则”：一张图里只有三种“角色”的颜色。第一种是主色，用来画核心模块，通常是一种饱和度偏高的蓝色或深灰；第二种是辅助色，用来画支撑模块，比如缓存、网关、消息队列，通常是主色的邻近色；第三种是语义色，用来突出异常、告警、无状态节点这一类有特殊含义的东西，比如红色表示风险、黄色表示脆弱点。剩下的背景、边框、线条，全部用不同深浅的中性灰。

另外有一个小技巧是配色之前先想清楚深浅关系：核心模块用深色或高饱和，次要模块用浅色或低饱和，背景永远最浅。这样读者扫一眼，视觉重心自然落在图的重点上。我经常看到有些人反着来，背景用深蓝，文本框用亮黄，图一出来，人眼根本不知道该看哪儿。

2.3 连线、箭头与标注：细节里的信息差

连线和箭头是图里信息密度最高的“低频元素”，但恰恰最容易被忽略。很多图线是都画了，方向也对了，可就是看起来乱，问题几乎都出在这几个地方。

箭头方向。架构图里，请求方向一般从调用方指向被调用方，数据流方向从生产方指向消费方。这两者如果混在一张图里，就需要用不同样式的线区分，比如实线表示 HTTP 调用，虚线表示异步消息。绝对不要在同一条连线里一会儿实一会儿虚。

标注与图例。图里的文字越短越好，尤其是连线上的文字，超过六个字就考虑拆出去放到图例里。图例是一个图的“编解码手册”，必须放在显眼位置，尤其是公共文档里的图，阅读者可能不知道你的“虚线圈”代表什么。

版本与命名。这一条我最想强调：越是正式的图，越要在图的角落写上版本号、日期、作者。否则一张架构图在文档里传了半年，没人知道它是不是过期了。这个细节看似简单，实际工作中真的没几个人做到。

3. 从零到一：一次完整的 diagram-design 实操

3.1 需求拆解：把文字变成四类图形元素

掌握了规范，接下来是完整的实操流。我用一个实际例子走一遍：某跨平台系统里要加一个数据同步模块，我需要给设计文档配一张模块架构图。

第一步不是打开画图工具，而是把需求文字拆成四类元素：节点（系统里的实体）、连线（节点之间的关系）、分组（模块或层级边界）、注解（说明文字）。对这套需求来说，拆出来是这样：

• 节点：客户端、同步服务、任务队列、数据库、文件存储
• 连线：客户端到同步服务（调用），同步服务到任务队列（写入任务），同步服务到文件存储（读写），任务队列到同步服务（回调）
• 分组：接入层（客户端）、业务层（同步服务、任务队列）、存储层（数据库、文件存储）
• 注解：协议类型、任务触发条件

这一步的价值在于，它把不可见的空间问题转化成了可编排的图元列表，等你打开画布的时候，你其实已经知道要放多少个框、哪些框要先连，不需要再去读需求文档。

我强烈建议把这一步的成果写成纯文本，哪怕只是临时画一下。它既是画图的蓝图，也是图的“可追溯源头”。后面图被改乱了、被改丢了，拿这份文本三分钟就能重新画出来。

3.2 工具选型与画布组织

工欲善其事，必先利其器。diagram-design 这块可选的工具不少，我的建议是别贪多，按场景定。长期维护的技术文档图，我推荐用 draw.io，免费、跨平台、支持 Git 版本管理，存成 XML 文件直接进代码仓库，和文档代码一起做评审。设计感要求高、要放进 PPT 和对外文档的图，用 Figma 更合适，画布自由度高，样式细腻。如果团队就是做软件开发的，那 PlantUML 和 Graphviz 这类文本即图的路线也值得考虑，好处是图随代码走，坏处是复杂图的可读性和可控性会差一些。

决定用哪个工具之后，画布组织同样不能含糊。我的习惯是：画布尺寸先预设好，不要默认无限大。比如目标是放进 A4 文档的一页，就把画布设置成 16:9 或者 A4 比例；如果是一张完整的架构图，直接在画布上划分好横向几块、纵向几层，每一块对应一组图元，用浅色底块先把分布定出来。

3.3 成图的七个关键动作

这个环节我称之为“七步成图法”，是我自己反复试出来的顺序，每一步都有不可替代的作用。

动作一：按网格摆骨架。把分组框拉好，按顺序摆出横向三层。这一步不做任何美化，就是确认结构对不对。

动作二：填入节点。把上一份清单里的节点各自拖进对应分组，节点的宽度尽量统一，比如核心服务用 140px，辅助组件用 120px，避免高矮胖瘦参差不齐。

动作三：统一高度与间距。全选节点后执行对齐与等距分布。draw.io 里“对齐-水平居中”“对齐-垂直居中”“排列-水平等距”这个三个命令是最高频的，务必用熟。

动作四：拉连线。从调用方拉到被调用方，方向别反。连接点选“相对连接点”而不是“绝对连接点”，这样后续挪动节点时连线会自动延伸，不会断。

动作五：标注。在连线中点附近加一行小字，说明协议或含义；在分组框顶部写清楚这个分组的名称；在图角落加“系统X-模块架构-v1.2-日期”信息。

动作六：着色。按三色原则上一遍颜色，从核心模块开始，然后是支撑模块，最后是分组底色。

动作七：全局走查。缩小后整体看一遍：有没有未标注的连线？有没有颜色冲突出格？有没有漏掉的节点？这一步相当于写完代码后的自测。

这七个动作看起来简单，但顺序很关键。先着色再拉线的话，颜色一多，连接时容易看错；先拉线再统一间距，连线很可能被拉歪。我按这个顺序执行之后，一张中等复杂的架构图大约 30 分钟搞定，质量还稳定。

4. 常见问题与维护实战

4.1 信息过载：做减法的三个原则

画图时最容易犯的错是贪多。尤其做技术的同学，总觉得这张图里不把所有细节画出来就少了点什么，结果图出来，除了自己没人看得懂。

对付信息过载，我执行“三个删”原则。删装饰：单纯为了好看的渐变、阴影、图标，一律先删掉，图的目的是传递信息，不是拍海报。删重复：同一个信息出现在图的多个角落，比如数据库节点既画了图标又在旁边写了“MySQL”，删掉其中一半。删次要：和这张图的核心表达关系不大的节点，哪怕它真实存在，先放到另一张图或者注释里。

这三个原则的本质，是让图回到它最初的目的——降低读者的认知负担。细枝末节移走后，核心链路变得更清晰，反而更容易被理解。

4.2 导出与兼容：SVG、PNG、PDF 怎么选

图画好之后的导出环节，也要讲策略。我把导出场景分成三类，对应三种格式：

第一类是要进文档继续编辑的，导出 SVG。SVG 是矢量格式，无限放大不糊，而且方便别人在文档里二次加工。大部分现代文档平台都支持 SVG 直接插入，我很推荐。

第二类是要在聊天窗口和 IM 工具里直接发图的，导出 PNG。注意是 2x 或 3x 分辨率的 PNG，不然在群里被压缩一次就会发虚。

第三类是要打印或作为正式附件归档的，导出 PDF。这个格式排版稳定，字体不会丢，打印出来最靠谱。

这里有一个容易翻车的细节：字体。很多人画图时用了特殊字体，结果导出到别人电脑上打开，字变成了方框。解决办法有两个：要么导出前把文字转成曲线（draw.io 里是“转换为路径”），要么统一使用 Arial、思源黑体这类机器自带的基础字体，以字形优先级高的那个为准。

4.3 图的“活”与“死”：可维护性的关键

最后聊聊图的长期维护。这是 diagram-design 里最不值钱、最没人讲、但实际最致命的环节。一张图如果画完就没人管，三个月后系统改了七八个版本，它还挂在那当摆设，那这张图不仅没价值，还有副作用——新人看它以为系统长这样，排查问题方向直接带偏。

把图变成“活图”有两个办法。

第一个办法：图随代码走。如果你用文本类绘图方案，把图源文件放进项目的 docs 目录，和发布版本在同一份提交里。任何人改了系统，顺手能把图源改了，形成习惯后图就永远不过期。

第二个办法：图有唯一真源。很多人画图，一会儿改在本地，一会儿存在云端协同盘，一会儿又发到群里，最后版本打架。我的习惯是，任何一张正式图，只在同一个仓库或同一个共享路径下维护，其他地方的图一律视为拷贝，不做长期使用。

说白了，画图难，养图更难。diagram-design 这套东西，我越用越觉得，真正要管理的不是图本身，而是图背后那些信息的版本和组织方式。

我个人在实际项目里最大的体会，是不要把图表设计当成某个工具的附属技能，它本质上是一种思维习惯：每次动手画图前，多花几分钟把结构想清楚、把信息拆干净、把图例定明白，后面所有实操都能顺理成章。这个习惯养成了，你再看那些画得乱糟糟的图，一眼就能说出问题在哪，这比多会一个快捷键有用得多。