前几个月做一个内部项目需要向协作方讲清楚一条跨系统的调用链路。我打开在线画图工具拖了四十多个框出来连上线标好颜色自认为信息很全。发给对方之后收到的反馈只有一句这图我看不懂。这句看不懂让我重新认真对待 diagram-design 这件事。画图的门槛看起来极低拖拖拽拽谁都会但真正能让人三秒抓住重点、顺着箭头走完全程的图门槛其实相当高。这篇内容是我近一年在 diagram-design 上的完整复盘涉及读者分析、工具取舍、画图流程、实战迭代和长期维护适合那些经常要画架构图、流程图、时序图却总觉得图不够清楚的开发者和产品同学。1. 先搞清楚一件事你画的图是给谁看的1.1 一次看图失败引发的重新思考那天我画的是一套跨模块的异步消息链路四十多个节点二十多条线还用了四种颜色区分不同服务。发到协作群之后对面负责业务的同事问了一句我就想知道订单状态更新之后接下来发生啥你这图里在哪我指着左上角那一堆框说从这儿开始。他又问那我为啥要看完右边这些我一时答不上来。右边那些是日志采集、监控告警的旁路节点对他的问题毫无意义但在我的图里它们和核心链路占据着同样醒目的位置。这件事让我意识到diagram-design 的第一个问题永远不是用什么工具而是读者是谁、他要带走什么信息。同一套系统给架构评审画的图、给业务方讲链路画的图、给新人做 onboarding 画的图完全可以长成三个样子。一张图想讨好所有人最后往往谁都用不了。1.2 三种典型读者和对应的信息取舍我把日常遇到的读者粗分成三类每一类的关注点和画法差别很大决策型读者关注边界、依赖关系、风险点。他们要的是整体拓扑和模块职责不需要知道每个接口字段。执行型读者关注具体流程、输入输出、异常分支。他们要的是主链路和分支条件不需要看部署拓扑。排查型读者关注时序、状态流转、故障入口。他们需要的是事件顺序和因果链。对应的画法完全不同。给决策型读者画要突出分组和边界用大色块区分领域连线只画关键依赖给执行型读者画要从触发事件开始沿着流程一步步走分支画全但旁路灰化给排查型读者画要用泳道或时序的表达方式把谁在什么时间调了谁讲清楚。我见过的大部分烂图根因不是画得不够多恰恰是画得太全。把三类读者的需求硬塞进一张图结果就是谁都没法快速拿到自己关心的东西。画之前先问一句这张图给谁看能省掉后面所有返工。1.3 信息密度的三秒法则我后来给自己定了一个粗糙的检验办法把图发给一个不了解上下文的人让他看三秒然后说出这张图在讲什么。如果他说不出来说明图的视觉重心是散的需要重画。三秒法则背后是很朴素的认知心理学常识人眼的注意力有限第一眼只会落在面积最大、颜色最亮、线条最粗的元素上。如果你把所有元素都设计得同样醒目那就等于没有重点。diagram-design 的核心能力本质上是做减法的能力。我现在遵守一条铁律每张图只允许有一个视觉焦点。主链路用实线、饱和色辅助流程用虚线、灰调纯背景信息直接不画。读者需要更多细节时他自然会放大、看注释、问你要第二种图但第一眼你必须告诉他该看哪儿。2. 工具选型别让工具限制你的表达2.1 四类工具和它们各自的主场先说结论没有万能工具只有匹配场景的工具。我日常实际在用的大概四类每一类都有自己的主场。第一类是轻量拖拽型包括在线白板工具和本地开源的轻量画图工具。它们最适合画快速沟通图——需求讨论、方案说明、评审草图。优点是上手零成本拖拖拽拽几分钟就能出图缺点是规范性差同一个箭头在不同人手里可能表达完全不同的意思图一复杂就乱。第二类是文本描述型工具用代码写图的描述再生成图形。它最适合画需要反复修改的工程图尤其是时序图、状态图这类结构重复度极高的图。优点是可版本化、可 diff、改起来快一段文本就能完整表达结构缺点是布局控制不自由学习曲线也比拖拽型陡一些。第三类是专业图表软件适合画网络拓扑、机房布线、组织架构这类对图形规范要求极高的场景。优点是元素库完整、画出来非常标准缺点是偏重、偏贵协作体验一般画逻辑图有点杀鸡用牛刀。第四类是通用设计工具适合画最终要进文档、进 PPT、进官网的高质量配图。好处是排版、配色、字体完全可控能画出很有质感的成品坏处是它本质是设计工具画逻辑图偏重维护成本也高。2.2 两种范式的取舍拖拽和文本描述我见过很多团队在工具选型上吵得不可开交。其实核心矛盾就一个拖拽型所见即所得但改起来没有痕迹文本描述型有源码可以追踪变更但预览和布局控制没那么自由。我的选择标准很粗暴如果只是几个人快速对齐思路拖拽型完胜别纠结规范和溯源如果这张图要进文档库、要长期维护、要多人修改那就必须用文本描述型或者至少给拖拽型图配上严格的版本管理。原因很简单。拖拽型图最大的问题不是画不出来而是三个月后没人记得当初为什么这么连。文本描述型强制你把节点和关系写成可读的文本每次改动都有记录哪怕后来的人看不懂图也能通过描述里的注释还原当时的思路。2.3 我的实际组合快图、活图和精图我跑了快一年固定组合是这样日常沟通图用轻量拖拽工具随开随画用完就扔正式文档里的架构图、时序图、状态图用文本描述型工具生成源文件跟着代码仓库走要上 PPT 和对外文档的高质量图最后在通用设计工具里重新排一版。这套组合看起来折腾实际跑下来很顺。因为 90% 的图都是沟通完就作废的只有剩下 10% 需要长期活着。正式化是有成本的这个成本要花在真正需要长期活着的图上而不是每张图都追求最终成品。3. 我整理的一套四步画图法3.1 第一步先写文字骨架再碰画布我踩过最大的坑就是拿起工具就画。看起来效率很高其实画到一半逻辑就乱然后开始疯狂删框、挪位置、改连线最后画出来的东西连自己都看不下去。现在的第一步永远是拿文本编辑器写图稿。比如画一个订单超时关闭的流程我先把逻辑写成几行字触发条件是用户下单后 30 分钟未支付定时任务扫描符合条件的订单加锁并标记超时关闭中判断库存是否可释放释放库存、记录超时日志通知消息服务推送提醒。写完这几行再判断图形结构。这六行是线性流程用普通流程图如果还涉及多个服务之间的来回调用就得考虑泳道如果重点是状态变化优先画状态图。文字骨架最大的好处是逼你先想清楚有哪些节点和节点之间什么关系而不是被一块空白画布吓到。3.2 第二步按表达目的选图型、定画布方向文字稿确定之后就要决定用哪种图表达。我通常按这套规则选省脑子的很关心谁在什么时候做了什么 → 时序图或泳道图关心一件事的先后顺序和分支 → 流程图关心系统由哪些模块组成、谁依赖谁 → 架构图关心一个对象的所有可能状态 → 状态图关心数据从哪来到哪去 → 数据流图选型之后是画布结构。我的习惯是从上到下或从左到右二选一主流程从上往下走辅助说明放侧面泳道按角色分列时间从上往下推进。画布方向一旦确定整张图的阅读方向就确定了读者顺着方向走不会迷路。3.3 第三步让颜色、线型和箭头只说语义这一步是我最想分享的心得。很多图视觉混乱是因为颜色随便用、线型随便选、箭头方向不统一。我给自己定了五条死规则违反任何一条都直接返工第一颜色必须有语义只用于表达类别或状态不用于装饰。比如所有外部系统一种色所有内部服务一种色所有数据存储一种色。第二实线代表已实现的正式调用虚线代表异步、事件或旁路两种线不可以混着表达。第三箭头方向统一指向数据或控制的流向目的地不要一会儿从发起到接收一会儿从接收到发起。第四文字标签放在线条的中部上方不要断线不要叠在节点框上。第五同一张图里同一种图形只表达同一种含义矩形是服务或模块圆角矩形是状态或流程步骤菱形是判断圆柱是存储。不要今天这个意思、明天换个意思。这些规则听起来基础到近乎啰嗦但你翻翻身边项目里的图十条有八条违反。视觉表达一旦混乱读者就只能靠猜。3.4 第四步交付前一晚的陌生化检查画完之后我通常不会立刻发出去而是把图放一晚上第二天当作自己完全没参与过重新看一遍。检查顺序固定先看整体第一眼落在哪是不是我想让它落的地方再看主链路能不能不读任何注释、只顺着实线走一遍接着看分支每个分支有没有明确的是/否或者成功/失败标签最后看细节字体大小是否一致、命名是否统一比如同一张图里别一会儿写订单服务一会儿写order-service。陌生化检查的核心是换一双眼睛。你画图时脑子是满的所有省略你都默认读者知道但读者真的什么都不知道。放一晚上这个动作看起来笨却是性价比最高的排错手段。4. 实战复盘一张系统架构图的三轮迭代4.1 第一版什么都想画结果什么都没讲清我拿一个模拟项目举例叫某跨平台订单系统涉及客户端、网关、订单服务、支付服务、库存服务、消息队列、日志平台、监控系统。第一版我把所有东西都画进去了每个服务一个框框里再画子模块连了二十多条线旁边还挂了数据表结构。结果就是前面说的没人看得懂我自己看都觉得累。问题出在哪我用装饰性颜色给每个服务上了不同色颜色带不来任何分类信息我在每个框里堆满细节导致框与框之间的连接关系被完全淹没我还把监控、日志这类不属于订单主链路的内容放在和支付服务同样醒目的位置。这一版教会我一件事图的价值不在于信息量而在于信息结构。堆得越多结构越模糊。4.2 第二版按层次重组给主链路让路第二版我做了三件事。第一把所有节点分成四层接入层客户端、网关、业务层订单、支付、库存、基础设施层数据库、消息队列、支撑层日志、监控。第二主链路只保留下单 → 支付 → 库存扣减 → 通知这一条用加粗实线表示支撑层整体灰化放在图底部只画虚线连到业务层。第三所有颜色改成按层赋色接入层一种色业务层一种色基础设施一种色支撑层一种色。这一版清晰了很多第一眼就知道系统分几层、主链路在哪。但评审时还是有人问这四个层之间的调用是从上往下还是从下往上我意识到分层是对的但箭头方向和层次关系没有协调好。4.3 第三版让箭头带着读者走完主流程第三版我定了一条硬规矩主流程的箭头一律从上往下、从左往右不允许出现回头线。回头线是架构图的大忌读者一旦要掉头就得在图上反复横跳。对于订单创建后要异步通知支付结果这种确实需要回流的场景我把它单独拿出来在图右侧画了一个局部时序图而不是硬塞进主架构图里。改完的效果很明显一个新同事第一次看这版图顺着箭头不到一分钟就走完了主流程还能独立回答出支付失败会走哪条线这种问题。这三轮迭代让我最大的体会是改图不是改细节是改取舍。每一轮都在问同一个问题——读者最需要看到什么答案清晰了图自然就清楚了。5. 比画图更重要的两件隐性工作5.1 图也是资产要跟着代码一起进版本管理很多团队把图当成一次性产物画完丢共享网盘连文件名都不规范。半年后要更新先得花半小时找最终版_改3_真的最终版.png。这种事我干过太多次。如果你用文本描述型工具画图这个问题天然就解决了——源文件跟着代码仓库走每次改动有记录、有历史、能对比。如果必须用拖拽型工具那就约定好导出统一的源格式放进专门目录并且每次内容变更必须配提交说明。我的习惯是仓库里建一个 diagrams 目录按项目分文件夹命名规则统一比如项目名-图类型-主题。任何人想找图路径是确定的不需要问人。5.2 建一份自己的图元素库和参考案例集画图画多了会发现大量重复一样的服务节点、一样的箭头风格、一样的层次布局。每次从零画一遍是巨大的浪费而且风格还不统一。我目前维护一份自己的图元素库常用服务节点模板、数据库节点模板、消息队列模板、三套配色方案、几种标准布局骨架全都存成可复用格式。画新图时直接拖模板几分钟就能出初稿。另外我会把画得好的图存成参考案例旁边用注释写清楚这张图好在哪里、用的什么布局、颜色怎么分的。下次画同类图之前先翻一遍能少走很多弯路。这比收藏一堆网上教程有用得多因为参考案例是你自己验证过的。5.3 关于提升画图能力的一件小事工具、模板、流程全是外围真正决定图的质量的是动笔之前有没有想清楚读者要什么。我见过有人用很普通的工具画出非常清楚的图也见过有人用顶级工具画出一团乱麻。如果你也想提升 diagram-design 的能力我建议从一件小事开始把你最近画过的一张自己觉得挺好的图拿出来用三秒法则自测一遍然后试着把节点删掉一半看看信息是不是反而更清楚了。我自己做过几次这个练习印象最深的是第一次——删完一半节点之后那张图居然比我精心画了三个小时的原版更容易看懂。这个练习做上十次你再看图的感觉会完全不一样。