1. 从diagram-design这个标题能读出什么第一次看到diagram-design这个标题我的直觉是这不是一个具体工具的名字而是一类工作的统称——围绕图做设计。图可以是流程图、架构图、时序图、状态机图、思维导图、数据流图甚至是手绘风格的概念草图。标题里没有限定领域也没有指定工具这恰恰说明它指向的是一个通用能力把抽象的逻辑关系、系统结构、业务流程用可视化的方式表达清楚。很多人第一次接触画图这件事会觉得它是个体力活——拖拖拽拽、对齐连线、调调颜色就完事了。但真正做过复杂系统设计的人都知道图的质量直接决定了沟通效率。一张好的架构图能让新人在五分钟内理解系统边界一张糟糕的图能让团队开三小时的会还在争论这个箭头到底代表什么。所以diagram-design这个标题背后真正要解决的不是怎么画而是怎么把复杂信息压缩成一张能被正确理解的图。这篇文章适合三类人看第一类是需要频繁输出技术图但总觉得画出来不够清晰的工程师第二类是要给非技术角色讲清楚系统逻辑的产品或项目人员第三类是对可视化表达有兴趣、想建立一套自己画图方法论的人。我会从设计原则、工具选型、实操流程、常见坑几个角度展开尽量把为什么这样画讲透而不是只给一堆模板。2. 画图之前先想清楚图到底为谁服务2.1 图的三种读者决定了三种画法我踩过最大的一个坑就是曾经用同一张架构图去应付三个不同的场合给领导汇报、给开发讲解、给运维交接。结果三个场合的人都不满意。领导觉得太细开发觉得太粗运维觉得缺关键信息。后来我才明白图不是客观真理它是针对特定读者的信息压缩包。读者不同压缩策略就完全不同。给决策者看的图核心是边界和关系。他们不关心你用了什么消息队列、分几个分片他们关心的是这个系统跟哪些外部系统有交互、数据从哪来到哪去、出问题的时候影响面有多大。所以这类图要克制细节用大色块区分模块用粗箭头表示主数据流把次要的调用关系弱化甚至省略。给开发者看的图核心是接口和时序。他们需要知道模块之间通过什么协议通信、调用顺序是什么、异常分支怎么处理。这类图适合用时序图或带标注的流程图把关键参数、超时设置、重试策略都标出来。我习惯在时序图旁边加一个异常路径的小图专门画失败重试和降级逻辑这个习惯帮我省了很多口头解释。给运维看的图核心是部署和依赖。他们关心的是服务部署在哪些节点、依赖哪些中间件、监控指标从哪采集、故障时先看哪个面板。这类图适合用部署图或网络拓扑图把 IP 段、端口、健康检查路径都标清楚。一个实用的判断方法画图之前先问自己这张图给谁看他看完之后要做什么决定。如果答不上来说明你还没想清楚先别打开画图工具。2.2 一张图只讲一件事新手最容易犯的错是想在一张图里塞下所有信息。我见过一张系统全景图上面同时画了业务流程图、数据流、部署拓扑、监控告警密密麻麻像电路板。作者很得意觉得信息量大但读者根本找不到入口。我的经验是一张图只回答一个问题。如果一个问题需要多个视角才能说清就拆成多张图然后用一张索引图把它们串起来。比如描述一个订单系统我会拆成四张订单状态流转图回答订单有哪些状态、怎么流转、下单时序图回答一次下单经过哪些服务、部署拓扑图回答这些服务部署在哪、数据模型图回答订单数据怎么存。每张图都简单但合起来信息完整。拆图的好处不只是清晰还在于可维护。系统改了某个流程我只需要更新对应的那一张图不用动其他三张。如果全塞在一张图里改一处就要重新调整全局布局成本极高。2.3 先定图例再画内容这个习惯我是从一位做数据可视化的前辈那里学来的。他的做法是任何一张正式图先在角落画一个图例区定义清楚每种形状、每种颜色、每种线型代表什么。比如实线代表同步调用、虚线代表异步消息、红色代表失败路径、蓝色代表正常路径。听起来很基础但实际工作中大量图是没有图例的。结果就是读者靠猜这个虚线框是可选模块还是外部系统这个菱形是判断还是数据存储一旦读者开始猜图的沟通价值就大打折扣。图例还有一个隐藏好处它逼你在画之前统一语义。很多时候我们画到一半才发现前面用圆形表示服务后面又用矩形表示服务风格不一致。如果先定图例这种问题在动笔前就解决了。3. 工具选型别在工具上纠结太久3.1 三类工具的适用边界关于画图工具我的态度很明确工具不重要重要的是你能不能快速改。因为图几乎一定要改需求变了要改、系统演进要改、读者反馈要改。如果一个工具改起来很痛苦你就不愿意改图就会慢慢过期最后没人看。我把常见工具分成三类。第一类是代码生成类用文本描述图工具渲染成图片。这类工具的最大优势是版本可控、diff 清晰、改起来快。适合架构图、时序图、状态机图这类结构性强、需要频繁迭代的图。缺点是样式调整不够灵活想要精细的视觉设计比较费劲。第二类是拖拽绘制类就是传统的画图软件。优势是自由度高想怎么摆就怎么摆适合概念草图、需要精细排版的汇报图。缺点是改起来麻烦而且不同人画出来的风格很难统一。第三类是白板协作类适合头脑风暴阶段的快速草图。优势是多人实时协作适合讨论。缺点是正式输出时通常需要重新整理因为白板上的图往往比较随意。我的实际组合是讨论阶段用白板类工具快速画草图确定结构后用代码生成类工具产出正式图只有需要对外汇报、对视觉要求高的场合才用拖拽类工具精修。这样既保证了迭代速度又保证了正式输出的质量。3.2 为什么我优先推荐代码生成类很多人觉得用代码画图很反直觉——画图不是应该所见即所得吗但我用了几年之后越来越倾向于代码生成。原因有三个。第一改起来真的快。系统加了一个服务我只需要在文本里加一行重新渲染就完事了不用手动调整周围所有元素的位置。拖拽工具里加一个节点往往要重新对齐一整片区域。第二版本管理友好。文本文件可以进代码仓库每次改动都有记录谁在什么时候改了什么一目了然。图片文件做不到这一点你只能看到图变了但不知道变了哪里。第三强制你关注结构而非样式。用代码画图时你描述的是A 调用 BB 依赖 C而不是A 这个框放在 B 左边颜色调成浅蓝。这种约束反而让你更专注于逻辑本身画出来的图通常更清晰。当然代码生成类工具也有短板。比如复杂的嵌套布局、非标准的视觉元素实现起来比较别扭。所以我的建议是结构性的图用代码生成视觉性的图用拖拽工具不要强求一个工具解决所有问题。3.3 一个容易被忽略的选型维度协作成本选工具时大家通常看功能但我认为协作成本更关键。所谓协作成本就是别人要改你这张图需要付出多少学习成本。如果团队里只有你一个人会用某个冷门工具那这张图就成了你的私有资产你一休假就没人能改。反过来如果工具足够普及、语法足够简单团队里其他人能快速上手图的维护就不再依赖单个人。所以我在团队里推工具时会优先选语法简单、文档齐全、上手快的。哪怕功能少一点只要大家都能改就比功能强大但只有一个人会用要好。这个原则在人员流动频繁的团队里尤其重要。4. 一套可复用的画图流程4.1 第一步用一句话写下图的主题听起来很傻但这一步能过滤掉大量无效工作。如果我不能用一句话说清这张图要表达什么那说明我还没想清楚画出来大概率是废图。这句话的格式我习惯用这张图展示 X 在 Y 条件下的 Z。比如这张图展示订单服务在正常下单场景下的调用时序、这张图展示系统与外部支付渠道的边界关系。有了这句话后面所有内容都要服务于它不相关的信息一律砍掉。4.2 第二步列出所有元素先不画关系确定主题后我会先把图里要出现的所有元素列出来——有哪些服务、哪些数据存储、哪些外部系统、哪些角色。这一步只列清单不画连线。列清单的好处是防止遗漏。画图时很容易画着画着发现哎这个服务忘了然后临时插入导致布局混乱。先列全再统一布局效率高很多。列完之后我会做一次筛选哪些元素是核心哪些是次要。核心元素放在视觉中心次要元素放在边缘。这个主次关系直接决定了读者第一眼看哪里。4.3 第三步先画主干再补分支布局时我遵循主干优先原则。先把最主要的几条关系画出来比如主调用链、主数据流确保主干清晰。然后再补异常分支、次要依赖、监控采集这些辅助信息。这样做的原因是读者的注意力是有限的如果主干和分支混在一起画读者很难分辨哪些是重点。先画主干相当于给读者一条阅读路径他顺着主干看下去再根据需要看分支。我见过很多图的问题就在于没有主干——所有连线看起来同等重要读者不知道从哪看起。这种图通常是因为作者没有区分主次把所有关系都平铺了。4.4 第四步加标注但只加必要的标注是图的注释能大幅提升信息密度但加多了会变成噪音。我的原则是只标注读者会问的问题。比如时序图里我会标注关键的超时时间、重试次数、幂等键。因为这些是读者看的时候一定会问的这个调用失败了怎么办会不会重复下单提前标出来就不用口头解释了。但像这个服务用什么语言写的这个数据库是什么版本这类信息除非跟图要表达的主题直接相关否则不加。加了只会让图变乱。4.5 第五步找人试读收集看不懂的点图画完之后我会找一个没参与设计的人试读让他说出他理解的内容然后对比我想表达的内容。差异点就是需要修改的地方。这一步非常关键但很多人省略了。因为作者对自己的图太熟悉了会自动脑补缺失的信息看不出问题。只有没背景的人才能暴露真正的歧义。试读时我通常问三个问题这张图在讲什么你觉得哪个部分是核心有没有你看不懂的地方根据回答调整通常改两三版就能达到自解释的程度。5. 那些年我踩过的画图坑5.1 坑一追求好看牺牲清晰刚工作那会儿我特别在意图的颜值——配色要高级、阴影要柔和、圆角要统一。结果花了两小时调样式图是好看了但逻辑一团糟。后来被一位前辈点醒图的第一目标是让人看懂不是让人夸好看。现在我画图样式一律从简黑白灰为主最多用两三种颜色区分模块形状只用矩形和圆角矩形连线只用直线和折线。把省下来的时间花在逻辑梳理上图的沟通效果反而更好。当然对外汇报的图可以适当美化但前提是逻辑已经清晰。美化是锦上添花不是雪中送炭。5.2 坑二连线交叉太多读者迷路连线交叉是画图里最影响可读性的问题之一。我早期的图经常像蜘蛛网线到处飞读者要顺着线找半天才能找到目标。减少交叉的方法有几个。一是调整元素顺序把有调用关系的元素放在相邻位置。二是用跳线符号表示线交叉但不连接。三是把复杂关系拆成多张图不要硬塞在一张里。还有一个技巧是分层把不同层级的东西画在不同水平线上上层调用下层这样连线大多是垂直的交叉自然就少了。5.3 坑三图更新不及时变成历史文物这是最隐蔽也最致命的坑。系统一直在演进但图没人更新半年后图上的服务已经下线了新加的服务没画上去。这时候图不仅没用还会误导人。我的应对方法是把图纳入变更流程。每次系统有架构级改动必须同步更新对应的图跟代码一起提交。这样图就跟着系统一起演进不会过期。另外我会在图里标注最后更新时间和对应版本。读者看到时间比较久就知道要谨慎参考主动去确认最新情况。5.4 坑四一个人闷头画不跟读者确认我曾经花了一整天画了一张自认为很完美的架构图拿去汇报时被领导问这个模块跟那个模块是什么关系我才发现我默认大家都知道的关系领导并不知道。后来我养成了一个习惯画图前先跟主要读者确认你希望这张图回答什么问题。有时候读者要的跟我以为的完全不一样。提前对齐比画完再返工划算得多。6. 让图自解释的几个细节技巧6.1 用命名传递信息元素命名不要用服务A模块B这种无意义代号直接用能表达职责的名字比如订单创建服务库存扣减服务。读者看到名字就知道它是干什么的不用额外解释。如果名字太长可以用缩写但要在图例里说明。比如OMS代表订单管理服务第一次出现时标注全称。6.2 用方向表达语义箭头方向要统一语义。我习惯用箭头指向被调用方表示调用关系箭头指向数据流向方表示数据流。同一张图里不要混用两种语义否则读者会混淆。如果一张图里既有调用又有数据流我会用不同线型区分实线表示调用虚线表示数据流。并在图例里写清楚。6.3 用分组表达边界系统边界、团队边界、部署边界都可以用分组框表达。分组框能帮读者快速理解哪些东西是一伙的。分组不要嵌套太深两层就够了。三层以上的嵌套会让图变得难以阅读这时候应该考虑拆图。6.4 用留白引导视线留白不是浪费空间而是引导读者视线的工具。核心元素周围留出足够空白读者自然会先看那里。如果所有元素都挤在一起读者会感到压迫不知道从哪看起。我画图时会在核心模块周围留出至少一个元素宽度的空白边缘的次要元素可以紧凑一些。这种疏密对比能有效突出重点。7. 从画图到设计图的思维转变7.1 图是设计工具不是记录工具很多人把画图当成记录已经想好的东西但我的体会是画图本身就是设计过程。当你试图把逻辑画出来时很多之前没想清楚的问题会暴露出来——这个分支怎么处理这个循环会不会死锁这个依赖是不是多余所以我现在画图往往在系统还没完全定型时就开始画。画的过程就是推演的过程画完图设计也清晰了。图不是设计的产物而是设计的一部分。7.2 图是沟通契约不是个人表达一张被团队接受的图实际上是一份沟通契约——大家约定用这张图作为讨论的基础。这意味着图不能太个人化要符合团队的共同理解。比如团队习惯用某种颜色表示某种含义你就不要为了好看改成别的颜色。团队习惯某种布局方式你就尽量沿用。图的个性应该体现在逻辑的清晰度上而不是视觉的标新立异上。7.3 图是活的资产需要持续投入最后一点体会图不是画完就完事的它需要持续维护。一个团队如果能把核心图维护好新人的上手成本会大幅降低跨团队沟通的效率也会提升。所以我会建议团队指定图负责人专门负责核心图的更新和审查。这个投入看起来是额外的但长期看回报很高。一张维护良好的架构图能省下无数次口头解释和会议讨论。8. 我个人的几个实操习惯最后分享几个我一直在用的小习惯都是踩坑之后总结出来的。第一个习惯画图前先在纸上画草图。纸上的自由度最高改起来最快适合快速试错。确定结构后再用工具正式画效率比直接在工具里改高很多。第二个习惯给图起一个描述性的文件名。比如订单服务-正常下单时序-2024版而不是图1新建文件。文件名本身就是一种文档方便日后查找。第三个习惯重要图导出两种格式一种矢量图用于放大查看一种位图用于快速预览。矢量图在缩放时不会模糊适合正式场合位图加载快适合日常沟通。第四个习惯定期回顾旧图。每隔一段时间翻翻之前画的图看看哪些已经过期、哪些还能用。这个过程也能帮你发现自己设计思路的演进挺有意思的。画图这件事说到底是一种把复杂变简单的能力。工具会变、样式会变但让读者快速正确理解这个目标不会变。把精力花在逻辑梳理和读者视角上比花在工具技巧上回报高得多。