1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次看到“diagram-design”这个标题很多人会以为它只是教你怎么画流程图、怎么把方框和箭头摆得好看一点。但真正做过技术方案、写过设计文档、给团队讲过架构的人都知道图这件事远没有这么简单。一张图背后其实是一整套信息表达系统谁来看这张图、他需要多快抓住重点、哪些细节必须保留、哪些细节必须砍掉、这张图未来会不会被反复修改、能不能直接嵌进文档里、换一个人接手还能不能继续维护。这些问题如果不在画图之前想清楚最后得到的往往就是一张“看起来很努力、但没人愿意看第二眼”的图。diagram-design 这个项目核心就是把这套“画图之前要想清楚的事”变成可复用的设计方法。它不是某个具体绘图工具的教程也不是单纯的美学指南而是一套围绕“图的结构、语义、视觉层级、维护成本”展开的实践框架。说得再直白一点它要解决的是为什么同样一个系统有人画出来三分钟就能讲明白有人画出来三页纸还是让人一头雾水。适合谁来参考我觉得三类人最需要一是经常写技术方案、做架构评审的工程师二是需要把复杂流程讲给非技术同事听的产品或运营三是任何需要长期维护一套图文档的人。哪怕你之前只用过最基础的绘图工具只要理解这套思路也能把图的质量拉高一个档次。我自己的经历是早些年做项目时图都是“顺手画”的觉得内容对了就行。后来发现图一旦多起来问题就暴露了同一个系统在不同文档里有三种画法箭头方向不一致颜色含义不统一新人进来先要花半天猜图例。那时候我才意识到diagram-design 不是锦上添花而是降低协作成本的基础设施。下面我就按实际做项目的思路把这套东西拆开讲清楚。2. 整体设计思路为什么先定规则再动手画2.1 图的本质是信息压缩不是装饰很多人画图时第一反应是打开工具拖几个框连几条线然后开始调颜色和阴影。这个顺序其实是反的。diagram-design 的第一个原则就是图是信息的压缩包不是视觉的装饰品。你压缩得好别人解压就快你压缩得乱七八糟别人就得自己重新整理一遍。我通常会把一张图要承载的信息分成三层。第一层是结构信息也就是系统里有哪些主要模块、它们之间是什么关系。第二层是流向信息数据、控制流、依赖关系往哪个方向走。第三层是约束信息哪些是必须遵守的边界哪些是可选路径。这三层如果混在一起图就会变得又乱又难读。比如把“数据库”和“缓存”画成同样大小的框读者就不知道哪个是核心把“同步调用”和“异步消息”用同一种线型读者就会误判系统行为。所以我在动手之前会先问自己三个问题这张图给谁看他需要做决策还是只需要了解概况这张图未来会不会被修改这三个问题的答案直接决定了图的粒度。给管理层看的图模块可以粗到“业务层、服务层、数据层”给开发看的图可能要把关键接口和重试策略都标出来。这不是“看人下菜碟”而是信息压缩比的选择。2.2 先定视觉语法再填内容diagram-design 里最值得借鉴的一点是把“视觉语法”前置。什么叫视觉语法就是颜色、形状、线型、字号、留白各自代表什么含义先定死再往里面填内容。这样做的好处是当你画到第十张图时不需要重新思考“这个框该用什么颜色”而是直接按规则执行。我一般会定一套最小规则集比如矩形代表服务或模块圆角矩形代表外部系统圆柱代表存储菱形代表判断或网关。线型上实线代表同步调用虚线代表异步消息点线代表可选依赖。颜色上主链路用一种颜色辅助链路用灰色异常路径用另一种颜色。字号上模块名最大接口名次之备注最小。这套规则不需要多复杂但必须一致。注意规则一旦定下来就不要因为某一张图“看起来不好看”而随意打破。视觉语法的一致性比单张图的美观更重要。你今天为了好看改一次明天别人就会跟着改最后整套图就失去了可比性。2.3 为什么不用“万能模板”套所有场景市面上有很多现成的图模板流程图、时序图、架构图、状态图看起来拿来就能用。但 diagram-design 的思路恰恰相反不要用万能模板套所有场景而是根据信息类型选择最合适的表达形式。流程强调顺序和分支时序强调参与者和时间线架构强调层次和边界状态强调迁移条件。如果你把状态迁移硬画成流程图读者就得自己脑补“当前状态是什么”如果你把架构图硬画成时序图读者就会迷失在时间线里。我踩过的一个坑是早期为了省事所有图都用同一种风格画结果评审时有人问“这个箭头是数据流还是控制流”我一时答不上来。后来我强制自己每张图只回答一个核心问题。流程图就回答“下一步做什么”架构图就回答“谁依赖谁”时序图就回答“谁在什么时候调用谁”。一张图只回答一个问题信息密度反而更高。3. 核心细节解析从需求到成图的完整拆解3.1 需求澄清先写一句话再画第一笔在打开任何绘图工具之前我会先用一句话写下这张图要表达的核心结论。比如“用户请求经过网关后先查缓存未命中再查数据库最后异步写回缓存”。这句话写不出来说明我还没想清楚画出来的图也一定是散的。这句话写出来了图的骨架基本就有了网关、缓存、数据库、异步写回四个节点三条主链路。这一步看起来简单但实际做的时候很容易跳过。我见过很多图画得很精致但你看完不知道它想说什么。问题就出在“先画后想”。diagram-design 强调的“结论先行”其实就是强迫你把信息压缩到一句话再展开成图。这句话也是后续检查图是否完整的标准如果图里少了某个关键节点或者多了一条无关链路对照这句话就能发现。3.2 节点设计每个框都要有存在的理由节点是图的基本单元。一个常见的误区是把系统里所有组件都画上去觉得“画全了才专业”。但图不是清单图是筛选。每个节点都应该回答“它为什么必须出现在这张图里”。如果某个节点删掉之后核心结论依然成立那它就不应该出现在主图里最多放到附录或细节图里。我在设计节点时会按“核心节点、支撑节点、背景节点”来分级。核心节点是结论直接涉及的必须突出支撑节点是帮助理解核心节点的可以弱化背景节点是提供上下文的通常用灰色或虚线表示。比如画一个请求链路网关、缓存、数据库是核心节点日志服务和监控服务是支撑节点外部认证系统是背景节点。这样读者一眼就能看出重点在哪里。另外节点命名也很关键。我习惯用“名词角色”的方式比如“订单服务”“用户数据库”“消息队列”而不是只写“服务A”“数据库1”。后者虽然省事但读者需要额外记忆映射关系增加了认知负担。如果名字太长可以用缩写但第一次出现时要给全称。3.3 连线与箭头方向、类型、标签一个都不能少连线是图里最容易出错的地方。很多人画线只关注“连上了没有”不关注“怎么连的”。但连线本身携带大量信息方向代表流向线型代表同步或异步粗细代表流量大小或重要性标签代表具体动作或数据。如果这些信息缺失读者就会自行猜测而猜测往往是不准确的。我一般会遵循几个规则。第一箭头方向必须明确不能出现双向箭头除非确实是双向依赖。第二同步调用用实线异步消息用虚线回调或事件用点线。第三关键连线上要加标签比如“HTTP”“gRPC”“MQ”“写回”。第四尽量避免交叉线如果实在避不开用跳线或颜色区分。第五连线的起点和终点要落在节点的边缘不要落在节点内部否则看起来像“穿模”。提示如果你发现一张图里连线超过二十条而且交叉严重那说明这张图的信息量已经超载了。正确的做法不是继续调布局而是拆成两张图一张讲主链路一张讲异常分支。3.4 布局与留白让读者的眼睛有路可走布局这件事很多人觉得是“审美问题”其实它是“阅读路径问题”。一张好的图读者的眼睛应该能沿着一条自然的路径移动不需要来回跳跃。常见的布局方式有从左到右、从上到下、中心辐射、分层堆叠。选择哪种取决于你的核心结论是什么。如果核心结论是“请求依次经过多个阶段”那就从左到右布局符合阅读习惯。如果核心结论是“多个模块围绕一个中心服务”那就中心辐射布局突出中心节点。如果核心结论是“系统分为多层每层有不同职责”那就从上到下分层布局层次感最强。留白同样重要。节点之间、层级之间、图与边界之间都要留出足够的空间。太挤的图会让读者感到压抑也会让连线变得难以追踪。我通常会把节点间距控制在节点宽度的三分之一到二分之一之间层级间距更大一些。留白不是浪费空间而是给信息呼吸的余地。3.5 颜色与样式少即是多一致即是专业颜色是最容易被滥用的视觉元素。很多人觉得颜色越多越好看结果图变成了调色盘读者反而不知道每种颜色代表什么。diagram-design 的建议是颜色数量控制在三到五种并且每种颜色都要有明确含义。比如蓝色代表核心服务绿色代表数据存储橙色代表外部依赖灰色代表辅助组件红色代表异常或警告。样式上我建议统一圆角半径、统一线宽、统一字号。不要一个框圆角大、一个框圆角小不要一条线粗、一条线细除非粗细本身有含义。统一性带来的专业感远比花哨的样式更有效。另外阴影和渐变尽量少用它们会分散注意力而且在打印或黑白显示时可能完全失效。4. 实操过程从零开始完成一套可维护的图文档4.1 工具选型先看协作方式再看绘图能力工具选型这件事我的经验是先看协作方式再看绘图能力。如果团队所有人都在同一个文档平台里写文档那就选能嵌入该平台的绘图工具如果图需要频繁修改并且多人协作那就选支持版本管理和评论的工具如果图只是个人整理思路用那轻量级工具就足够了。我一般会把工具分成三类。第一类是代码化绘图工具用文本描述生成图优点是版本管理方便、修改成本低、适合长期维护缺点是有学习成本复杂布局需要调。第二类是拖拽式绘图工具上手快、自由度高适合一次性或低频修改的图缺点是多人协作时容易产生冲突版本管理弱。第三类是文档内嵌绘图直接在文档里画优点是上下文紧密、阅读体验好缺点是复杂图难以表达。我的建议是核心架构图和长期维护的图尽量用代码化工具临时讨论和一次性展示的图用拖拽式工具文档内的简单示意图用内嵌工具。不要试图用一种工具解决所有问题。4.2 从草图到成图我的五步工作流我实际画一张图的流程通常是这样的。第一步用纸笔或白板画草图只画节点和连线不关注样式。这一步的目的是把结构想清楚快速试错。第二步把草图转成文字描述也就是前面说的“一句话结论”加上节点和连线清单。第三步在绘图工具里搭建骨架先放节点再连线最后加标签。第四步调整布局和样式统一视觉语法。第五步找人试读让对方说出这张图的核心结论如果他说不出来或者理解偏了就回去改。这五步里第一步和第五步最容易被忽略但恰恰是最重要的。草图阶段快速试错可以避免在工具里反复调整试读阶段验证效果可以避免“自嗨式画图”。我见过太多人画完图直接发出去结果别人看不懂又得重新讲一遍反而更费时间。4.3 参数与规则的具体设定以一套架构图为例假设我要画一套“请求处理链路”的架构图我会先定参数。节点方面核心服务用蓝色圆角矩形存储用绿色圆柱外部依赖用橙色矩形辅助组件用灰色矩形。连线方面同步调用用蓝色实线异步消息用绿色虚线异常路径用红色点线。字号方面模块名用 14 号加粗接口名用 12 号常规备注用 10 号灰色。布局上我采用从左到右的主链路网关在最左存储在最右中间是服务层。辅助组件放在主链路下方用灰色表示。外部依赖放在主链路上方用橙色表示。这样读者的视线自然从左到右移动遇到辅助信息时向下看遇到外部依赖时向上看形成清晰的阅读路径。这套参数不是固定的可以根据项目调整。但关键是一旦定下来整套图都要遵守。我会把这套规则写成一个简短的“图例说明”放在图文档的开头方便新人快速理解。4.4 版本管理与变更记录让图也能被追溯图也是文档也需要版本管理。我习惯在每张图的角落标注版本号和修改日期比如“v1.2 2025-03-10”。如果图有重大变更我会在文档里加一个简短的变更记录说明改了什么、为什么改。这样做的好处是当别人看到旧图时能快速判断它是否过时当需要回溯决策时能知道当时的图是什么样子。对于代码化绘图工具版本管理天然由代码仓库承担每次提交都有记录。对于拖拽式工具我建议导出为图片或 PDF 后按版本号命名存档不要只保留最新版。我踩过的坑是有一次评审时有人问“上个月那版图里这个模块还在怎么现在没了”我翻遍聊天记录才找到旧图非常被动。从那以后我强制自己每次修改都存档。5. 常见问题与排查技巧实录5.1 图太乱怎么办先删节点再减连线图太乱是最常见的问题。很多人第一反应是调整布局把节点挪来挪去结果越调越乱。我的经验是先删节点再减连线。问自己哪些节点删掉之后核心结论依然成立哪些连线可以合并或省略通常删掉三成节点、减掉两成连线之后图就会清爽很多。如果删完之后还是乱那就拆图。一张图只讲一个核心结论把次要信息放到另一张图里。不要试图在一张图里讲完整个系统那不是图那是海报。5.2 别人看不懂怎么办做一次“盲测”别人看不懂往往是因为你默认他知道某些背景信息。解决办法是做一次“盲测”找一个不了解这个项目的同事让他看这张图然后说出他理解的核心结论。如果他说不出来或者理解偏了那就说明图里有信息缺失或歧义。常见的缺失包括没有图例、没有方向说明、没有关键标签、节点命名太抽象。常见的歧义包括同一种线型代表多种含义、颜色没有统一规则、箭头方向不明确。根据盲测反馈逐条修正通常两三轮之后图就会清晰很多。5.3 图维护成本太高怎么办代码化与模块化图维护成本高通常是因为图是“画”出来的而不是“生成”出来的。每次修改都要手动调整费时费力还容易出错。解决办法是代码化和模块化。代码化就是用文本描述图修改文本就能更新图。模块化就是把图拆成可复用的片段比如“存储层”“网关层”“服务层”每个片段单独维护组合成完整图。我现在的做法是核心架构图用代码化工具维护公共组件做成可复用模块变更时只改模块所有引用该模块的图自动更新。这样维护成本大幅降低一致性也有保障。5.4 常见问题速查表问题现象可能原因排查思路解决建议图太乱读者找不到重点节点过多、连线交叉严重数节点和连线数量检查是否有冗余删节点、减连线必要时拆图读者理解偏了缺少图例、标签或方向说明做盲测记录读者误解点补充图例、标签统一视觉语法同一种样式含义不一致没有统一视觉规则检查所有图的颜色、线型、字号定规则集写图例说明强制遵守修改一张图影响多张图图之间没有模块化检查是否有重复片段提取公共模块代码化维护图过时了没人知道没有版本号和变更记录检查图角落是否有版本信息加版本号、日期和变更记录打印或黑白显示效果差依赖颜色区分信息转灰度预览增加形状和线型区分减少颜色依赖5.5 几个我踩过的坑和独家技巧第一个坑是“过度设计”。早期我为了让图看起来专业加了很多阴影、渐变、图标结果读者反而被这些装饰分散了注意力。后来我全部去掉只保留最基础的形状和颜色图反而更受欢迎。第二个坑是“命名不一致”。同一个模块在不同图里叫不同名字读者需要反复确认是不是同一个东西。后来我建了一个术语表所有图都从术语表里取名字。第三个坑是“忽略黑白显示”。有一次评审时投影仪效果不好颜色区分完全失效图变得无法阅读。从那以后我强制自己每张图都转灰度检查一遍确保不依赖颜色也能读懂。独家技巧方面我推荐两个。一是“三秒法则”一张图如果三秒内看不出核心结论就需要改。二是“电梯测试”如果你不能在电梯里用一句话说清这张图说明图本身就没想清楚。这两个技巧听起来简单但非常有效。6. 图文档的长期维护与团队协作6.1 建立团队级视觉规范从个人习惯到集体共识个人画图可以随心所欲但团队协作必须有一致的视觉规范。我建议每个团队都建一份简短的“图文档规范”内容包括常用节点形状及含义、线型及含义、颜色及含义、字号规则、命名规则、版本管理方式。这份规范不需要很长一两页就够但必须全员遵守。制定规范时不要追求一步到位可以先从最常用的三五种形状和线型开始后续根据实际需要补充。规范定好后放在团队文档的显眼位置新人入职时作为必读材料。每次评审图时如果发现不符合规范的地方当场指出并修正慢慢就形成习惯了。6.2 图与文档的联动让图成为文档的一部分图不应该孤立存在它应该和文档正文联动。我的做法是每张图都有一个唯一的编号和标题正文里通过编号引用图比如“如图 3-2 所示”。图下方附简短的说明解释这张图的核心结论和关键细节。如果图有更新正文里的引用不需要改只需要更新图本身和版本号。对于代码化绘图工具图可以直接嵌入文档生成流程文档更新时图自动更新。对于拖拽式工具我建议把图导出为统一格式按编号存档并在文档里嵌入最新版。无论哪种方式关键是让图和文档保持同步避免“图是旧的、文档是新的”这种尴尬情况。6.3 评审与反馈让图在讨论中进化图的价值在于沟通所以评审和反馈是必不可少的。我习惯在方案评审时先让图“说话”把图投出来让参会者先看一分钟然后问他们“这张图想表达什么”。如果他们说的和我想表达的一致说明图合格如果不一致就先改图再讨论方案。评审时收集到的反馈我会分类处理。如果是视觉问题比如颜色太刺眼、字号太小直接改如果是结构问题比如缺少某个关键节点、连线方向不对需要重新思考如果是理解问题比如读者误解了某个模块的职责说明命名或标签需要优化。每次评审后更新图并在变更记录里注明原因这样图就会越来越清晰。6.4 新人上手如何快速理解一套图文档新人面对一套图文档时最容易犯的错是从第一张图开始逐张看。我的建议是先看“图例说明”和“整体架构图”建立全局认知然后看“核心链路图”理解主要流程最后看“细节图”和“异常分支图”补充边界情况。看的时候对照文档正文遇到不懂的节点或连线先查术语表再问同事。作为图文档的维护者你也可以主动为新人在图文档开头加一个“阅读指南”说明推荐阅读顺序和每张图的核心结论。这样新人上手会快很多也能减少重复解释的时间。7. 一些个人体会和后续可以扩展的方向这套 diagram-design 的思路我用了几年下来最大的感受是画图这件事功夫在画之外。你把信息想清楚了图自然就清晰你没想清楚再怎么调样式也没用。所以我现在画图的时间可能只有三成花在工具上七成花在思考和草图上。这个比例看起来不划算但实际效果很好返工少、沟通快、维护省心。后续如果继续扩展我觉得有两个方向值得尝试。一是把图文档和自动化检查结合起来比如用脚本检查图里是否有未定义的节点、是否有孤立节点、是否符合视觉规范。二是把图文档和知识库结合起来让图成为知识图谱的一部分点击节点可以跳转到对应的详细文档。这两个方向都需要一些工具支持但思路是通的让图不只是图而是信息系统的入口。最后分享一个小技巧如果你觉得一张图怎么改都不满意不妨先放一放第二天再看。很多时候问题不在图上而在你还没想清楚。睡一觉起来可能五分钟就改好了。这个技巧我用了很多次屡试不爽。