1. 从“diagram-design”这个标题说起它到底在解决什么问题第一次看到“diagram-design”这个标题很多人会以为它只是一个画图工具的代称或者某个设计模板库的名字。但真正做过系统设计、技术方案评审、产品流程梳理的人一眼就能看出来这个词背后指向的是一整套关于“如何把复杂逻辑用图讲清楚”的方法论和工具链。它不是一个单点工具而是一个从需求拆解、结构建模、视觉编码到最终交付的完整工作流。我在过去几年里参与过不少跨团队的技术方案评审和产品流程重构项目最深的感受就是图画得好不好直接决定了沟通成本的高低。同样一套微服务架构有人画出来三分钟能讲明白有人画出来半小时还在解释箭头方向。这中间的差距不是审美问题而是设计方法问题。diagram-design 要解决的核心痛点就在这儿——让图成为真正的沟通工具而不是装饰品。这篇文章适合几类人看一是经常需要画架构图、流程图、时序图的技术同学二是需要梳理业务流程、做产品原型的产品经理三是需要把复杂逻辑可视化呈现给非技术受众的咨询顾问或项目负责人。不管你用的是 draw.io、Excalidraw、Figma 还是代码化的 Mermaid、PlantUML底层的设计思路是相通的。我会从整体设计思路、核心细节、实操过程、常见问题四个维度把 diagram-design 这件事拆透。2. 整体设计思路为什么大多数人的图“不好看又不好懂”2.1 图的本质是信息压缩不是美术创作很多人画图有个误区觉得图要“好看”。好看当然重要但好看是结果不是目标。图的本质是信息压缩——把一段三百字的文字描述压缩成一张十秒钟能看懂的图。压缩率越高信息传递效率越高。你画一张架构图如果读者需要对照旁边的文字说明才能理解那这张图的压缩率就是零甚至负数。我在某次方案评审中见过一张“微服务调用关系图”画了二十多个方框箭头密密麻麻像蜘蛛网每个方框里写着服务名但没有标注调用协议、没有区分同步异步、没有标出核心链路。结果评审会上大家花了二十分钟在问“这个箭头是什么意思”“这个服务是干嘛的”。这就是典型的信息压缩失败——图只是把文字里的名词搬到了方框里没有做任何结构化处理。diagram-design 的第一个原则就是先想清楚这张图要回答什么问题再决定画什么。是要回答“系统有哪些模块”还是要回答“请求怎么流转”还是要回答“数据怎么存储”不同的问题对应不同的图类型和不同的信息层级。一张图只回答一个问题这是铁律。2.2 图类型选择别用流程图去干架构图的活我见过太多人用流程图去画系统架构用架构图去画业务流程结果就是怎么看怎么别扭。每种图类型都有它擅长的信息结构选错了类型后面怎么调都救不回来。图类型擅长回答的问题核心元素典型场景架构图系统由哪些部分组成如何分层方框、分层、边界技术方案评审、系统概览流程图步骤如何流转决策点在哪节点、箭头、判断菱形业务流程、算法逻辑时序图谁在什么时候给谁发了什么消息生命线、消息箭头、激活条接口交互、协议设计状态图对象有哪些状态如何迁移状态圆角框、迁移箭头订单状态、任务生命周期ER图数据实体之间是什么关系实体、属性、关系菱形数据库设计、领域建模思维导图一个主题如何层层展开中心节点、分支需求拆解、知识梳理选图类型的判断标准很简单你的核心信息是“结构”还是“顺序”还是“交互”。结构用架构图顺序用流程图交互用时序图。如果一张图里既要表达结构又要表达顺序那就拆成两张图别硬塞在一起。2.3 视觉编码颜色、形状、粗细都是有语义的diagram-design 里最容易被忽视但又最影响可读性的是视觉编码。什么叫视觉编码就是用颜色、形状、线条粗细、填充样式来承载信息。比如颜色蓝色代表前端、绿色代表后端、橙色代表第三方依赖、红色代表风险点。颜色一旦赋予语义就要全图统一不能这张图蓝色是前端下张图蓝色变成数据库。形状矩形代表服务、圆角矩形代表组件、圆柱代表数据库、菱形代表判断。形状的语义也要统一。线条实线代表同步调用、虚线代表异步消息、粗线代表核心链路、细线代表辅助链路。分组用背景色块或虚线框把同一层级的元素圈在一起形成视觉分组。我自己的习惯是在画图之前先定一个视觉规范小卡片写清楚这张图里每种颜色、每种形状、每种线条代表什么。画完之后对照检查一遍确保没有“无语义的视觉元素”。什么叫无语义就是你把那个颜色去掉、把那个形状换掉图的信息量不变。那这个视觉元素就是多余的要么赋予它语义要么删掉。2.4 布局原则从左到右、从上到下、核心居中布局是图的骨架。布局乱了再好的视觉编码也白搭。diagram-design 的布局原则可以总结为三条第一主流程从左到右或从上到下。人的阅读习惯是单向的主流程方向要符合阅读习惯。如果是请求流转就从左到右如果是层级关系就从上到下。第二核心元素居中或靠近中心。最重要的服务、最关键的节点放在视觉中心位置。边缘位置放辅助元素、外部依赖、次要分支。第三减少交叉线。交叉线是阅读障碍能避免就避免。如果实在避免不了用“跳线”符号或者调整布局来减少交叉。我见过一张图交叉线多达三十多处读者根本追不下去。提示布局阶段不要追求一步到位。先用纸笔或白板画出大致布局确认信息层级和流向没问题再进工具细化。直接在工具里拖拽很容易陷入“局部好看但整体混乱”的陷阱。3. 核心细节解析与实操要点从需求到成图的完整拆解3.1 需求拆解先写“图的大纲”再动手很多人画图是打开工具就开始拖方框这是效率最低的做法。我的习惯是画图之前先写一份图的大纲用纯文本把这张图要表达的信息列出来。大纲包含四个部分图的目标这张图要回答什么问题给谁看核心元素清单有哪些节点、角色、系统、数据实体关系清单元素之间是什么关系调用、依赖、包含、流转层级与分组元素如何分层哪些属于同一组这份大纲不需要很正式用 bullet point 就行。但有了这份大纲你在工具里拖拽的时候就有明确的“填充目标”不会画着画着就跑偏。我实测下来写大纲花五分钟能省掉后面二十分钟的返工。举个例子假设你要画一个“用户下单”的流程图。大纲可能是这样的目标说明用户从浏览商品到完成支付的完整步骤给产品和技术团队看核心元素用户、商品列表、购物车、订单确认页、支付网关、订单服务、库存服务关系用户浏览→加购→确认订单→发起支付→支付回调→更新订单→扣减库存分组前端交互浏览、加购、确认、后端服务订单、库存、外部依赖支付网关有了这个大纲你进工具之后就是“填空”而不是“创作”。创作阶段应该在大纲里完成工具阶段只负责视觉呈现。3.2 工具选型没有最好的工具只有最合适的场景diagram-design 的工具选型核心考量三个维度协作需求、版本管理需求、输出格式需求。工具类型代表工具适合场景不适合场景拖拽式白板某白板工具、某设计工具快速草图、协作讨论复杂架构、精确布局代码化图表Mermaid、PlantUML版本管理、文档嵌入高度定制视觉、非技术受众专业绘图某绘图工具、某图表工具正式交付、复杂布局快速迭代、多人协作设计工具某设计平台高保真视觉、品牌规范技术图表、逻辑密集型我自己的组合是讨论阶段用白板工具文档阶段用代码化图表交付阶段用专业绘图工具。讨论阶段追求速度白板工具最合适文档阶段追求可维护性代码化图表能进版本管理交付阶段追求视觉质量专业工具能精细控制。注意不要在一个项目里混用太多工具。工具切换的成本很高而且风格不统一会让读者困惑。选定一套工具链团队内统一使用。3.3 视觉规范建立你自己的“图表设计系统”如果你经常画图建议建立一套自己的图表设计系统。这套系统包含色板定义 5-7 种语义颜色比如主色、辅色、强调色、警告色、中性色。每种颜色有明确的语义。字体规范标题字号、正文字号、注释字号。通常标题 16-18px正文 12-14px注释 10-11px。形状库定义常用形状及其语义。矩形、圆角矩形、圆柱、菱形、圆形、六边形。线条规范实线、虚线、点线、粗细、箭头样式。间距规范元素之间的最小间距、分组框的内边距、画布边距。这套系统不需要很复杂一页文档就能写完。但有了它你每次画图就不用重新做视觉决策直接套用就行。而且团队内统一使用这套系统出来的图风格一致读者看起来也舒服。我自己的色板是这样的深蓝核心服务、浅蓝辅助服务、绿色数据存储、橙色外部依赖、灰色基础设施、红色风险或重点。这套色板用了三年基本覆盖了所有技术图场景。3.4 信息层级一张图最多三层超过就拆信息层级是图的“深度”。一张图如果层级太多读者会迷失。我的经验是一张图最多三层信息层级。比如架构图第一层是接入层第二层是服务层第三层是数据层。每层内部再分小组但整体层级不超过三层。如果信息确实需要四层甚至五层那就拆成多张图。第一张图展示整体三层结构第二张图深入某个层的内部细节。这叫渐进式披露——先给读者全局再给细节。不要试图在一张图里塞下所有信息那是文档干的事不是图干的事。提示判断一张图是否层级过多有个简单方法——把图缩小到 50% 看如果还能看清主结构说明层级合理如果缩小后变成一团模糊说明信息太密需要拆分。4. 实操过程与核心环节实现从零画一张架构图的完整记录4.1 第一步明确目标与受众5分钟假设我要画一张“某电商系统订单模块”的架构图受众是技术评审委员会。目标是什么回答“订单模块由哪些服务组成它们之间如何交互依赖哪些外部系统”。受众是技术专家所以可以接受一定的技术细节但不需要代码级细节。这一步的输出是一句话这张图要展示订单模块的服务组成、调用关系和外部依赖给技术评审用。这句话决定了后面所有决策。4.2 第二步列出元素与关系10分钟基于目标列出核心元素接入层API 网关服务层订单服务、支付服务、库存服务、通知服务数据层订单库、支付库、库存库外部依赖支付网关、消息队列关系清单API 网关调用订单服务订单服务调用支付服务、库存服务、通知服务支付服务调用支付网关订单服务、支付服务、库存服务分别读写各自的数据库订单服务、支付服务、库存服务通过消息队列异步通信这一步的输出是一份纯文本清单不需要任何格式。4.3 第三步选择布局与视觉编码10分钟布局选择从上到下三层——接入层、服务层、数据层。外部依赖放在右侧用橙色标识。消息队列放在底部用灰色标识。视觉编码深蓝色矩形核心服务订单服务浅蓝色矩形辅助服务支付、库存、通知绿色圆柱数据库橙色圆角矩形外部依赖灰色圆角矩形基础设施实线箭头同步调用虚线箭头异步消息这一步的输出是一份视觉规范小卡片画图时对照使用。4.4 第四步工具实操与参数配置30分钟我选择用代码化图表工具来画因为这张图需要进文档、需要版本管理。以下是一个简化的配置示例# 伪代码示意展示结构定义思路 layers: - name: 接入层 elements: - id: gateway label: API网关 type: service color: deep-blue - name: 服务层 elements: - id: order-service label: 订单服务 type: service color: deep-blue - id: payment-service label: 支付服务 type: service color: light-blue - id: inventory-service label: 库存服务 type: service color: light-blue - id: notify-service label: 通知服务 type: service color: light-blue - name: 数据层 elements: - id: order-db label: 订单库 type: database color: green - id: payment-db label: 支付库 type: database color: green - id: inventory-db label: 库存库 type: database color: green external: - id: payment-gateway label: 支付网关 type: external color: orange - id: message-queue label: 消息队列 type: infra color: gray relations: - from: gateway to: order-service type: sync - from: order-service to: payment-service type: sync - from: order-service to: inventory-service type: sync - from: order-service to: notify-service type: async - from: payment-service to: payment-gateway type: sync - from: order-service to: order-db type: sync - from: payment-service to: payment-db type: sync - from: inventory-service to: inventory-db type: sync实际工具中你需要根据具体语法调整。关键是先定义元素和关系再调整布局和样式。不要一边画一边调样式那样效率很低。4.5 第五步布局微调与交叉线消除15分钟代码化工具通常会自动布局但自动布局往往不完美。你需要手动调整把核心服务订单服务放在视觉中心把外部依赖放在右侧边缘把消息队列放在底部调整箭头走向减少交叉如果交叉线实在太多考虑调整元素顺序。比如把支付服务和库存服务的位置互换可能就能减少好几条交叉线。4.6 第六步视觉检查与导出10分钟导出之前做一次视觉检查颜色语义是否统一有没有无语义的颜色形状语义是否统一有没有混用线条样式是否一致实线虚线是否区分清楚文字是否清晰缩小到 50% 是否还能看清主要标签是否有拼写错误标签是否准确检查通过后导出为 SVG 或 PNG。SVG 适合文档嵌入PNG 适合即时通讯分享。如果工具支持同时导出 PDF 版本方便打印。提示导出时注意画布边距。边距太小会显得拥挤边距太大又浪费空间。通常上下左右各留 20-30px 边距比较合适。5. 常见问题与排查技巧实录那些年我踩过的坑5.1 图太乱怎么办先删元素再调布局图乱的根本原因通常是元素太多。很多人舍不得删觉得每个元素都重要。但图不是文档图的价值在于选择性呈现。一张图如果超过 15 个核心元素基本就乱了。排查步骤列出所有元素按重要性排序只保留前 10-12 个最重要的元素其余元素要么合并要么放到第二张图重新布局减少交叉线我自己的经验是一张图超过 12 个元素可读性就急剧下降。与其硬塞不如拆图。5.2 箭头方向混乱统一流向规则箭头方向混乱是常见问题。有人从左到右画有人从右到左画有人从上到下画结果读者不知道按什么顺序读。解决方法全图统一流向规则。要么全部从左到右要么全部从上到下。如果有反向箭头比如回调用不同颜色或虚线标识并在图例中说明。5.3 颜色太多太花限制在 5-7 种颜色是双刃剑。用得好信息层级清晰用不好眼花缭乱。我的原则是一张图的颜色不超过 7 种其中 2-3 种是主色2-3 种是辅色1-2 种是强调色。如果发现颜色不够用说明信息层级没理清。先理层级再分配颜色。5.4 文字太多标签要短注释要精图上的文字要短。方框里的标签最好控制在 6-8 个字以内。超过 10 个字读者阅读速度就下降。如果需要更多说明用注释或图例不要塞进方框。我见过有人在方框里写了两行文字每行 15 个字结果方框巨大布局全乱。正确做法是方框里只写核心名称详细说明放在图下方的注释区。5.5 常见问题速查表问题现象可能原因解决方法图太乱元素太多、层级太深删减元素、拆图、限制三层箭头混乱流向不统一统一流向规则反向箭头特殊标识颜色太花颜色语义不明确限制 5-7 种颜色赋予明确语义文字太多标签过长标签控制在 6-8 字详细说明放注释交叉线多布局不合理调整元素顺序核心居中边缘放辅助缩小后看不清字号太小、间距太密增大字号增加间距减少元素风格不统一没有视觉规范建立图表设计系统统一色板形状线条提示每次画完图把图发给一个不了解背景的同事看问他“这张图在说什么”。如果他能在一分钟内说出大意说明图合格如果他说“看不懂”说明还有优化空间。6. 进阶技巧让图从“能看”变成“好用”6.1 图例与注释别让读者猜图例是图的“说明书”。颜色、形状、线条的含义都要在图例中说明。图例放在图的右下角或左下角不要放在顶部顶部通常留给标题。注释用于补充关键信息。比如某个服务有特殊限制某个调用有超时设置都可以用注释标出。注释要精炼一句话说清楚。6.2 版本管理图也要有变更记录图是活的会随着系统演进而变化。建议给图加版本号和变更记录。比如“v1.22024-06-15新增通知服务”。这样读者知道这张图是什么时候的避免拿旧图讨论新问题。代码化图表工具天然支持版本管理因为图就是代码可以进 Git。拖拽式工具通常没有版本管理需要手动保存不同版本。6.3 多图联动用一致的视觉语言如果一个项目有多张图确保它们使用一致的视觉语言。同样的颜色代表同样的含义同样的形状代表同样的元素类型。这样读者在看不同图的时候不需要重新学习视觉规则。我自己的做法是项目开始时先定一份视觉规范所有图都按这份规范来画。规范文档放在项目 Wiki 里团队成员都可以参考。6.4 从图到文档图的嵌入与引用图最终要嵌入文档或演示文稿。嵌入时注意分辨率要足够SVG 最佳PNG 至少 2x图要有编号和标题方便引用图下方可以加一段文字说明补充图里没表达的信息如果图会更新文档里用链接引用不要直接嵌入避免版本不一致7. 我个人的实操体会画了这么多年图最大的体会是图的质量不取决于工具取决于画图之前的思考。工具只是执行思考才是核心。一张好图是在脑子里已经画好了工具只是把它呈现出来。另一个体会是图是给人看的不是给机器看的。不要追求“完整”要追求“清晰”。完整是文档的事清晰是图的事。一张图能回答一个问题就是好图。最后分享一个小技巧如果你不确定一张图好不好把它打印出来贴在墙上退后三步看。如果三秒内能看出主结构说明图合格如果三秒内看不出说明还需要优化。这个方法的原理是退后三步相当于模拟了读者快速浏览的场景能暴露信息层级的问题。