1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次看到 “diagram-design” 这个标题很多人会以为它只是教你怎么画流程图、时序图或者架构图。但真正做过技术方案、写过设计文档、跟产品运营吵过架的人会明白图只是表象背后真正要解决的是信息如何被准确、高效、低损耗地传递。我做了十多年一线开发和技术方案见过太多团队把图画得花里胡哨结果评审会上没人看得懂也见过一张极简草图五分钟就让所有人对齐了方案。diagram-design 的核心就是把这件“看起来靠感觉”的事情拆成一套可复用的设计系统。它适合谁如果你是需要写技术方案的后端、前端、架构师或者是需要把复杂业务逻辑讲清楚的产品经理、项目经理甚至是需要给客户做方案汇报的售前同学这套东西都能直接用。它不挑工具不依赖某个特定软件核心是一套思考框架和落地方法。你可以用它在白板上画草图也可以用代码生成图表甚至用设计工具做高保真架构图。关键是图背后的逻辑要立得住。我先把结论放在前面diagram-design 不是“画图技巧合集”而是一套从信息分层、视觉编码到协作评审的完整工作流。它要解决的问题包括图太复杂没人看、图太简单说不清、图更新不及时导致文档过期、不同角色对同一张图理解不一致。这四个问题几乎每个技术团队都踩过。接下来我会从设计思路、核心细节、实操过程、常见问题四个维度把这套方法拆开讲透。2. 整体设计思路为什么你的图总是“画了等于没画”2.1 信息分层先决定“不画什么”再决定“画什么”很多人画图的第一反应是打开工具拖几个框连几条线。但 diagram-design 的第一步恰恰相反先做减法。一张图能承载的信息量是有限的心理学里有个粗略的经验值人在一次浏览中能同时处理的视觉元素大约在 7±2 个。你硬塞 30 个节点进去读者的大脑直接宕机。我的做法是先把要表达的信息分成三层核心层这张图必须让读者记住的 1 到 3 个关键点。比如“订单服务通过消息队列异步通知库存服务”这就是核心。支撑层为了理解核心层而必须存在的上下文。比如订单服务、库存服务、消息队列这三个节点。细节层可以放到附录、备注或者第二张图里的内容。比如消息队列的具体型号、重试策略、死信队列配置。实操中我会拿一张纸先把所有想画的东西列出来然后强制自己划掉细节层。划掉的内容不是丢掉而是放到图下方的“补充说明”里或者单独出一张“部署细节图”。这样主图永远保持清爽读者第一眼就能抓住重点。注意信息分层不是一次性的。评审时如果发现有人反复问某个细节说明这个细节应该被提升到支撑层甚至核心层。图的层次是跟着沟通效果迭代的。2.2 视觉编码颜色、形状、线条都是有“语法”的diagram-design 里最容易被忽视但又最影响理解效率的是视觉编码的一致性。我见过一张图里蓝色既表示“数据库”又表示“外部系统”虚线既表示“异步调用”又表示“可选依赖”。读者每看一个元素都要重新猜含义认知负担直接翻倍。我的经验是建立一套最小视觉语法并且在整个文档甚至整个团队里保持一致。下面这张表是我常用的编码规则你可以直接抄视觉元素含义使用场景实线箭头同步调用HTTP、RPC 等请求-响应模式虚线箭头异步消息消息队列、事件通知粗边框矩形核心服务当前方案的重点模块细边框矩形辅助服务日志、监控、配置中心圆柱体数据存储数据库、缓存、对象存储红色风险点/瓶颈需要重点讨论的环节灰色已有系统/不在本次范围减少干扰这套规则不需要多复杂关键是团队内达成共识。我们团队曾经因为“虚线到底表示异步还是表示弱依赖”吵了半小时后来直接把规则写进文档模板新同学入职第一周就要过一遍。从那以后评审会上关于图本身的争论少了至少一半。2.3 工具选型别让工具绑架你的表达diagram-design 不绑定工具但不同场景下工具的选择确实影响效率。我按使用场景分三类白板/草图阶段纸笔或者白板最好。这个阶段目标是快速对齐不要纠结美观。我习惯用不同颜色的便利贴代表不同服务随时可以撕下来重排。文档/评审阶段推荐用代码生成图表的工具比如 PlantUML、Mermaid 或者 Structurizr。好处是图可以跟代码一起进版本管理改起来快而且风格统一。坏处是学习成本但一次投入长期受益。汇报/对外阶段可以用设计工具做高保真图但前提是前面的逻辑已经跑通了。我见过太多人直接跳到这一步结果图很漂亮逻辑一塌糊涂。提示如果你团队还在用截图贴文档的方式强烈建议换成代码生成。截图最大的问题是无法追溯、无法 diff、无法批量修改。代码生成的图改一行文本就能更新评审时直接看 diff 就行。3. 核心细节解析一张好图的五个关键决策点3.1 粒度控制一张图只讲一件事这是我最想强调的一点。很多技术方案文档里一张图试图同时表达业务架构、技术架构、部署架构、数据流。结果就是每个维度都画了一点但每个维度都说不清。diagram-design 的原则是一张图只回答一个问题。比如“订单系统重构”这个项目至少需要三张图业务流程图回答“用户下单后发生了什么”面向产品和运营。服务依赖图回答“订单服务依赖了哪些下游”面向开发和架构评审。部署拓扑图回答“这些服务部署在哪些节点上”面向运维和 SRE。每张图的读者不同粒度自然不同。业务流程图可以粗到只画“下单-支付-履约”三个框服务依赖图要细到具体接口和中间件部署拓扑图要标清楚机房、集群、副本数。如果你把这三张图合并成一张读者会疯掉。3.2 布局方向从左到右还是从上到下有讲究布局方向直接影响阅读顺序。我的经验是时间顺序或调用链从左到右。比如用户请求经过网关、服务 A、服务 B、数据库横向排列最符合直觉。层级关系从上到下。比如接入层、逻辑层、存储层纵向排列能体现上下级依赖。网络拓扑按实际地理或逻辑区域分组。比如同机房的服务放一起跨机房用虚线框隔开。有个细节很多人忽略箭头方向要统一。如果一张图里有的箭头从左到右有的从右到左读者会不自觉地来回扫视效率很低。我通常强制所有主流程箭头从左到右只有回调和反向依赖才用反向箭头并且用不同颜色标出来。3.3 命名规范节点名字决定图的可读性节点命名是 diagram-design 里最“不起眼”但最影响体验的部分。我见过太多图里写着“ServiceA”、“Module1”、“DB”读者根本不知道这是什么。好的命名应该满足三个条件见名知意order-service比svc-a好inventory-db比db1好。长度可控太长会撑爆框太短看不懂。我的经验是中文 4 到 8 个字英文 2 到 3 个单词。一致性如果用了中划线命名全图都用中划线如果用了驼峰全图都用驼峰。不要混用。另外我习惯在节点名字下方用小字标注技术栈或版本比如order-service下面写Spring Boot 3.x。这样评审时不用额外解释信息密度也上去了。3.4 注释与图例别让读者猜图例是 diagram-design 里最容易被省略但最不该省略的部分。一张没有图例的图读者只能靠猜。我的做法是任何非标准视觉元素都必须有图例。比如你用了红色虚线表示“降级方案”那图例里就要写清楚。注释的使用也有技巧。我通常把注释放在图的右侧或下方用编号跟图中的节点对应。比如图中节点旁边标个 ①右侧写“① 该服务在高峰期 QPS 超过 5000 时会触发限流”。这样既不破坏图的整洁又能补充关键信息。注意图例和注释不要超过图本身面积的 30%。如果注释太多说明这张图承载了太多信息应该拆图。3.5 版本与变更图是会过期的这是最痛的一点。我见过太多文档里的图还是两年前的版本服务早就拆了图里还画在一起。diagram-design 要求每张图都有版本号和最后更新日期并且跟代码一样进版本管理。我的做法是在图下方加一行小字v2.3 | 最后更新2024-06 | 变更新增库存服务异步通知。这样读者一眼就知道这张图的新旧程度。如果图是用代码生成的直接跟代码仓库关联每次合并请求自动更新图根本不会过期。4. 实操过程从零开始设计一张架构图4.1 第一步明确读者和目的动手之前先问自己三个问题这张图给谁看开发、产品、运维还是老板他们看完后要做什么决策评审通过、排期开发还是汇报他们最关心什么性能、成本、还是交付时间这三个问题的答案决定了图的粒度和重点。比如给老板看的图重点画业务价值和系统边界技术细节全部收起来给开发看的图重点画接口和依赖业务背景一笔带过。4.2 第二步列出所有元素并分层拿一张纸把所有想画的服务、中间件、数据库、外部系统列出来。然后按前面说的三层法分类核心层必须出现在主图上的通常不超过 7 个。支撑层为了理解核心层而存在的可以放在主图边缘或者用浅色表示。细节层放到注释或第二张图。我通常会做一个表格来管理这些元素元素名称层次类型备注订单服务核心服务本次重构重点库存服务核心服务异步通知消息队列核心中间件削峰填谷监控系统支撑基础设施浅灰色表示重试策略细节配置放注释4.3 第三步选择布局并画草图根据元素之间的关系选择布局。如果是调用链从左到右如果是分层从上到下。先用纸笔或者白板画草图不要打开工具。这个阶段目标是快速试错画错了擦掉重来成本极低。我画草图时会用不同颜色的笔黑色画主流程蓝色画数据存储红色画风险点。这样即使草图很粗糙评审时也能快速指出问题。4.4 第四步用代码生成正式图草图确认后用代码生成工具出正式图。以 PlantUML 为例下面是一个简化版的订单系统架构图代码startuml skinparam componentStyle rectangle actor 用户 as user component API 网关 as gateway component 订单服务 as order component 库存服务 as inventory queue 消息队列 as mq database 订单库 as orderDb database 库存库 as inventoryDb user -- gateway : HTTPS gateway -- order : 创建订单 order -- orderDb : 写入 order -- mq : 发送库存扣减消息 mq -- inventory : 异步消费 inventory -- inventoryDb : 扣减库存 note right of mq 削峰填谷 失败进入死信队列 end note enduml这段代码生成的图结构清晰箭头方向统一注释也到位。更重要的是它可以进 Git每次修改都有记录。4.5 第五步评审与迭代图不是画完就完了。评审时我会重点观察三件事有没有人问“这个箭头是什么意思”——说明视觉编码不清晰。有没有人问“这个服务为什么在这里”——说明分层有问题。有没有人问“如果这里挂了怎么办”——说明风险点没标出来。每次评审后更新图并在图下方记录变更。通常迭代两到三轮图就稳定了。5. 常见问题与排查技巧实录5.1 图太复杂读者看不懂怎么办这是最高频的问题。我的排查顺序是先看节点数量超过 15 个节点几乎肯定需要拆图。再看箭头数量箭头交叉超过 5 处说明布局有问题尝试调整节点位置或换布局方向。最后看颜色数量超过 5 种颜色读者会眼花。我的经验是主色不超过 3 种辅助色不超过 2 种。如果拆图后还是复杂说明你对信息的理解还不够透彻。这时候应该回到第一步重新做信息分层。5.2 不同角色对图的理解不一致这个问题通常是因为图里混用了不同抽象层次的概念。比如把“业务模块”和“部署单元”画在同一层。解决办法是按角色出图给产品的图只画业务模块给开发的图只画服务和技术栈给运维的图只画部署单元。如果必须在一张图里表达多个层次用分组框隔开。比如上半部分画业务架构下半部分画技术架构中间用一条虚线分开。5.3 图更新不及时文档过期这个问题的根源是图没有跟代码或文档一起管理。我的解决方案是用代码生成图跟代码仓库放在一起。在合并请求里强制检查图是否需要更新。图下方标注版本和日期过期图直接标记“已废弃”。我们团队曾经有一张图过期了半年没人发现后来在评审时被新同学指出非常尴尬。从那以后所有图都必须跟代码一起更新否则合并请求不通过。5.4 工具太多不知道选哪个下面这张表是我对不同场景的工具推荐场景推荐工具理由快速草图纸笔/白板零成本随时改文档嵌入PlantUML/Mermaid代码化可版本管理高保真汇报设计工具美观适合对外架构治理Structurizr模型驱动适合大型系统提示不要同时用太多工具。我见过一个团队同时用三种工具画图结果风格不统一维护成本极高。选一个主力工具其他场景用最轻量的方式补充。5.5 评审时没人看你的图如果评审时大家都在低头看手机说明你的图没有抓住他们的注意力。我的经验是图要放在文档最前面并且配一句话结论。比如“本方案通过消息队列解耦订单和库存预计降低高峰期超时率 80%”。这句话就是钩子读者会带着问题去看图。另外评审时不要从头讲到尾先讲结论再讲图。如果结论大家认可图只是佐证如果结论有争议图就是讨论的基础。6. 我踩过的坑和最后分享的几个技巧第一个坑是过度追求美观。早期我花大量时间调颜色、对齐、加阴影结果评审时被一句“这个服务为什么依赖那个”问住。后来我明白了图的美观度只要达到“不干扰理解”就行逻辑才是核心。第二个坑是图里塞了太多技术细节。比如把数据库字段、接口参数都画进去结果图变成了代码的图形化版本没人看。技术细节应该放在文档正文图只负责表达结构和关系。第三个坑是不写图例。我曾经画了一张图用了不同颜色的虚线表示不同含义但没写图例。评审时有人问“这条红色虚线是什么意思”我才发现只有我自己知道。从那以后任何非标准元素都必须有图例。最后分享几个实用技巧用灰度测试把图转成黑白如果还能看懂说明视觉编码不依赖颜色更可靠。用“三秒测试”给同事看三秒然后问他这张图讲了什么。如果他说不出来说明图需要简化。用“反向画图”从结果倒推先画最终状态再补中间过程。这样不容易漏掉关键节点。用“图配文”每张图下面配一段 100 字以内的说明讲清楚这张图回答什么问题。读者可以先看图再看文效率更高。这套 diagram-design 的方法我在多个项目里反复用过从单体架构到微服务拆分从内部评审到对外汇报基本都能覆盖。它不是银弹但能让你少走很多弯路。如果你现在手里正好有一张画了很久但没人看懂的图不妨按上面的步骤重新拆一遍大概率会有惊喜。