1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次看到 diagram-design 这个标题很多人会以为它只是一个画图工具或者某个模板库。但真正做过系统设计、写过技术方案、给团队讲过架构的人会明白图只是最终呈现的载体真正难的是图背后那套“把复杂关系讲清楚”的设计能力。diagram-design 这个项目核心就是围绕“如何设计一张能自解释的图”展开的它既涉及图形语法的选择也涉及信息层级的编排还涉及不同场景下图表类型的取舍。我最初接触这类项目是在给一个跨平台系统做架构评审的时候。当时团队里有人用纯文字写了二十页文档评审会上没人看得下去有人随手画了几张框图结果箭头方向混乱、模块边界模糊反而引发了更多争论。后来我们专门花了两周时间梳理“图的设计规范”从颜色语义、连线规则、分组逻辑到标注方式全部统一。那之后评审效率至少提升了一倍。diagram-design 要解决的正是这个问题让图不再只是“配图”而是成为可独立阅读、可传递复杂逻辑的工程产物。这个项目适合谁如果你是技术方案撰写者、系统架构师、产品经理、技术博主或者任何需要把抽象逻辑可视化的人它都能直接派上用场。它不要求你会复杂的绘图软件也不要求你有美术功底但它要求你理解“信息设计”的基本原理。下面我会从整体设计思路、核心细节、实操过程、常见问题四个维度把 diagram-design 拆开讲透。2. 内容整体设计与思路拆解2.1 为什么 diagram-design 不先讲工具而是先讲语法很多人做图的第一步是打开某个绘图软件然后开始拖拽矩形和箭头。这个顺序其实是反的。diagram-design 的思路是先定义“图形语法”再选择工具。图形语法包含几个核心要素节点类型、连线语义、分组容器、标注规则、颜色体系。这五个要素决定了图能不能被正确理解而工具只决定画得快不快、好不好看。我举个实际例子。在一个数据流图中如果实线箭头表示“同步调用”虚线箭头表示“异步消息”那么读者不需要看文字说明就能区分两种交互。但如果所有箭头都用实线只是颜色不同而颜色又没有图例那这张图就失去了自解释能力。diagram-design 强调的就是这种“语义先于样式”的原则。你先把每种图形元素的含义定死再去画图就有了逻辑骨架。这个思路的优势在于当图变复杂时你不会因为样式混乱而迷失。很多人在画大型系统图时画到后面自己都忘了某条线代表什么这就是因为一开始没有定义语法。diagram-design 要求你在动笔前先写一份“图形约定”哪怕只有五六条也能极大提升图的可读性。2.2 方案选型为什么是“分层分区”而不是“一张大图走天下”diagram-design 的另一个核心设计决策是分层与分区。所谓分层是指把系统按抽象级别拆成多个视图比如上下文层、容器层、组件层、代码层。所谓分区是指在同一个视图内用视觉边界把不同职责的模块隔开。这个决策背后的逻辑是人的短期记忆容量有限一张图里如果同时出现超过十五个节点理解成本就会急剧上升。我试过把整个微服务系统画在一张图上结果节点超过四十个连线交叉得像蜘蛛网。后来改成三层第一层只画外部用户和系统边界第二层画主要服务模块第三层画某个关键服务的内部结构。每张图节点控制在十个以内评审时大家反而能逐层深入讨论。diagram-design 提倡的就是这种“按需展开”的策略而不是追求一张图包罗万象。具体操作上你可以先画一张上下文图只包含三到五个元素用户、系统、外部依赖。然后针对每个核心模块再单独画一张展开图。每张图只回答一个核心问题比如“数据从哪里来”“请求经过哪些环节”“状态如何流转”。这样图与图之间通过编号或颜色关联形成一套图集而不是一张孤图。2.3 颜色与形状的语义分配为什么不能随便用在 diagram-design 里颜色和形状不是装饰而是语义载体。我见过太多图用红色表示“重要”、绿色表示“正常”但红色到底是指错误、警告还是高优先级没有定义。diagram-design 的做法是先确定一套有限的语义类别比如“用户侧”“系统侧”“数据存储”“外部服务”“异步通道”然后为每个类别分配固定的颜色和形状。比如用户侧统一用浅蓝色圆角矩形系统侧用深蓝色直角矩形数据存储用绿色圆柱体外部服务用灰色虚线框。这样读者一眼就能识别元素类型不需要反复看图例。形状的选择也有讲究圆角通常表示“软边界”或“可交互”直角表示“硬边界”或“内部模块”圆柱表示“持久化”菱形表示“决策点”。这些约定一旦建立整张图就形成了一套视觉语言。注意颜色数量不要超过六种否则会变成彩虹图反而增加认知负担。如果类别超过六种考虑用形状或纹理来区分而不是继续加颜色。2.4 连线规则箭头方向、线型和交叉处理连线是图里最容易出错的部分。diagram-design 对连线有三条硬规则第一箭头方向必须与数据流或控制流方向一致不能反向第二不同语义的连线用不同线型实线表示同步调用虚线表示异步消息点线表示依赖关系第三尽量避免交叉如果无法避免用“跳线”或“桥接”符号表示不相交。我踩过的一个坑是在一张部署图里我把“网络连接”和“进程调用”都用实线表示结果读者以为所有连接都是同一种机制。后来改成实线表示进程内调用虚线表示跨网络调用并在图例里注明问题就解决了。另外连线上的标注也很关键。如果一条线上有协议名、端口号或数据格式一定要标出来否则图就丢失了关键信息。3. 核心细节解析与实操要点3.1 节点命名为什么“用户服务”不如“用户认证服务”节点命名看似简单但直接影响图的可读性。diagram-design 建议节点名称采用“限定词核心词”的结构比如“用户认证服务”比“用户服务”更明确“订单写入队列”比“消息队列”更具体。如果节点名称太长可以用缩写但必须在图例或脚注里说明。我通常的做法是先列出所有节点然后逐个问自己“这个名字能不能让一个不了解项目的人猜出它的职责”。如果不能就加限定词。比如“缓存”太泛“会话缓存”更清楚“数据库”太泛“订单主库”更明确。节点名称控制在四到八个汉字之间英文控制在两到三个单词之间太长就换行或缩小字号。3.2 分组容器的画法边界、标题与嵌套分组容器用来表示模块、子系统或部署单元。diagram-design 建议分组容器用浅色背景加虚线边框标题放在左上角字号比节点名称稍大。如果分组有嵌套比如“业务层”里面包含“订单模块”和“支付模块”那么外层容器用更浅的背景内层容器用稍深的背景形成视觉层次。一个常见的错误是分组容器画得太大把不相关的节点也框进去了。我的经验是分组边界应该紧贴其成员节点留出少量内边距即可。如果两个分组之间有共享节点不要强行框入某一组而是把共享节点放在两组之间用连线连接。另外分组标题不要用“其他”“杂项”这种模糊词要么明确归类要么单独列出。3.3 标注与图例让图自己说话diagram-design 强调“图例是图的一部分不是附属品”。图例应该包含颜色语义、形状语义、线型语义、缩写对照。图例的位置通常在图的右下角或左下角不要放在顶部因为顶部容易与标题冲突。如果图例内容较多可以分成两列或三列。标注则用于解释特定节点或连线的细节比如“此服务仅在内网访问”“该队列最大积压十万条”。标注不要直接写在节点内部而是用引线拉到图外或者用脚注编号。我习惯用数字编号然后在图下方统一列出注释这样图面更干净。实测下来带编号注释的图比直接写满文字的图阅读速度要快百分之三十左右。3.4 字体与字号被大多数人忽略的关键细节字体选择上diagram-design 建议使用无衬线字体比如思源黑体、微软雅黑或系统默认的无衬线字体。衬线字体在缩小后容易糊不适合图内文字。字号方面节点名称用十四到十六号分组标题用十六到十八号标注用十二到十四号图例用十二号。如果图要嵌入文档字号不要小于十号否则打印或缩放后会看不清。我见过有人为了塞下更多内容把字号调到八号结果图在投影仪上完全没法看。后来我们定了一条规矩任何图在百分之百缩放下站在两米外能看清节点名称才算合格。这个标准虽然有点苛刻但确实能倒逼你精简节点数量而不是靠缩小字号来硬塞。4. 实操过程与核心环节实现4.1 第一步明确图的类型与目标读者在动手画之前先回答两个问题这张图是给谁看的它要回答什么问题如果是给高层看的上下文图节点不超过五个重点展示系统边界和外部依赖如果是给开发看的组件图节点可以到十五个左右重点展示模块划分和调用关系如果是给运维看的部署图重点展示节点、网络区域和端口。我通常会在图的开头写一句话“本图展示某某系统的某某视图目标读者是某某角色。”这句话不一定要放在图里但一定要先想清楚。如果一张图既想给高层看又想给开发看结果往往是两边都不满意。diagram-design 提倡“一图一目标”宁可多画几张也不要在一张图里塞进所有信息。4.2 第二步列出节点与连线清单不要直接开始画先用文本列出所有节点和连线。节点清单包括名称、类型、所属分组。连线清单包括起点、终点、语义、线型。这个步骤看起来笨但能帮你提前发现逻辑漏洞。比如你可能会发现某个节点没有入边或出边或者某个连线形成了环路但没有说明。我一般用表格来整理节点表三列节点名、类型、分组连线表四列起点、终点、语义、线型。整理完之后再对照检查有没有孤立节点有没有语义不明的连线有没有跨分组的连线没有标注这个清单直接决定了后续画图的效率。实测下来先列清单再画图比直接画图再修改至少节省一半时间。4.3 第三步选择工具并设置画布工具选择上diagram-design 不绑定特定软件。轻量级场景可以用 draw.io、Excalidraw 或系统自带的绘图工具复杂场景可以用 Figma、Sketch 或专业的图表工具。关键不是工具本身而是工具是否支持你定义的图形语法。比如你需要虚线箭头、圆角矩形、圆柱体、分组容器这些基本图形大多数工具都支持。画布设置上建议使用十六比九或四比三的横向画布分辨率至少一千九百二十乘一千零八十。背景用白色或浅灰色不要用深色背景因为深色背景在打印和投影时容易失真。网格线可以打开但不要显示在最终导出图里。对齐辅助线一定要开否则节点歪歪扭扭看起来很不专业。4.4 第四步按分层顺序绘制绘制顺序很重要。diagram-design 建议从外到内、从上到下。先画外部用户和外部系统再画系统边界然后画主要模块最后画内部细节。每画完一层停下来检查一次这一层的节点是否完整连线是否清晰标注是否必要如果发现某条连线跨了太多层考虑把它拆到另一张图里。我自己的习惯是先用灰色画出所有节点和分组确定布局然后给节点上色区分类型接着画连线调整线型和箭头最后加标注和图例。这个顺序的好处是布局阶段不受颜色和线型干扰可以专注于空间关系。如果先上色再调布局改起来会很麻烦。4.5 第五步导出与嵌入文档导出格式上如果图要嵌入在线文档用 SVG 或 PNGSVG 更清晰但某些平台不支持PNG 兼容性更好但放大后会模糊。如果图要打印用 PDF 或高分辨率 PNG分辨率至少三百 DPI。如果图要放在演示文稿里用 PNG 并确保背景透明或与幻灯片背景一致。嵌入文档时图的下方要加图注格式为“图一某某系统上下文图”。图注不要写在图里面而是作为文档的一部分。如果图有编号注释注释列表放在图注下方。我见过有人把图注写在图的上方读者先看到图注再看到图体验很别扭。另外图与正文之间要留出适当间距不要紧贴文字。5. 常见问题与排查技巧实录5.1 图太乱怎么办先删节点再删连线图乱的根本原因通常是节点太多或连线太多。diagram-design 的排查顺序是先删节点再删连线。删节点的标准是这个节点是否直接回答了图的核心问题如果否移到另一张图。删连线的标准是这条连线是否传递了必要信息如果否直接删掉。我处理过一张包含三十多个节点的部署图乱得没法看。后来我把“监控代理”“日志收集器”这些辅助节点全部移到另一张图只保留核心服务节点图立刻清爽了。再后来我把“服务A调用服务B”和“服务B调用服务C”合并成“服务A经服务B调用服务C”连线又少了一半。记住图不是越全越好而是越清晰越好。5.2 连线交叉严重怎么办调整布局或使用跳线连线交叉是布局问题不是绘图问题。解决方法有三种第一调整节点位置把关联紧密的节点放在一起第二使用分层布局把不同层的节点放在不同水平线上第三使用跳线符号表示两条线不相交。diagram-design 建议优先用前两种跳线只作为最后手段。我通常会把节点按数据流方向从左到右排列或者按调用层级从上到下排列。如果某个节点与多个节点有连线把它放在中心位置。如果两个分组之间连线太多考虑把其中一个分组的节点移到另一个分组旁边。实测下来调整布局能解决百分之八十的交叉问题剩下百分之二十再用跳线。5.3 颜色不够用怎么办用形状和纹理补充颜色超过六种就会混乱但语义类别可能超过六种。这时候用形状和纹理来补充。比如圆形表示用户矩形表示服务圆柱表示数据库菱形表示决策六边形表示外部系统。纹理方面斜线填充表示异步点状填充表示可选网格填充表示 deprecated。我做过一张图有八种节点类型只用了四种颜色其余靠形状区分。读者反馈说比之前用八种颜色的版本更容易理解。所以不要迷信颜色形状和纹理同样是有效的视觉编码手段。关键是保持一致性同一种形状在所有图里代表同一种语义。5.4 图例太复杂怎么办拆成主图例和局部图例如果图例超过十条考虑拆成主图例和局部图例。主图例放在图的一角包含全局通用的语义局部图例放在特定分组旁边只解释该分组内的特殊符号。这样读者不需要一次性记住所有图例而是按需查阅。我通常把颜色和形状放在主图例把线型和标注放在局部图例。如果某张图只用到三种线型就把线型图例放在图的下方而不是塞进主图例。另外图例的排版要整齐颜色块、形状、文字要对齐不要东一个西一个。5.5 常见问题速查表问题现象可能原因排查方法解决技巧图太乱节点或连线过多数节点和连线数量删节点、合并连线、拆图连线交叉严重布局不合理检查节点位置调整布局、分层、跳线颜色混乱颜色语义未定义检查图例限制颜色数量、用形状补充图例太复杂图例条目过多数图例条目拆主图例和局部图例字号太小节点太多或画布太小检查缩放后可读性精简节点、放大画布箭头方向混乱连线语义未定义检查连线清单定义线型语义、统一方向分组边界模糊分组容器太大或太小检查分组与节点关系紧贴成员节点、留内边距标注太多标注未精简检查标注必要性用编号注释、移到图外6. 工具选型与效率提升技巧6.1 轻量级场景draw.io 与 Excalidraw 的取舍draw.io 适合需要精确对齐和丰富图形库的场景它支持自定义形状库、图层管理和导出多种格式。Excalidraw 适合快速草图和白板讨论它的手绘风格能降低“正式感”让评审更聚焦逻辑而不是样式。我通常用 Excalidraw 做早期讨论用 draw.io 做最终交付。选择标准很简单如果图需要反复修改且要求精确用 draw.io如果图只是用来快速沟通用 Excalidraw。不要用演示文稿软件画图因为对齐和连线功能太弱后期修改成本极高。6.2 复杂场景Figma 与专业图表工具的适用边界Figma 适合需要多人协作和设计系统支持的场景它的组件功能可以复用节点样式自动布局可以快速调整间距。专业图表工具比如某些建模软件适合需要生成代码或文档的场景但学习曲线较陡。diagram-design 的建议是先用轻量工具验证图的逻辑确认无误后再用复杂工具做最终美化。我见过有人直接用建模软件画图结果逻辑还没理清就陷入工具细节浪费了大量时间。正确的顺序是纸上草图、轻量工具、专业工具。每一步只解决一个问题不要跳步。6.3 效率提升模板与快捷键建立自己的模板库能极大提升效率。模板包括常用节点样式、常用分组容器、常用图例、常用画布尺寸。我通常会把模板保存为文件每次新建图时直接复制。快捷键方面掌握对齐、分布、组合、锁定这几个操作能节省大量鼠标操作时间。另外给节点和连线命名时使用一致的命名规则比如“服务-用户认证”“队列-订单写入”这样在工具的对象列表里能快速找到。不要用“矩形一”“箭头二”这种默认名称后期修改时根本找不到。7. 从单张图到图集diagram-design 的扩展思路7.1 图集编号与交叉引用当图超过一张时需要建立编号和交叉引用。diagram-design 建议用“图一”“图二”编号并在图注中注明“本图是图一的展开”。如果图与图之间有依赖关系比如图二展示了图一中某个模块的内部结构那么在图一的该模块上标注“见图二”。我通常会在图集的首页放一张总览图然后用编号列出所有子图。每张子图的开头写一句话说明它与总览图的关系。这样读者可以按顺序阅读也可以跳读。交叉引用不要用“如上图所示”这种模糊说法而是明确写“见图三”。7.2 版本管理与变更记录图也会迭代所以需要版本管理。diagram-design 建议在图的右下角标注版本号和日期比如“v1.2 2025-01”。如果图有重大变更在文档的变更记录里说明改了什么、为什么改。不要把旧版本直接覆盖而是保留历史版本以便追溯。我自己的做法是每张图保存为独立文件文件名包含版本号比如“系统上下文图-v1.2”。如果图嵌入文档文档的版本号与图的版本号保持一致。变更记录放在文档末尾格式为“版本号、日期、变更内容、变更人”。变更人用代号不用真实姓名。7.3 团队协作中的图规范落地团队协作时图规范需要落地。diagram-design 建议先写一份“图规范文档”包含图形语法、颜色语义、线型语义、命名规则、导出格式。然后在新项目启动时花半小时给团队讲一遍。不要指望大家自觉遵守而是要在评审时检查图是否符合规范。我通常会在评审清单里加一条“图是否符合图规范”如果不符合打回重画。一开始大家会觉得麻烦但两周后就会形成习惯。规范不是限制创造力而是降低沟通成本。当所有人都用同一套视觉语言时评审效率会显著提升。8. 我个人在实际操作中的体会画图这件事工具和技巧都是次要的核心是“你想让读者看到什么”。我见过太多人把图当成文档的装饰而不是思考的工具。实际上画图的过程就是梳理逻辑的过程。当你把节点和连线列出来的时候很多逻辑漏洞会自己暴露出来。我自己的习惯是先用手绘草图画在纸上或白板上不追求好看只追求逻辑完整。然后拍照用轻量工具重画一遍调整布局和样式。最后导出嵌入文档。这个流程看起来慢但实际上比直接打开软件画要快因为手绘阶段没有工具干扰思维更集中。另外不要追求一张图解决所有问题。图集比单张图更有效因为每张图只回答一个问题读者可以按需阅读。我现在的项目文档里通常有五到八张图每张图都有明确的编号和标题读者可以根据需要跳转。这比一张大图塞满所有信息体验要好得多。最后分享一个小技巧如果你不确定一张图是否清晰把它发给一个不了解项目的同事让他用一句话说出图在讲什么。如果他说不出来或者说的和你想的不一样那这张图就需要改。这个测试比任何规范都有效。
