1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次看到 “diagram-design” 这个标题很多人会以为它只是教你怎么画流程图、时序图或者架构图。但真正做过技术方案、写过设计文档、给团队做过架构评审的人都知道画图这件事从来不是“画得好看”这么简单。它背后牵扯的是一整套信息表达系统你要把脑子里模糊的结构变成别人一眼能看懂、能讨论、能落地的东西。这个过程里图只是最终呈现真正的核心是“设计”——也就是你如何组织信息、如何选择表达方式、如何让不同角色的人在同一张图上达成共识。我过去几年在多个项目里反复踩过“图没画好导致沟通成本爆炸”的坑。比如有一次做系统重构方案我花了两天画了一张非常详细的部署架构图结果评审会上大家盯着图看了十分钟问的第一个问题是“这个服务到底是谁调谁”。那一刻我才意识到图的信息密度太高、层次太乱反而让读者失去了方向。后来我重新调整了图的层级把“调用关系”和“部署单元”拆成两张图评审效率立刻提升了一倍。这就是 diagram-design 要解决的核心问题不是让你学会某个画图工具而是让你建立一套“图的设计思维”。这套思维适用于很多场景。如果你是后端开发需要画系统架构图、数据流图、时序图如果你是产品经理需要画业务流程图、状态机图、用户旅程图如果你是技术写作者需要画概念关系图、决策树、对比矩阵。甚至你在做汇报、写周报、整理知识体系时都会用到图。diagram-design 的目标读者不是设计师而是所有需要用图来表达复杂信息的人。它不要求你会用 Figma 或 Sketch也不要求你有美术基础它要求的是你愿意花时间想清楚“我要表达什么”以及“读者需要看到什么”。我自己的经验是一张好的图能顶三千字文档。但一张糟糕的图会让读者产生“还不如看文字”的挫败感。所以这篇文章我会从设计思路、核心细节、实操过程、常见问题四个维度把 diagram-design 这件事拆开来讲。我会尽量用我实际项目里的例子告诉你哪些做法是有效的哪些坑我踩过之后再也不碰了。如果你正在为“怎么把复杂系统画清楚”发愁或者你觉得自己画的图总是差点意思那接下来的内容应该能帮到你。2. 内容整体设计与思路拆解为什么图的设计比画图本身更重要2.1 图的本质是信息压缩不是美术创作很多人对画图有一个误解觉得图就是“把文字变成图形”。但真正做过 diagram-design 的人会告诉你图的本质是信息压缩。你面对的是一个复杂的系统可能有几十个模块、上百个接口、多种数据流向。如果你把这些信息全部平铺在一张图上读者会直接崩溃。所以你需要做的是从大量信息中提取出最关键的几个维度然后用视觉元素把它们组织起来。我通常会把信息分成三类结构信息、行为信息、约束信息。结构信息回答“系统由哪些部分组成”比如模块、服务、数据库、缓存行为信息回答“这些部分之间如何交互”比如调用、消息、事件、数据流约束信息回答“有哪些规则和边界”比如同步/异步、超时、重试、权限。一张图最好只聚焦一类信息最多两类。如果你试图在一张图里同时表达结构、行为和约束那这张图一定会变得难以阅读。举个例子我之前参与过一个订单系统的设计评审。第一版图里有人把服务调用、数据库表结构、消息队列的 topic、定时任务的时间窗口全部画在了一起。结果评审会上大家花了大量时间在争论“这个箭头到底代表 HTTP 调用还是消息投递”。后来我们把它拆成三张图一张部署架构图只画服务与中间件的部署关系一张时序图只画下单流程的调用顺序一张状态机图只画订单状态流转。三张图各司其职评审效率提升了不止三倍。所以 diagram-design 的第一个核心思路就是先分类再压缩最后视觉化。分类决定了你画几张图压缩决定了你保留哪些信息视觉化决定了你用什么样的图形和连线。这个顺序不能乱。很多人一上来就打开画图工具边画边想最后画出来的图往往逻辑混乱、重点不清。2.2 选择图类型不是所有关系都适合用方框和箭头在 diagram-design 里选择正确的图类型是决定成败的关键一步。我见过太多人用流程图去表达状态流转用架构图去表达时序关系结果读者看得一头雾水。下面这张表是我自己总结的常见图类型与适用场景对照你可以直接参考。图类型核心表达适用场景不适用场景架构图系统组成与部署关系服务划分、模块依赖、部署拓扑表达调用顺序、状态变化时序图交互顺序与消息传递接口调用、异步消息、超时重试表达静态结构、数据模型流程图业务逻辑与分支判断审批流、订单流程、算法逻辑表达系统部署、并发关系状态机图状态流转与触发条件订单状态、任务状态、生命周期表达调用链、数据流向数据流图数据加工与存储ETL 流程、数据管道、报表生成表达服务调用、部署结构概念关系图实体与关系领域模型、知识体系、ER 图表达时序、部署、状态这张表看起来简单但实际用起来有很多细节。比如时序图很多人画的时候会把所有分支都画出来导致图非常宽。我的做法是主流程用一条线画清楚异常分支用注释或者单独的图说明。再比如状态机图很多人会把所有状态都画上包括那些几乎不会出现的中间状态。我的建议是只画核心状态和关键流转边缘状态用文字补充。还有一个容易被忽略的点图的类型要和读者的认知模型匹配。如果你给运维团队看架构图他们关心的是部署单元和网络分区如果你给产品团队看流程图他们关心的是业务规则和用户路径。同一套系统给不同角色看的图应该是不一样的。这不是“画多张图”的问题而是“为不同读者设计不同信息层次”的问题。2.3 视觉编码颜色、形状、连线背后的设计逻辑确定了图类型之后下一步就是视觉编码。这一步是 diagram-design 里最容易被低估的部分。很多人觉得颜色只是装饰形状只是习惯连线只是连接。但实际上每一个视觉元素都在传递信息。如果你用错了读者会产生误解。我自己的视觉编码规则是这样的颜色代表类别形状代表类型连线代表关系粗细代表强度。比如在架构图里我用蓝色代表计算服务绿色代表存储橙色代表中间件灰色代表外部依赖。形状上圆角矩形代表服务圆柱体代表数据库菱形代表网关。连线上实线代表同步调用虚线代表异步消息箭头方向代表数据流向。粗细上粗线代表核心链路细线代表辅助链路。这套规则不是固定的你可以根据自己的项目调整。但关键是一旦确定就要在整个文档或整个项目里保持一致。我见过有人在第一张图里用蓝色代表前端在第二张图里用蓝色代表数据库读者看到第三张图的时候已经不知道蓝色到底是什么意思了。这种不一致会严重破坏图的可读性。另外颜色的使用要克制。我一般一张图里最多用四种颜色超过四种就会显得杂乱。如果你需要表达更多类别可以用形状或者标签来区分。还有一点不要依赖颜色来传递关键信息因为有些读者可能是色盲或者打印出来是黑白的。关键信息应该通过形状、标签、位置来传递颜色只是辅助。连线也是一个大坑。很多人画图时喜欢用直线连接所有元素结果线交叉在一起像一团乱麻。我的经验是尽量减少连线交叉必要时使用正交线或者曲线。如果两个元素之间关系复杂可以考虑用编号或者注释来代替直接连线。还有箭头的方向一定要明确不要出现双向箭头却不知道谁主动谁被动的情况。3. 核心细节解析与实操要点从信息梳理到最终成图的完整链路3.1 信息梳理先写文字再画图我见过很多人一上来就打开画图工具拖几个方框连几条线然后开始调整位置和颜色。这种做法效率极低而且很容易漏掉关键信息。我的做法是先用文字把要表达的内容写清楚再考虑怎么画。具体来说我会先写一段“图的大纲”。比如我要画一个订单系统的架构图我会先写系统边界订单服务、支付服务、库存服务、用户服务、消息队列、数据库核心关系订单服务调用支付服务和库存服务支付服务通过消息队列通知订单服务订单服务读写订单数据库关键约束支付服务是同步调用库存服务是异步消息订单数据库是主从架构写完这段文字之后我再把它翻译成图。这样做的好处是文字阶段你可以快速调整逻辑而画图阶段你只需要关注视觉表达。如果你直接画图调整逻辑的成本会高很多因为你要移动方框、重连连线、调整布局。还有一个技巧用纸和笔先画草图。不要一上来就用专业工具。纸笔的好处是速度快、修改方便、没有工具的限制。我经常在纸上画三四版草图确定结构没问题之后再用工具画正式版。这个过程看起来多了一步但实际上节省了大量在工具里反复调整的时间。3.2 布局设计让读者的眼睛有路可走布局是 diagram-design 里最考验经验的部分。一张图的信息再准确如果布局混乱读者也会失去耐心。我自己的布局原则是从左到右从上到下核心在中间边缘在四周。具体来说如果是架构图我会把用户入口放在最左边核心服务放在中间数据存储放在右边外部依赖放在最上面或最下面。如果是时序图我会把参与者放在顶部时间轴从上到下消息从左到右。如果是流程图我会把开始节点放在左上角结束节点放在右下角分支节点放在中间。布局的另一个关键是对齐。很多人画图时不太注意对齐方框大小不一、位置随意导致图看起来很乱。我的做法是先用网格或者参考线把主要元素的位置定好然后再微调。对齐不仅让图更美观更重要的是让读者更容易理解元素之间的关系。如果两个方框没有对齐读者可能会误以为它们不在同一层级。还有一点留白很重要。不要把图填得太满元素之间要有足够的间距。我一般会保证元素之间的水平间距至少是方框宽度的三分之一垂直间距至少是方框高度的二分之一。留白不仅让图更透气也给读者的大脑留出处理信息的时间。3.3 标注与注释让图自己说话一张好的图应该能“自己说话”也就是说读者不需要看额外的文字说明就能理解图的核心内容。但现实中很多图需要配合大量文字才能看懂。这通常是因为标注和注释没做好。我的做法是每个关键元素都要有标签每条关键连线都要有说明。标签要简洁最好控制在五个字以内。比如“订单服务”比“订单管理微服务模块”更好“同步调用”比“通过 HTTP 协议进行同步请求”更好。如果标签太长可以考虑用编号然后在图旁边用文字说明。注释的使用要克制。我见过有人在图上加了几十个注释结果图比文字还难读。我的经验是只注释那些容易产生歧义或者特别重要的地方。比如一个异步消息如果它的重试策略很特殊可以加一个注释说明如果只是普通的异步消息就不需要注释。还有一个技巧用图例。如果图里用了多种颜色、形状、连线最好在角落加一个图例说明每种视觉元素代表什么。图例不需要很大但一定要清晰。我一般会把图例放在图的右下角或者左下角避免遮挡核心内容。3.4 工具选型适合的才是最好的说到画图工具市面上有很多选择。我自己的经验是没有最好的工具只有最适合当前场景的工具。下面这张表是我对常见工具的分类和评价。工具类型代表工具优势劣势适用场景代码生成类PlantUML、Mermaid版本可控、修改方便、适合技术文档样式受限、布局自动化程度低技术文档、代码仓库内的图拖拽类draw.io、Excalidraw自由度高、上手快、样式丰富版本管理困难、协作麻烦方案评审、快速草图专业设计类Figma、Sketch视觉效果最好、组件复用强学习成本高、不适合技术图产品设计、对外展示白板类Miro、Mural协作方便、适合头脑风暴不适合正式文档、导出效果一般远程会议、工作坊我自己的主力工具是 draw.io 和 PlantUML。draw.io 适合画需要精细调整的架构图和流程图PlantUML 适合画需要版本管理的时序图和状态机图。Excalidraw 我一般用来画草图因为它的手绘风格很适合早期讨论。Figma 我只有在需要对外展示或者做产品设计时才会用。选择工具时我会考虑三个因素修改频率、协作需求、输出场景。如果图需要频繁修改我会选代码生成类工具因为改代码比拖方框快。如果图需要多人协作我会选白板类或者拖拽类工具。如果图需要放进正式文档或者对外展示我会选专业设计类工具。提示不管你用什么工具一定要保留源文件。我见过太多人只导出了 PNG结果后来要改的时候发现源文件丢了只能重画。源文件是你最重要的资产。4. 实操过程与核心环节实现一个真实项目的 diagram-design 全记录4.1 项目背景与目标这个项目是我之前参与的一个跨平台系统的重构。系统原本是一个单体应用随着业务增长性能问题和维护成本越来越高。团队决定把它拆成微服务架构。我的任务是为这次重构设计一套图用于内部评审和后续的开发参考。目标很明确让评审团队在半小时内理解新架构的核心变化让开发团队在后续开发中有图可依。评审团队包括技术负责人、产品经理、运维负责人他们的关注点各不相同。技术负责人关心服务划分和调用关系产品经理关心业务影响和上线节奏运维负责人关心部署结构和监控方案。所以我需要设计多张图分别满足不同角色的需求。4.2 第一版信息梳理与草图我先花了一个下午做信息梳理。我把原系统的所有模块列出来然后按照业务领域重新分组。分组的原则是高内聚、低耦合。比如订单相关的功能放在订单服务支付相关的功能放在支付服务库存相关的功能放在库存服务。分组之后我得到了八个核心服务。然后我梳理了服务之间的调用关系。这一步很关键因为调用关系决定了系统的复杂度和性能瓶颈。我用一个简单的表格记录了每个调用的类型同步/异步、协议HTTP/消息、频率高/中/低。这个表格后来成了我画架构图的基础。梳理完信息之后我在纸上画了第一版草图。草图很简单八个方框代表八个服务方框之间用箭头连接箭头旁边标注调用类型。画完之后我发现一个问题服务之间的调用关系太复杂箭头交叉严重读者很难看清核心链路。于是我决定把架构图拆成两张一张“核心链路图”只画订单、支付、库存三个核心服务的调用关系一张“全量服务图”画所有服务的关系但用颜色区分核心和非核心。4.3 第二版正式图的设计与实现第二版我用 draw.io 来画。我先画核心链路图。布局上我把订单服务放在中间支付服务和库存服务放在两边用户服务放在最左边数据库放在最右边。连线上同步调用用实线异步消息用虚线。颜色上核心服务用蓝色数据库用绿色外部依赖用灰色。画完之后我拿给一个同事看。他的反馈是“订单服务和支付服务之间的箭头太细了我差点没注意到。”于是我调整了连线的粗细把核心链路的连线加粗到 2px辅助链路保持 1px。这个调整看起来很小但效果很明显读者一眼就能看出哪些是核心链路。然后我画全量服务图。这张图我用了一个不同的布局策略按照业务领域分组把八个服务分成三组每组用一个浅色背景框起来。组内服务用实线连接组间服务用虚线连接。这样读者可以先看组再看组内关系最后看组间关系信息层次很清晰。时序图我用 PlantUML 来画。因为时序图需要频繁修改用代码生成类工具效率更高。我画了下单流程的时序图包括订单创建、支付调用、库存扣减、消息通知四个阶段。每个阶段我都标注了超时时间和重试策略。这张图后来成了开发团队最常用的参考图。4.4 评审与迭代评审会上我先把核心链路图投出来用了五分钟讲解核心变化。然后投全量服务图讲解服务划分和调用关系。最后投时序图讲解关键流程。整个讲解过程用了二十分钟比原计划少了十分钟。评审团队的反馈是“图很清楚基本没有疑问。”但还是有一些迭代。运维负责人提出全量服务图里没有体现部署结构他需要知道每个服务部署在几个节点上、有没有跨机房。于是我加了一张部署架构图用不同的形状表示节点、容器、数据库实例。产品经理提出时序图里没有标注业务影响他需要知道哪些步骤会影响用户体验。于是我在时序图旁边加了一个注释列说明每个步骤的用户感知。这次迭代让我意识到图的设计不是一次性的而是一个持续迭代的过程。不同角色的反馈会帮你发现信息盲区而这些盲区往往是你自己意识不到的。4.5 最终交付与文档化最终我交付了五张图核心链路图、全量服务图、下单时序图、部署架构图、状态机图。每张图我都保留了源文件并且导出了 PNG 和 SVG 两种格式。PNG 用于文档嵌入SVG 用于放大查看。我还写了一份简短的“图的使用说明”放在文档开头。说明里写了每张图的用途、读者对象、关键图例。这样即使我不在场读者也能快速找到自己需要的图。注意图的命名很重要。我见过有人用“图1”“图2”“图3”来命名结果过了一个月自己都忘了哪张是哪张。我的命名规则是“系统名-图类型-版本号”比如“订单系统-架构图-v2”。这样即使图很多也能快速定位。5. 常见问题与排查技巧实录那些年我踩过的 diagram-design 坑5.1 图太复杂读者看不懂怎么办这是最常见的问题。很多人画图时恨不得把所有信息都塞进去结果图变得极其复杂。我的排查思路是先问自己三个问题。第一这张图的核心信息是什么第二读者最需要看到什么第三哪些信息可以放到文字里如果一张图的核心信息超过三个我就会考虑拆图。比如架构图可以拆成“核心链路图”和“全量服务图”时序图可以拆成“主流程时序图”和“异常流程时序图”。拆图的原则是每张图只回答一个问题。还有一个技巧用层级来组织信息。比如在全量服务图里我可以用不同的颜色深浅来表示服务的层级核心服务用深色支撑服务用中色边缘服务用浅色。这样读者可以先看深色部分再看浅色部分信息处理有先后顺序。5.2 连线交叉严重像一团乱麻连线交叉是画图时的常见问题尤其是在架构图和流程图中。我的解决方法有三个。第一调整元素位置。把关系密切的元素放在一起减少连线长度和交叉。第二使用正交线。正交线比直线更容易跟踪尤其是在复杂图中。第三用编号代替连线。如果两个元素之间关系复杂可以在元素上标编号然后在图旁边用文字说明关系。还有一个经验尽量减少双向箭头。双向箭头会让读者困惑到底是谁主动谁被动如果确实是双向关系我会用两条单向箭头或者用一条线加两个箭头但标注清楚方向。5.3 颜色用得太乱读者分不清颜色是双刃剑。用得好图很清晰用不好图很混乱。我的原则是一张图最多四种颜色每种颜色代表一个明确的类别。如果类别超过四种我会用形状或者标签来区分。还有一个常见问题是颜色对比度不够。有些人喜欢用浅蓝、浅绿、浅灰结果打印出来或者投屏时根本看不清。我的做法是用中等饱和度的颜色确保在黑白打印时也能通过灰度区分。如果实在需要区分可以用纹理或者边框样式来辅助。提示如果你不确定颜色是否合适可以把图转成灰度看看。如果灰度下还能区分那颜色就没问题。5.4 图更新不及时和实际系统不一致这是最致命的问题。图一旦和实际系统不一致就会误导读者甚至导致错误的决策。我的做法是把图纳入版本管理。如果用代码生成类工具图就和代码一起提交如果用拖拽类工具图文件也要提交到代码仓库。另外我会在图的角落标注“最后更新时间”和“对应版本”。这样读者一看就知道这张图是不是最新的。如果系统有重大变更我会在评审会上同步更新图确保图和系统保持一致。5.5 常见问题速查表问题可能原因解决方法图太复杂信息未分类、未压缩拆图、分层、用文字补充连线交叉元素位置不合理、连线方式单一调整布局、用正交线、用编号颜色混乱颜色过多、对比度不足限制颜色数量、用形状辅助图与系统不一致未版本管理、更新不及时纳入版本管理、标注更新时间读者看不懂缺少图例、标注不清加图例、简化标签、加注释打印效果差颜色依赖过重、分辨率低用灰度测试、导出高分辨率5.6 独家避坑技巧最后分享几个我自己的避坑技巧。第一画图前先写文字大纲这个习惯帮我节省了大量时间。第二用纸笔先画草图不要一上来就用工具。第三找同事试读他们的反馈往往能发现你意识不到的问题。第四保留源文件这是你最重要的资产。第五图不是越详细越好有时候一张简单的图比一张复杂的图更有说服力。我在实际项目中的体会是diagram-design 的核心不是工具而是思维。你需要想清楚“我要表达什么”和“读者需要看到什么”然后选择合适的图类型、布局、视觉编码。这个过程需要练习但一旦掌握你的沟通效率会有质的提升。最后再分享一个小技巧如果你不确定一张图好不好把它放一晚上第二天再看。如果第二天你还能一眼看懂那这张图就没问题如果你自己都要看半天那读者肯定更费劲。