diagram-design 这个名字听起来略泛落到开发日常里其实就是一句话的事把脑子里的系统结构、调用关系、状态流转画成别人能看懂、能评审、能持续维护的图。这个能力是我这些年带项目做得最多、也最常被低估的事。很多人觉得画图是美工或者文档员的活但实际上真正能把一张架构图画到能指导开发、能支撑评审、能被团队当长期文档用的一定是懂系统的人自己。从最早在白板上随手画歪歪扭扭的箭头到后来用了一套相对固定的流程去设计、评审、维护图我在这件事上踩过的坑和攒下的经验都不少。这篇文章我就把我在 diagram-design 上的完整思路写出来包括设计前要想清楚什么、工具怎么选、怎么把图做得严谨又好看、怎么避免图越维护越乱。适合正在写系统设计文档的开发者也适合团队里负责组件库、基础平台、微服务治理的同学参考。内容不会只教你某款画图工具更多是解决“为什么我画的图总是乱、总是说不清楚”这个问题。1. 一张好图背后的设计本质不只是画出来更是想明白很多人画架构图的第一反应是找工具打开画板就开始拖方框拉箭头。我在刚入行那几年也这样后来发现一个扎心的事实如果脑子里的逻辑没理顺用什么工具画出来都是乱的。diagram-design 里真正难的不是“design 图”而是“design 那个系统”在脑海里的形状。1.1 一张图同时承担三个角色记忆、沟通、验证在一套系统的生命周期里图至少要扮演三种角色每个角色对图的要求各不相同。第一是记忆。一个半年没人动过的子系统有人问你“这边的数据到底怎么流转的”你第一反应一定是去翻图。这个场景下图要完整关键细节不能省丢了中间件、漏了超时机制看图的人会被误导。第二是沟通。方案评审会上你画一张图给前后端、算法、运维的同学看目的是让所有人对系统的处理流程达成一致。这个场景下图要克制不能把日志框架都画进去否则核心链路反而被淹没了。第三是验证。写代码前把边界画清楚标出依赖关系、数据流向、异常分支其实是在纸面上预演一遍系统。很多设计缺陷在画图的阶段就能发现等代码写完再改成本翻倍。明白一张图同时承载这三个角色之后很多纠结就迎刃而解了。比如“这个要不要画上去”“这个连线要不要标方向”“这块要不要放那么大的空间”本质问题都是你现在是服务于记忆、沟通还是验证同一张图往往无法同时满足三个角色所以成熟的 diagram-design 会把一张“大图”刻意拆成多张“小图”分别负责不同的使命。1.2 从白板涂鸦到规范流程我是怎么慢慢演进过来的我最早给项目画图就是开会时在白板上随手涂。白板涂鸦的好处是即时、随意坏处也很明显画的人爽了拍照的人以为自己懂了真正对着照片写代码的时候才发现箭头指向根本对不上。后来开始用绘图工具做正式的设计图又走入另一个极端画得太细。一个只有两个服务的内部系统硬是画出了二十几个模块框连线还带十几条箭头。结果方案评审会上没人关心核心链路全在问“这个框是什么”“这条线为什么连过来”沟通效率反而比不画更差。真正让我的 diagram-design 能力上台阶的是学会了两件事。第一先写下文字再画图第二把图当代码一样评审与维护。前者保证了内容完整后者保证了长期可用。后面几节我会把这两条经验展开成具体的操作步骤直接把能复用的流程给到你。2. 动手画图前必须想清楚的问题清单开始画图之前有四个问题没想清画出来的图大概率要推倒重来。这些问题听起来很基础但实操中大部分乱图病根都在这。2.1 第一性原理这张图给谁看为什么现在要看这一条怎么强调不过分。给团队新人看的图重点是全貌和概念细节太多他会懵给技术专家评审看的图重点是边界和机制他需要看到异常分支给管理层汇报看的图重点是成本、风险和依赖关系他不在乎消息队列里是否走的是 JSON 序列化。我曾经有一个惨痛教训给业务方汇报技术方案我画了一张业务侧完全不需要的“注册中心选型对比图”里面塞满了节点同步、心跳探测之类的细节。汇报结束后对方只记住了一件事系统里有两个全新的基础组件稳定性风险未知。那次汇报的方向彻底跑偏了。所以我现在给自己定了一个规矩画之前先在一张便签上写下这张图的读者是谁、他看完之后应该做出什么判断或掌握什么信息。写着写着哪些该画、哪些不该画基本自动浮现了。2.2 视角选择结构视角、流程视角、状态视角不能在一张图里混着画很多图看起来像一锅粥是因为忘了视角统一。视角一般分三类。结构视角表达的是“系统里有什么”比如模块划分、部署拓扑、组件依赖。这种图的重点在边界和层级连线往往是“依赖”或“包含”。流程视角表达的是“事情是怎么一步步发生的”比如请求处理链路、订单状态流转、用户登录过程。这种图的重点在顺序和分支箭头带方向数据会越来越清晰。状态视角表达的是“某个对象在不同条件下如何变化”比如订单从创建到关闭有哪些状态、什么动作触发迁移。这种图通常会带条件判断常见的 UML 状态图就是这类。三种视角不是不能出现在同一份文档里而是不要挤进同一张图。我见过最乱的一张图既想表达微服务拓扑又想画一次下单的时序流程还想标出订单状态机。最后的结果是画的人累死看的人脑子炸掉。2.3 信息粒度分三档概览、逻辑、细节你可以用多图组合我不太相信“一张图搞定一个系统”这回事尤其是复杂系统。更实际的做法是按信息粒度把图拆成三档。第一档是概览图用户侧、网关、核心服务、存储、第三方依赖整体不超过十个节点。用来交代系统长什么样。第二档是逻辑图某一跳的链路展开比如“下单”这个用例涉及的模块、服务之间的调用顺序、数据读写的位置。用来给开发讲明白业务逻辑。第三档是细节图某个类、某个表、某个部署单元的具体设计比如某个核心实体在不同状态下的流转规则。用来指导编码。三档图组合起来既能回答“系统是什么”又能回答“某条链路怎么跑”还能回答“某个点怎么落地”。每次画图前的目标其实就是确认当前这张图属于哪一档别让一张概览图硬生生长出细节图的负担。3. 文本派还是拖拽派工具选型背后的真实逻辑diagram-design 领域绕不开一个选择题用基于文本描述的工具还是用可视化拖拽的工具。这两派各有拥趸我谈谈自己的真实经历和最终选择。3.1 三种主流工具的差异化能力对比我把这三类工具的差异拆开来看不仅仅是“命令行友好”和“所见即所得”这么简单。基于文本的制图工具第一类用代码或者记号描述画图对象和关系。优势是改起来非常精准搜索定位方便和代码一样可以做 diff、走评审、存仓库。劣势是上手有学习成本排版微调要靠参数新手容易对着代码猜最终长什么样。基于 Markdown 生态的可视化语言第二类属于第一类的变种但更轻量直接嵌在文档里用适合快速画流程图和时序图。功能没那么全复杂系统图会显得吃力。拖拽式绘图工具第三类优点是即时反馈排版自由度高画出来的图容易做到非常美观。缺点是变更很难追踪多人协作时容易各改各的时间一长图就失去了可信度。我用一张表来总结方便你根据团队情况做判断维度文本描述类轻量文档内嵌类可视化拖拽类上手速度中等需要记语法快代码量小极快零基础可维护性强可 diff 可评审强随文档走弱历史版本难追复杂排版能力较弱需调参数有限很强自由适合场景系统评审长期维护单页文档说明一次性演示涂鸦3.2 我选工具的一个核心原则看维护频率而非初次体验工具没有绝对的好坏选型的标准应该回归到这张图会被维护多少次。如果一张图是给某个一次性分享准备的画完就扔那么用拖拽式工具最合适画得快且好看比如一次性的系统演示、课程截图。我自己的博客图就经常用这类工具做。如果是系统架构图、方案设计图这种“要活很长时间”的图也就是一年两年内会被反复修改、评审、对接的那我会坚定地选文本描述类。原因特别直白当图被修改二十次之后拖拽工具里的那二十个历史版本可能早已散落在各个群聊的截图里但文本文件还能躺在仓库里任何一次修改都有记录谁改的、为什么改清清楚楚。对团队协作、历史追踪、变更评审这些图的长期健康至关重要。维护一次就难受一次拖拽图很难在一年后还有人愿意去动它。所以我的组合通常是长期架构图用文本描述类一次性讲解图用拖拽式取长补短。3.3 一个可以直接改的文本制图示例从需求到两张关键图空说理论不如看例子。我用一个非常常见的“外部对接场景”来演示比如一个后端服务需要接收上游平台的支付回调更新订单状态再通知业务方。按照前面的流程先写文字再画图。文字化需求大概是这样平台发起回调网关验签业务服务处理更新订单状态生产消息通知服务推送遇到失败进入重试队列重试超过三次进入人工处理。然后我用文本描述工具画出第一张时序图重点是看清调用顺序和关键反馈startuml actor 上游平台 participant API网关 as GW participant 交易服务 as TS database 订单数据库 as DB queue 重试队列 as MQ 上游平台 - GW: 支付结果通知 GW - GW: 验签与幂等校验 alt 验签失败 GW -- 上游平台: 拒绝并返回错误码 end GW - TS: 转发通知内容 TS - DB: 更新订单支付状态 DB -- TS: 更新结果 alt 更新成功 TS - MQ: 发送支付成功事件 TS -- 上游平台: 返回SUCCESS else 更新失败 TS - MQ: 发送重试消息 TS -- 上游平台: 返回PENDING end enduml这版代码出来之后时序关系是明确的谁在什么时候触发了谁正常分支和失败分支都画到了。第一次给团队看的时候有人提出“重试消息如果也失败怎么办”于是我在下一版补上了失败计数、延时重试、超过 N 次进入人工补偿队列这些分支这比写完代码再补逻辑清晰得多。再画一张组件拓扑图表达系统的依赖结构给部署接入的同学看startuml node 外部平台 as external node API网关 as gateway node 交易服务 as trade node 通知服务 as notify database 订单库 as db queue 消息队列 as mq node 补偿任务 as job external -down- gateway: HTTPS gateway -down- trade: 验签后转发 trade -down- db: 读写订单 trade -down- mq: 事件推送 mq -down- notify: 消费事件 notify -down- external: 结果通知 job -right- db: 扫描超时订单 job -right- mq: 重新生产消息 enduml两张图画完设计阶段的核心信息就都齐了。第一张图给研发讲逻辑第二张图给运维和设备部署讲结构。分开之后看的人不用在一张图里忍受不同维度信息的互相干扰。4. 让图既严谨又好看布局、配色、渲染格式的细节清单很多技术同学画图能力不错但图出来就是不好看或者说不专业。我自己复盘下来和审美天赋关系不大主要是缺少一套可执行的视觉检查清单。4.1 布局第一原则连线尽量少交叉主要链路要走直线绘图工具自动排版时节点一多连线交叉就不可避免。交叉太多看图的人需要不断顺着线找下一个节点大脑负担会快速飙升。我自己的布局经验有三条。第一把主链路的节点排成一条纵向或横向的直线让最核心的流程一眼贯通。第二辅助节点放侧边用虚线或者浅色连接让视觉层次立刻分出来。第三适当增加空白节点之间不要贴得太近留白不够图会显得很窒息。以我上面的组件拓扑图为例主链路是外部平台到网关到交易服务到数据库这条线刚好可以排成直列其他依赖放两边。这种布局看起来是后期调的但其实是最自然的阅读顺序。4.2 颜色控制在四种以内图标是点缀不是主角颜色是最容易暴露不专业的地方。我见过一张架构图用了十几种颜色每个框一个色结果读者首先被颜色吸引而不是被结构吸引反而增加了认知负荷。我的建议是主结构用一种颜色核心模块用另一种颜色突出异常或外部依赖用第三种颜色留一个颜色给关键警示。整个画面的颜色控制在这个范围内基本不会显得花。图标也是一样的逻辑。语雀和各类模板都提供了大量图标库但图标画多了图会变得非常拥挤而且图标的叙事语义很难在全团队形成一致。今天这个人画个数据库图标明天那个人在同一个库里换了个云数据库图标长期维护时歧义就出现了。我现在的做法是能不用图标就不用用形状加文字颜色表达层级箭头表达关系这样最稳重。4.3 导出图片格式的讲究矢量图和截图完全是两种用途很多团队喜欢把图导出成截图丢进文档短时间看问题不大但图一放大就糊了想改就得回到原文件去重新导出。我建议对外分享或写正式文档时尽量导出矢量格式比如 SVG。矢量图在任意尺寸下都清晰贴在文档里按需放大缩小体验完全不同。另外注意导出的命名和版本。我习惯给文件名加上主题和日期例如“支付链路-时序图-20240801.svg”这样存放多年之后也剩下一堆意义不明的“最终版最终版2”至少我还能知道这张图对应的是哪个版本的设计。这不属于技法但属于长期维护体验里特别重要的一环。5. 高频翻车现场与排查速查表从三个典型场景说避坑再充分的规划实操中还是会有各种意外。我归纳了 diagram-design 里最常踩的三个坑每个坑都给到可落地的排查方案。5.1 场景一图越维护越乱最终没人敢改这是长期维护型图纸最怕的问题。原因往往是编辑工具分散、多人分别维护导致内容漂移。你添一个节点我改一个箭头时间一长图和代码就慢慢对不上了最后谁都不敢动。解决方案是把图文件收口到仓库里和代码一起走变更流程。任何图变更都要和代码变更一样发起评审合并到主分支后团队所有人只能基于仓库里的版本来更新。这一点执行下来符号才是真正的产品。如果你现在维护的图还在各自的本地文件里或者聊天工具中我强烈建议尽早把图的源文件都收到一个大家都认可的位置统一管理。5.2 场景二核心链路被次要逻辑淹没这个坑常发生在“想画全”的心理上。画图的人担心漏掉信息被挑战于是各种配置、备份、健康检查模块全画上还把主链路和旁路逻辑画成一样粗的黑线。遇到这种情况我推荐“两遍画法”第一遍先画出所有想画的元素先保证内容完整第二遍开始做减法把主线相关的节点用粗实线连接把旁路逻辑改成浅色虚线甚至直接拆到另一张图去。不要怕拆图文档中多放几张分工明确的图永远比一张塞满的巨图更容易读懂。5.3 场景三图做得很漂亮但经不起“什么条件下”的追问美观不等于严谨。很多图把正常流程画得清清楚楚但一问“失败怎么办”“并发怎么办”“延时会怎样”就答不上来了。这在方案评审阶段特别致命。我的习惯是把“异常分支”作为绘图的一项必填信息。每一层调用旁边至少标出一个失败出口。对关键操作我会在边上用注释说明失败之后的补偿策略。这种图刚画出来时不如纯主干图好看但它的价值在评审时就能体现追问越少说明设计越扎实。6. 团队协同里的 diagram-design 治理实践当图不再是个人的笔记而是团队的基础设施时光会画还不够还需要一套协作上的规矩。6.1 把图变成评审对象而不是口头解说对象不少团队评审时画图只是为了辅助讲说图本身不承担评审结论。我建议反过来先评审图再讨论实现。因为图的抽象层级高一次讨论能覆盖大量后续开发细节图过不了关就急着写代码等于用一个未定稿的蓝图去指导施工。具体操作上评审前把文本格式的图文件附在议题箱里评审时先指着图过一遍关键链路请所有人先看图有什么问题再进入代码实现的技术细节。这个动作看似正规化其实节省了不少往复时间。6.2 为团队沉淀一张“图例和样式规范”当多人协作维护同一套图时一定要有一份团队内的“图例”约定。比如方框代表服务、圆柱代表存储、箭头代表调用、虚线代表异步或事件。否则每个人画图风格不一A 用圆柱代表消息队列B 用圆柱代表缓存图一合并就混乱了。我们团队的做法是在文档库中维护一份简短的绘图规范只有半页到一页包含常见的图例定义、颜色含义和文件命名规则。新成员来了一天就能掌握老成员也不会随意发挥。这套规范是 diagram-design 从个人能力变成团队能力的关键一步。6.3 图不是一次性产物它值得拥有“持续维护预算”最后说一个和钱相关的经验图这种资产会随着系统演进持续消耗维护时间。很多团队只给图和文档留创建时间不留维护预算只要求做到代码上的及时图往往是“有时间再补”。结果是系统演进一年后图彻底失效成为一堆摆设。我的看法是只要是核心链路的架构图都要在迭代计划里留出“刷新图表”这一步不用很长半小时到一小时即可但必须有专门安排。否则能力再强、图画得再好也都只存在于入职那一天。我个人在做 diagram-design 时最大的体会是它是一项被极大低估的设计能力一次完整的架构图设计过程相当于提前在纸面上完成了一次架构评审和一轮逻辑推演。真正上手去画过复杂链路、去回答过各种异常追问、去维持过半年以上的图纸可靠性之后你就会发现画图的收益远不止“文档好看”这么简单。它帮你避开“写完代码才发现设计有洞”的致命反转也让后来接手的人不再靠读代码来考古。最后还是那句话从写下你系统里的第一个调用关系开始把画图当作设计的一部分而不是事后的整理。这个习惯越早养成你的项目后期就越省心。