从一团乱麻到一眼看懂聊聊diagram-design这件事先从我最近一次评审会说起。会上要过一套新系统的技术方案PPT翻到架构图那一页我盯着屏幕看了快两分钟愣是没看出来数据到底从哪进来、中间过了几个环节、最后又落到哪个存储。图里密密麻麻摆了四十多个框连线像蛛网一样交叉箭头方向比迷宫还绕。那一刻我脑子里就一句话这不是图这是事故。那场会之后我花了大概一个周末把团队里过去一年产出的所有架构图、流程图、时序图翻出来复盘了一遍又结合这些年自己画图、审图、帮人改图的踩坑经历整理出了一套围绕diagram-design的完整方法论。这篇博文就是那次整理的产物适合所有需要画图的人来说——不管是程序员画架构图、产品经理画流程图、运维画拓扑图还是技术文档作者画各种示意图。我会把图设计背后真正值钱的东西拆开讲清楚从整体思路、工具选型、实操步骤到排坑经验争取让你看完就能用、用了就能见效。简单说diagram-design不是会拖几个框就完事而是一项让复杂信息变得可读、可信、可维护的工程能力。下面直接进正题。1. 先想清楚一张好图到底是怎么设计出来的1.1 图的本质是沟通不是装饰很多人画图有一个根深蒂固的误解觉得图就是文档的配图把文字变成方框和箭头就算完成任务。我见过太多这样的配图式架构图系统有十个模块就画十个矩形模块之间有没有调用关系也不管反正先框出来再说。这种图放在方案里除了占掉半页纸之外唯一的作用就是让评审专家多看几眼然后问出更尖锐的问题。真正值钱的diagram-design核心是沟通。你要通过这张图让一个完全不了解背景的人在三到五分钟内搞清楚三件事系统里有哪几类角色或模块、它们之间什么关系、关键的数据或流程是怎么流转的。为什么是这三件事因为这就是系统架构这个概念的通俗定义。你画的每一根连线、每一个箭头、每一个标注都应该在回答这三件事中的至少一件。如果某个元素跟这三件事没关系它就是噪音就应该被删掉或者弱化。这里有个很实用的检查方法画完图之后找一个没参与过项目的人给他五分钟看图然后让他复述这张图讲了什么。如果他说的跟你脑子里的方案基本一致说明你这张图的沟通效率是达标的。如果他复述得支离破碎、抓不住重点那不怪他理解能力差是你这张图设计得不够好。1.2 图的驱动力永远在读者和场景上我在做diagram-design时动笔之前一定会先问自己三个问题这三个问题决定了图的一切走向第一个问题这张图的读者是谁是研发团队的同事还是业务方还是外部的合作伙伴研发同事关注模块边界、接口协议、数据流向业务方关注功能链路、角色权限、结果展示合作伙伴关注对外能力、对接方式、安全边界。同一套系统针对不同读者图的画法可以完全不一样。第二个问题这张图用在什么场景是方案评审、代码讲解、故障复盘还是产品说明文档评审场景的图要突出方案取舍和风险点讲解场景的图要按代码的组织逻辑来组织复盘场景的图要把时间线和故障点标得醒目文档场景的图则要追求自解释最好不依赖正文也能看懂。第三个问题这张图想让人记住的一件事是什么任何一张图都应该有一个核心信息。比如这套系统是分层解耦的、这个流程最关键的是审核环节、这两个服务之间是同步调用关系。明确了核心信息之后布局、配色、层级都会围绕它展开这样读者一眼扫过去最先注意到的必然是你最想让他知道的东西。这三个问题想清楚之前我不建议任何人打开绘图工具。工具只是把想法呈现出来的手段想法没定型之前就开画大概率画完草稿发现方向完全错了白白浪费时间。1.3 从需求到图设先写出文字版再落成图形这可能是我最想安利给所有人的一个习惯在打开画图工具之前先花几分钟写一段图设文档。图设文档不需要很复杂就是一段结构化的文字描述。比如画一张下单流程图我会先在文本里写清楚角色有用户、前端应用、订单服务、库存服务、支付服务流程从用户创建订单开始经过库存预占、支付请求、支付回调、库存扣减、订单状态更新最后返回下单结果异常分支包括库存不足、支付超时、重复回调。就这么简单一段话它把图画里该有哪些东西、按什么顺序流转都定义清楚了。为什么这一步这么重要因为它是成本最低的纠错环节。改一行文字的代价几乎为零而改一张已经排好版、调好色的图的代价可能是一上午。我见过太多人直接对着画布开画画到一半发现流程漏了一条分支或者模块之间关系理不顺只能推倒重来这个过程极其耗人心力。文字版确认无误之后再落成图形就会顺畅很多。你只需要做两件事第一把文字里的角色变成容器或分组第二把文字里的动作和流程变成节点和连线。这时候你的注意力可以完全集中在排版好不好看、连线清不清晰这些图形层面的问题上而不是还要分心去想去哪补充逻辑。磨刀不误砍柴工这个道理在diagram-design里体现得特别明显。2. 方案选型Text-Based还是Drag-and-Drop这是个关键分岔路2.1 代码化绘图和拖拽绘图的真实差异做图设计第一个绕不开的选择就是工具路线。现在市面上主流的图设计工具大致分两派一派是代码化绘图代表有Mermaid、PlantUML、Graphviz、Python的diagrams库、D2语言等另一派是拖拽式绘图代表有draw.io现在叫diagrams.net、Excalidraw、Figma、ProcessOn、boardmix等。两派各有拥趸但其实它们解决的问题根本不是一个维度的。代码化绘图的核心优势有三个一是可版本化图跟代码一起进Git仓库每次改动都有diff记录评审代码的时候顺手就审了图二是可复用一段模板改改参数就能生成新图适合批量产出三是一致性高只要维护好公共样式所有图自动统一风格不需要靠每个画图的人自觉。缺点也很明显排版自动化程度有限调整位置、优化间距很多时候要靠手写坐标学了成成本不低另外复杂布局很难精细控制。拖拽式绘图则相反上手几乎没有门槛所见即所得布局完全可控想要什么效果鼠标拖一下就出来了。但缺点是版本管理基本靠手动导出图片多人协作时容易产生最终版v8_really_final.drawio这种文件团队里一旦多几张这样的图维护成本直接失控。我的建议是不要非此即彼而要按场景混用。逻辑性强、需要长期维护、跟着代码走的图比如核心业务流程图、系统架构图用代码化方案一次性使用、探索性强、需要精细调样式布局的图比如汇报草图、头脑风暴脑图、对外宣传示意图用拖拽方案。两者不是替代关系而是互补关系。2.2 我自己的工具组合与日常流程下面这套组合是我用了很长时间、实测下来比较顺手的方案供你参考。对于技术方案类的架构图和数据流图我用Python的diagrams库画。它最大的优点是可以用代码描述云原生架构里的各种组件服务、数据库、消息队列、负载均衡等都有现成图标输出是Graphviz渲染的矢量图清晰度够高也能进Git做版本管理。画一张微服务架构图从写代码到导出PNG正常情况下不超过十五分钟。对于业务流程、时序图、状态图这类跟代码逻辑强相关的图我主要用Mermaid的文本语法。它内嵌在Markdown里写文档的时候顺手就能把图写了GitHub、GitLab这些平台原生支持渲染团队其他人看文档的时候不需要额外装工具就能看图这是它最大的杀手锏。对于需要手工精修的图比如要给客户演示的部署拓扑图、要放进售前PPT里的方案图我用draw.io。它在网页和桌面端都可用模板丰富图标库齐全还能跟GitHub/GitLab深度集成导出格式支持PNG、SVG、PDF基本能覆盖所有交付场景。这里多说一句工具选型的判断逻辑你在意的到底是一次性效率还是长期维护成本如果答案是后者就果断选代码化方案哪怕最初多花两三个小时学习。但如果你只是想快速画一张示意图发给同事那大可不必折腾学习成本直接上拖拽工具就行。工具始终是服务的纠结太久工具本身也是一种内耗。2.3 快速对比主流工具怎么选为了让你少走弯路我把这几年实际用过的主流工具按维度做了个对比。这个表里的结论不是我凭空拍的都是自己在真实项目里跑过之后的感觉。工具类型上手难度版本管理友好度图形精细度适合场景Mermaid代码化极低极好一般文档内嵌图、快速流程/时序图PlantUML代码化低极好一般UML图、需要活跃社区的团队Graphviz代码化高极好高需调参复杂结构图、自动布局优先Python diagrams代码化中极好高云架构图、系统架构图draw.io拖拽极低好配合Git高全场景尤其适合手调精细图Excalidraw拖拽极低好原生支持中手绘风快速草图、协作白板Figma拖拽中中极高高保真UI/视觉图、团队设计协作ProcessOn拖拽极低差依赖平台中国内团队快速出流程/思维导图如果非要我总结一句选型心法低频一次性图选快的高频长期维护图选稳的需要协作看图选通用的。把这三个原则放在心里基本不会选错。3. 实操过程与核心环节实现拿一张架构图走完整流程3.1 需求确认和图设文档的撰写前面说过动手前先写文字版。这里我就拿一个实际的例子走一遍。假设我们要画一套订单处理系统的架构图面向的读者是团队内部研发人员场景是系统设计评审核心想传达的信息是这套系统是分层解耦的不同层之间的依赖关系清晰可控。那么我先写出来的图设文档大概长这样展示层用户端App、运营管理后台应用层订单服务、支付服务、库存服务、消息推送服务数据层订单库、支付流水库、库存库、消息队列关键链路App创建订单 - 订单服务落库 - 调用库存服务预占库存 - 发起支付 - 支付回调 - 更新订单状态 - 发送消息通知异常关注点库存不足时订单状态流转、支付超时后如何处理写完之后通读一遍感觉还少了一个环节外部的支付网关因为支付服务本身是不直接跟银行卡打交道的中间还有一道支付网关。我补上。这时候文字版已经比最初脑子里那团乱麻清晰多了可以进入下一阶段。3.2 用代码化方案快速生成初稿我选择用Python的diagrams库来实现。核心代码很简单整个图分三列展示层、应用层、数据层每列内再纵向排布各组件层与层之间用带箭头的边连接。下面是我现场写的结构省略了部分非核心代码from diagrams import Diagram, Edge from diagrams.programming.framework import React from diagrams.custom import Custom from diagrams.generic.storage import Storage from diagrams.onprem.queue import Kafka from diagrams.programming.language import Python from diagrams.aws.compute import EC2 from diagrams.aws.database import RDS with Diagram(订单处理系统架构, showFalse, directionLR): # 展示层 app React(用户App) admin Custom(运营后台, ./admin.png) # 应用层 order_svc Python(订单服务) pay_svc Python(支付服务) stock_svc Python(库存服务) msg_svc Python(消息推送服务) # 外部网关 pay_gateway Custom(支付网关, ./gateway.png) # 数据层 db_order RDS(订单库) db_pay RDS(支付流水库) db_stock RDS(库存库) mq Kafka(消息队列) # 连线 app Edge(label创建订单) order_svc order_svc Edge(label预占库存) stock_svc order_svc Edge(label发起支付) pay_svc pay_gateway order_svc db_order pay_svc db_pay stock_svc db_stock order_svc Edge(label发送消息) mq msg_svc admin order_svc这段代码跑完后会生成一张SVG图。但说实话初稿基本不能直接用于评审——因为自动布局出来的连线可能会交叉组件大小不够整齐边上的标签位置也有点随意。所以初稿的作用是把结构和逻辑先立住不是一步到位的成品图。3.3 布局优化、配色与视觉层级调整初稿出来后就要进入diagram-design里最有讲究的环节视觉设计。我给自己定了一套基本规则到现在还在用。布局规则一张图的阅读方向尽量统一要么从左到右要么从下到上。人类阅读习惯是线性流动的图也要遵守这个规律。不要一会儿左到右、一会儿下到上读者会迷路。其次连线尽量少交叉。两线交叉就是两个信息点互相干扰交叉一多图就废了。减少交叉的办法是调整节点位置、调整连线方向必要时甚至拆图。第三相关模块尽量物理上靠近。把高内聚的概念用在图的排版上关系密的组件放一起用背景色或者虚线框圈成一个区域读者不需要靠连线也能感知到分组关系。配色规则我强烈建议把颜色当成传递信息的手段而不是装饰。每个颜色都要有语义。比如我用蓝色表示应用服务绿色表示数据存储橙色表示外部依赖灰色表示辅助元素或边缘模块。这样读者扫一眼颜色就知道图里哪块是核心业务、哪块是支撑设施信息获取成本大幅下降。同一个图里主色调不要超过3到4种颜色太多等于没有颜色还会显得花哨廉价。字体和尺寸规则统一字体族一般用无衬线体思源黑体、Inter、Helvetica都行。节点内文字字号控制在12到16之间层级越高的节点字号越大但整个图里字号层级不超过三档。边框粗细统一重要的边界线框可以加粗到2像素其余1像素。所有的规则都要克制克制才能形成风格感。把这套规则套回上面那张架构图我会调整出大概这样的结果左侧一列是展示层中间四列是应用层订单服务放在最靠近数据层的地方因为它跟数据库交互最多右侧是数据层支付网关作为外部依赖用醒目的橙色放在左侧或顶部外侧表示这是外部要对接的边界核心链路创建订单 - 预占库存 - 发起支付 - 支付回调 - 更新状态 - 发消息用更粗的实线表示其他交互用细实线。到这里这张图才开始有了设计感。3.4 导出与交付不要只丢给用户一张PNG图设计完成后交付环节也有讲究。很多人画完图从工具里导出一张PNG就发到群里这其实是不够的。我给自己的交付标准有三个格式源文件drawio / py / mmd一定保留并且入库方便后续修改和追踪变更。这是一张可以维护的图最关键的底子没有源文件这张图的寿命基本就到这次交付为止了。矢量图SVG用于文档和网页放大不糊也可以后续在Illustrator里做二次编辑。位图PNG或PDF用于聊天窗口和演示文稿导出时注意设置DPI。draw.io里的导出选项PNG的话建议分辨率填150或300 DPI不然在PPT上放大之后会发虚。很多人忽略这一点导致成品图在投影上一放大全是锯齿特别掉价。另外在交付给团队或客户时建议在同级目录放一个README或者说明文档写上图的版本、作者、更新日期、核心变化、源文件在哪。这个东西看起来繁琐但坚持做久了你会发现在三个月后再翻出这张图的时候自己会感谢当时的自己。4. 常见问题与排查技巧实录那些年我踩过的图坑4.1 连线交叉、布局混乱的深层原因和处理方法如果你画的图上连线像蛛网一样乱先别急着怪工具大概率是图的逻辑层级出了问题。我遇到的最常见原因有两个一是节点在画布上的排列顺序跟数据流向不一致二是没有利用分区比如泳道、分组框来承载逻辑边界。解决交叉问题有一个很土但很好用的办法手工调整节点顺序。Graphviz或draw.io的自动布局再智能也不如你对你的业务流程理解得深。先把所有节点排成一条或者几行让连线只在你希望的层级之间走基本可以消除百分之八十的交叉。剩下的交叉可以通过给连线加弯道或者绕行解决。在draw.io里选中一条线之后可以拖动线的中间路径点来布线路这个操作熟练之后会救你无数次。4.2 代码化绘图遇到中文乱码或字体问题Mermaid、PlantUML、Graphviz这些工具在默认配置下渲染中文经常出幺蛾子轻则变成方块重则直接乱码。背后的原因是它们依赖的字体渲染环境没有配置中文字体。以Graphviz为例解决办法是在图中显式指定支持中文的字体名称digraph G { graph [fontnameMicrosoft YaHei]; node [fontnameMicrosoft YaHei]; edge [fontnameMicrosoft YaHei]; }或者更省心的做法是给整个图设默认字体。如果你用的是draw.io或者Excalidraw这类图形界面工具很少遇到这个问题因为它们直接调用操作系统的字体系统选择中文字体即可。另外提醒一句用代码化方案绘图如果团队里有人用macOS、有人用Windows中文字体名称可能不兼容最好约定一个跨平台常见字体或者在CI环境里统一字体库否则同一个脚本在别人电脑上跑出来效果完全不同。4.3 图太臃肿信息密度失衡的调整策略画图最常见的一个问题是什么都说导致什么都没说清。我在评审会上看到的很多图属于这类一个服务框里塞了十几个内部模块一条线上挂了五六个协议说明角标注释恨不得把接口文档复制上去。信息密度失衡的根源是没想清楚这张图的表达边界。图是给人建立整体认知的不是用来承载全部细节的。如果细节真的重要正确做法是分层第一层总体架构只画服务和主要链路第二层某服务的内部结构单独画第三层某个接口的调用时序再用一张时序图。三张图各司其职比一张千层饼有效得多。另一个被忽略的瘦身技术是合并相似节点。比如订单服务里有十个内部模块如果它们对外暴露的交互方式一样就别画十个框画一个框代表订单服务细节留给代码注释。图的清晰程度跟图里节点的数量呈反比这是我踩过无数坑换来的教训。4.4 团队协作里的版本混乱问题最后说一个特别痛的问题图的版本管理。你肯定见过这种命名架构图-最终版.drawio、架构图-真最终版.drawio、架构图-改完不再改.drawio。这套命名法的结局基本一样——过两周没人记得哪一份才是墙上挂的那一份。解决思路不复杂要么全部代码化图和代码一起入库走MR流程要么用支持Git集成的工具比如draw.io配合GitHub实现文件级版本管理要么统一用在线协作白板工具让所有人都在同一条链接上改。核心原则只有一个——图跟代码/文档走同一个版本管理流程让看图成为研发流程的一部分而不是文档里的一张静态截图。我给团队定的小规矩很简单所有技术方案里的图必须有对应的源文件放在doc目录文件名规则是日期-主题-作者文字描述二十分钟、加班找图两小时这种事能少一回是一回。5. 场景延伸图设计在不同领域的具体玩法5.1 技术文档与架构评审中的架构图架构图大概是diagram-design里出镜率最高、也最容易被做砸的类型。好的架构图给评审专家的感觉是这个系统是可控的差劲的架构图哪怕系统本身设计得很合理也会让专家觉得这个人脑子里一团乱麻。画架构图时我最看重三条一是明确边界系统边界用粗框或者不同底色标出来外部依赖放在边界外面这样评审人一眼就能分清哪里是自研、哪里是集成二是突出链路主链路的连线要明显粗于辅助链路用颜色或线型跟普通交互区分开让评审人不用仔细找就能跟上核心请求的走向三是标清协议和格式关键接口边上要不要写HTTP/REST还是gRPC取决于读者有多了解系统给研发同事看可以写给甲方看就算了一句话讲不清的协议标注就是噪音。5.2 业务流程图中的泳道与角色划分业务流程图里最值钱的设计工具是泳道。泳道本质上是给图上的人或角色分配一条专属通道各角色的行为都在自己的泳道内展开这样不同角色的职责范围、交接点、审批节点一目了然。我画泳道流程图时有个习惯先列角色再列动作最后连线。角色不要在过程中想到再加动作按时间顺序垂直或水平排好交接动作画跨泳道的箭头。这里面最容易出问题的是角色漏了。比如画一个报销流程画着画着才发现漏了财务审核这个角色再去调泳道结构整个图的排版就全乱了。所以画之前图设文档里列角色这个动作一定不能省。5.3 数据中心拓扑图中的资源分层与网络路径运维场景的拓扑图核心不是好看是准确表达依赖关系。画数据中心拓扑图时我一般按物理层、网络层、应用层、业务层这样分层去画然后用聚合线表示链路聚合而不是一根根画不然图会爆炸。设备之间的连接要标注协议和端口尤其涉及安全域隔离的地方一定要把防火墙的放行策略对应的链路画清楚不然排障的时候对着图根本找不出问题。另外拓扑图里的设备建议分状态标注在用、空闲、故障、维护用不同的边框或填充色表示并配图例。这个看似简单的事情在故障紧急排障的时候能节省大量时间因为人的视线可以第一时间跳过不相关的设备。5.4 汇报PPT与对外材料里的图示表达汇报场景的图有一条游走在严谨和通俗之间的钢丝要踩。对内技术评审可以画得复杂、准确但对外汇报或给管理层看图必须做减法只保留对方关心的东西。给管理层看系统架构就突出我们有哪些核心子系统、各自的定位是什么、新方案带来什么变化不要画内部接口和协议细节。我一般会在汇报材料里放两张图一张现状图、一张目标图确保听众能通过视觉对比理解方案价值。对比时目标的简和现状的繁恰好也能帮助传达方案落地后带来的改善。这就是diagram-design里用图讲故事的能力图不只是表达事实的工具也是引导情绪的载体。6. 把图设计变成团队习惯而不是某个人的特长写到这里我觉得有一件事比所有技术细节都重要图设计的水平本质上不是画图技巧而是思考质量的外化。你的模块拆分是否清晰你的流程逻辑是否闭环你的依赖边界是否明确全部会通过一张图暴露无遗。所以提升图设计的过程其实是在逼自己把业务逻辑想得更透彻这项能力对任何岗位都是加成。如果你现在正在为画不好图发愁我的建议是从小处开始练找一张你最近画过的图用今天文章里的方法重新设计一遍——先写文字版图设再调整布局再收敛配色再检查信息密度。走完这一圈之后你会发现画图这个动作本身并没有变但产出的图完全不一样了。最后分享一个我一直在用的小习惯每次画完图我都会把图导成PNG丢到手机相册里第二天再翻出来看一眼。隔了一夜带着一点第一次看这张图的陌生感那些之前因为太熟而看不出来的问题——标注不清、边界混乱、重点不突出——往往一眼就能揪出来。这个方法我从入行用到现在救过我无数次。