第一次接触 diagram-design 这个名字是在一次系统改造项目的设计评审会上。当时我们团队花了一周画的架构图在评审现场被问得哑口无言这张图的主链路在哪数据库和缓存的关系为什么用两种线型日志链路为什么画在主流程中间那一次之后我开始认真思考一件事画图这件事到底缺的是工具还是缺了一套设计方法。diagram-design 这个词后来在我这里就变成了一套很具体的实践从信息分层、视觉规范到工具落地把一张图当成一个需要设计、评审、维护的产品来做。这篇文章想分享的就是这套方法怎么从零开始建立以及实际项目中我会怎么操作。适合所有需要画架构图、流程图、部署图、时序图的人尤其适合文档写了没人看、图画了没人懂、一改需求整张图推倒重来的团队。1. 为什么需要 diagram-design先搞清楚画图难在哪1.1 画图不是艺术创作而是工程表达很多人画图第一步是打开工具第二步是拖框连线第三步就陷入了调整箭头样式的泥潭。我见过最夸张的案例一张架构图上用了 8 种颜色、6 种线型、13 个没有任何图例的图标画的人说“每一处细节我都考虑过”看的人只感受到一团信息爆炸。问题不在工具而在于画图的人把图当成“个人表达”没有把图当成“工程文档”。一张合格的技术图本质上是一份压缩过的设计文档。它必须有清晰的主链路、明确的边界、一致的符号体系、可追溯的版本。代码有 lint、有 code review图为什么不能有diagram-design 想解决的就是这个“图也需要被设计和管理”的问题。我刚入行那会儿也犯过同样的毛病。画一张流程图恨不得把所有异常分支、所有重试策略、所有日志输出全部塞进去结果就是主流程细得像毛细血管评审时每个人都在问“这一条线是什么意思”而不是讨论方案本身。后来我学乖了先画一张只有核心节点的图给评审看确认结构没问题再补细节。这个转变带来的效率提升非常直接。1.2 diagram-design 的四个关键词我给 diagram-design 归纳了四个关键词结构、一致性、可读性、可维护性。这四个词不是口号而是我在实践中反复撞墙之后总结出来的每一个都对应着一个具体的失败场景。结构说的是“图里必须先有骨架”。用户请求从哪进、数据从哪出、依赖关系朝哪个方向这些在动手前就要定下来而不是画到一半再临时决定。我见过太多图画着画着突然发现少了一个模块然后硬塞在角落连线绕了大半个图。结构一旦乱了后续所有调整都会很难受。一致性说的是“同一个概念必须用同一种画法”。同一张图、同一个项目的一组图里服务调用永远是实线箭头异步消息永远是虚线箭头不能今天用红色代表告警、明天用红色代表核心链路。这里我踩过的坑非常具体有一段时间我负责的文档里红色一会儿表示“外部依赖”一会儿表示“故障节点”后来新同事接手时反复问为什么这里的红色和另一张图不一样我只能承认图表之间没有达成一致的约定。可读性说的是“信息密度必须控制”。一张图如果需要在评审现场逐块解释才能看懂那它的信息组织已经失败了。好的图应该让读者在 30 秒内说出主链路2 分钟内定位到他想看的部分。我自己判断可读性的标准很简单找一个完全没参与这个方案的人看图让他讲一遍主链路和几个关键节点。如果他能讲清楚说明图合格如果他开始猜说明图在表达上失败了。可维护性是最容易被忽视的也是长期价值最高的。图一定要能低成本修改否则一改需求就没人愿意维护它。文本化绘图、模块化拆分、图层规范都是为了让图能跟着代码一起演进。否则一张图在交付那天就是它的巅峰状态之后每一次需求变更都是毁灭性的打击。1.3 谁适合参考这套思路diagram-design 不是某一个岗位的专用技能。做架构设计的人需要用它画架构图做业务流程梳理的人需要用流程图讲清楚现状和改造点做运维的人需要用它画部署拓扑写技术文档的人需要为每一篇复杂的文档配一张足够清晰的示意图。哪怕你是做数据分析的把指标联动关系画成一张关系图也比堆一屏表格更容易让业务方点头。如果你所在的团队正在经历“图越画越多、但每一张都画得不痛不痒”的阶段这套方法可以直接拿来做一次内部规范。哪怕只统一了“主链路必须用粗实线、所有颜色必须有图例”这两条图的整体质量都会立刻上一个台阶。我推动过几次类似的规范化最明显的收益不是图变好看了而是评审会议变短了——因为大家不再纠结看图而是直接讨论方案。2. 图表类型选型画对图比画好图更重要2.1 先别动手先回答“这张图要支撑什么决策”我每次画图前会先问自己三个问题这张图的读者是谁是开发、测试、运维还是业务方读者看完图之后需要做什么决策是评审方案、排查故障还是确认流程这张图要放进什么文档里是架构说明、上线方案还是事后复盘这三个问题的答案决定了图的类型。实际上很多翻车图不是因为画得差而是因为类型选错了。想表达调用关系却画成流程图想说明部署拓扑却画成时序图读者自然看不明白。我见过最典型的一个例子有人要说明“用户登录之后系统做了哪些事”结果画了一张架构图把前端、网关、用户中心、数据库全部框出来再用箭头连一遍。架构图确实表达了模块间关系但用户要看到的“先校验、再签发令牌、最后初始化会话”这个顺序完全被模块的物理位置淹没了。这就是类型选错的代价。2.2 六类高频场景和对应的图表类型我在实际工作中会高频用到六类图这里整理成一张对照表可以直接拿去做选题参考。确认了类型后续所有设计动作才有针对性。场景推荐图表类型表达的核心信息常见误用系统模块与依赖关系架构图分层/模块系统包含哪些部分、部分之间怎么调用把架构图画成流程图框与框之间既画调用线又画流程箭头业务处理过程流程图活动图操作先后顺序、分支条件、结束点在流程图中加入大量系统模块框图被切成两半请求处理顺序时序图调用方、被调用方、消息先后顺序用流程图代替时序图只表达“先A后B”丢了交互的归属关系服务器/网络部署部署拓扑图物理或逻辑节点、网络区域、端口关系把所有事情堆进一张图内网和公网划分不清数据模型关系ER图/关系图实体、属性、关联基数为了“好看”把关系线画成曲线读起来反而费力方案对比/头脑风暴草图/思维导图观点分组、演进路径把讨论草图画成最终文档图后面没人维护这张表我自己打印过一份贴在显示器边上。每次要画图时先对着表确定类型再决定怎么布局、怎么配色。特别是团队新人给他们这张表能避免很多无效劳动。2.3 一图一主题信息密度失控的临界点我在团队里定过一条硬规则一张图只讲一个主题。这不是教条而是信息密度控制的需要。人的短期工作记忆大概只能同时处理 5 到 9 个信息块一张架构图超过 20 个核心节点、两条以上并列主链路读者的注意力必然开始碎片化。我见过最夸张的一张图是某个系统的“全链路大图”把几十个微服务、中间件、数据存储全部画在一张巨型画布上。打印出来之后字小到要拿放大镜才能看清。那张图的作者自己也承认除了他自己没有人能完整看完。如果内容确实很多正确做法是拆分。比如画一个交易系统可以先画一张“整体模块图”表现支付、订单、库存三个模块的依赖再单独画一张“订单下单时序图”把调用细节放进去最后画一张“部署拓扑图”说明多环境部署关系。三张图各司其职看起来不会累维护的时候也可以单独改某一张。刚开始拆分的时候可能会觉得麻烦但实际做完会发现一张小图 20 分钟就能更新完而一张大杂烩图每次改都像做一次手术。两相对比拆分的价值立刻体现。2.4 类型选错的翻车现场分享一个真实踩过的坑。有一年我们做容量评估有同事直接把业务流程图当作架构图拿去评审。流程图的主线是“用户下单→库存扣减→通知发货”但架构图要表达的是“订单服务、库存服务、消息服务之间的依赖与数据流向”。两者混在一张图里的结果就是评审时业务线的人看流程技术线的人找模块两边指着图上的同一个框说完全不同的意思一个小时的评审什么都没定下来。自那之后我们在画图前会先写一句“图题加一句话说明”比如“订单模块依赖关系图用于评估服务拆分方案”。写不出来这句话就说明自己还没想清楚要画什么这比工具技巧重要得多。还有一个相似场景是时序图画成了调用清单。有人画时序图时把每个方法名、每个参数都写在消息线上图和代码文档几乎没有区别。时序图的价值在于“交互顺序和归属关系”而不是帮你记忆方法签名。把这些细节塞进去反而会让人忽略真正的交互逻辑。3. 画图前必须定好的三件事信息分层、视觉规范、布局节奏3.1 信息分层让读者第一眼看到主链路diagram-design 里最核心的一个动作是“分层”。一张图至少要有三个层次主信息、辅助信息、装饰信息。主信息是第一眼必须看到的东西通常就是主链路或主结构。它应该占据图的视觉中心、使用最高对比度的颜色、最粗的线宽。辅助信息是分支流程、数据流向、异常路径它们要有但不能抢主链路的风头。装饰信息是最容易滥用的部分比如圆角、阴影、渐变。这些一旦越过界限就会把所有信息拉回同一条视觉起跑线读者的眼睛不知道往哪放。实操上我会分四步走先用文本框把图里的核心元素按“主体、依赖、外部系统”三类摆出来不做任何美化再用连线把主链路连出来确认主线路径是否顺畅然后给辅助信息分组能用子图或泳道收拢就收拢不会散得到处都是最后才加颜色、线型、图标和边框。工具给的美化能力越强越容易让人在还没想清楚结构时就开始调样式。很多人画图慢就是因为把美化提前了。我在团队里经常说一句话如果你发现自己开始调圆角半径而主链路还没连完说明流程走错了。3.2 视觉规范颜色是信息不是装饰颜色是图上最容易失控的元素。我见过一张架构图出现 12 种颜色问设计者每个颜色什么意思他说“我觉得区分一下好看”。这一句话就暴露出问题颜色没有承担信息。我在团队里推过一套最小可用配色规范主链路深蓝或深灰唯一的高饱和色辅助链路浅灰或浅蓝不干扰视觉焦点告警/风险红色只在真的表示“异常”时使用外部系统浅橙或浅黄用于和内部模块区分中性底色白、浅灰、深灰用于背景和容器边界。这套规范最大的特点就是克制。颜色总数不超过五种高饱和色只有一种所有读者都会默认把最深最亮的元素当作核心这样主链路不需要额外加粗也能被快速识别。我现在画图前会先建一套色板把颜色提前定义好再开始画而不是画到一半的时候突然想“这里要不要换个颜色试试”。同时要避免一个坑用颜色区分含义时必须有图例。即使团队约定过颜色含义看图的未必是团队内部的人。一套图里所有颜色都必须在右下角或底部用图例固定下来这才算一个完整的设计闭环。3.3 布局与对齐让图经得起放大缩小布局方面我的经验是“方向统一网格对齐间距成体系”。方向统一指主流程方向要一致要么从左到右要么从上到下不要一张图里既有横向又有纵向读者很难顺着视线走。网格对齐指所有框体尽量贴着同一套栅格排布间距不要出现 5 像素、10 像素、15 像素混用的情况。间距成体系指边距至少分成三个档位模块内间距、模块间间距、整图留白每个档位在整张图里保持一致。图标和字体也要纳入布局考虑。图标尺寸建议同一张图里不超过两种文字字号建议标题、核心节点、辅助说明分别固定为三个档位而不是随手调大调小。把这些约束做成一个模板文件每次画图直接基于模板开始能省掉大量重复的对齐与调样式时间。我自己的做法是在绘图工具里保存一个“空白规范模板”里面提前定义好字体、字号、颜色、箭头样式和常用的几个容器形状。每次开新图都从这个模板开始而不是从头拖一个新的空白画布。这个习惯坚持了一年画图速度提升非常明显。3.4 命名、图例与版本管理图设计得再好如果文件名叫 diagram-v2-final-new.drawio那和没维护有什么区别。命名我会按“序号-类型-主题-日期”的格式来比如 03-architecture-order-module-20250612。同一套图放在同一个目录里目录内放一个 README标清楚每张图对应文档里的哪个章节。版本管理方面如果团队用 git直接把绘图源文件放进去不要只提交导出后的 png。否则下一次修改就是重画一张图。用文本化绘图天然适合 git因为 diff 出来就是文字变化review 起来一目了然。这个习惯一旦养成图的可维护性会提高特别多。我在一个项目里踩过这样的坑文档里引用的架构图已经更新到第三版但仓库里只存着第一版导出的 png。后来要紧急查一个节点关系老图片上的信息完全对不上只能翻聊天记录去找谁改了图。那次之后我把“源文件必须进仓库”写进了团队规范再也没出过类似问题。4. 实操把 diagram-design 落地成一个可复用的图表工程4.1 工具选型别纠结三种方案对应三种需求工具只是承载设计的容器。我实际用下来会按三种需求选工具而不是盲从“某某工具最强大”的说法。需求推荐工具/路线理由要画复杂的架构图、部署图需要精细排版桌面绘图工具如 draw.io / diagrams 类拖拽自由、模板丰富、支持分层与图层适合正式文档图要进 git、要审 diff、要能脚本生成文本绘图如 PlantUML / Graphviz源码即图形改一行文字就是改一张图review 成本低讨论期、方案对比、快速表达想法手绘板/白板类工具如 Excalidraw手绘风格降低评审压力大家愿意在上面圈改不要盲目追求“一个工具画所有图”。再好的工具如果只适合你自己用、团队其他人用不起来最后图还是会在文档里变成一张无人维护的静态图片。我见过很多团队买了很贵的绘图软件授权结果只有一个人在用其他人全部用白板加手机拍照。工具选型要跟着团队的协作方式走而不是跟着个人偏好走。4.2 实操作业一用文本方式绘制一张系统架构图文本绘图最大的价值是可 review、可版本化。我用 PlantUML 画一张简单的订单服务架构图给你看完整流程。startuml !theme plain skinparam componentStyle rectangle skinparam defaultFontSize 14 component 客户端 as client component API网关 as gateway component 订单服务 as order component 库存服务 as stock component 消息队列 as mq database 订单数据库 as db_order database 库存数据库 as db_stock client -- gateway gateway -- order order -- stock : HTTP调用 order -- mq : 发送事件 order -- db_order : 读写 stock -- db_stock : 读写 enduml代码写完之后直接渲染就可以得到一张带组件容器和箭头的架构图。这里有个关键技巧所有关系只用箭头方向表达不要使用双向箭头。双向箭头在视觉上容易让人误以为是一条线而不是两种调用后期维护的时候也不方便定位“谁依赖谁”。单向箭头强制你在写代码时想清楚依赖方向这一点对架构评审特别有用。如果要用 Graphviz 也可以dot 语法写起来更接近“描述节点和边”的思维方式。digraph G { rankdirLR; client [label客户端, shapebox]; gateway [labelAPI网关, shapebox]; order [label订单服务, shapebox]; stock [label库存服务, shapebox]; mq [label消息队列, shapebox]; db_order [label订单数据库, shapecylinder]; db_stock [label库存数据库, shapecylinder]; client - gateway; gateway - order; order - stock; order - mq; order - db_order; stock - db_stock; }这种文本方案的优点是每一行都是一个独立的信息单位团队 review 时可以逐行确认逻辑缺点是精细排版能力有限容易在复杂场景下出现布局错乱。所以我的建议是正式对外的高保真架构图用桌面绘图工具内部协作和演进记录用文本绘图两者各司其职不冲突。4.3 实操作业二用绘图工具完成一张部署拓扑图假设现在要画一个“应用服务器到数据库”的部署拓扑图用桌面绘图工具的操作路径我会这样走。第一步先拉一个整图背景容器代表“生产环境”内部再拉两个子容器接入层和数据层。第二步在接入层放负载均衡和应用服务器节点在数据层放主库和从库节点。第三步连线负载均衡连应用服务器应用服务器连主库主库连从库表示主从复制。第四步给线加上端口标注比如 8080、3306端口标注用最浅的灰色避免抢视觉。第五步导出。导出时我一般导出 SVG 而不是 PNG保证文档放大后依然清晰。还有一个很容易忽略的细节节点之间的连线不要穿过别的节点。桌面绘图工具里线是半自动的一旦布局动过线就很容易变成“绕柱飞行”看起来非常乱。我的习惯是先把所有节点按网格摆好再统一连线最后再调布局而不是每加一个节点就连一条线、挪一次布局。步骤的前后顺序直接影响画图效率这个顺序我用了很多年实测比边画边调布局的方式快不少。4.4 从草稿到终稿的迭代步骤完整走一遍 diagram-design 的流程我总结了六个步骤适用于大多数图表的创作和维护白板草图用最简单的框和线把主链路画出来忽略美观。元素清单把图里的每个元素列成一个清单检查有没有重复、有没有缺失。定主链路确认从起点到终点的主线路径删除和主线无关的装饰。工具实现按“先结构、再连线、后美化”的顺序落地。评审修改找一位不了解这个方案的同事看他能不能 30 秒讲出主链路。归档源文件渲染图、源文件、图例说明一起归档方便后续修改。第六步最容易被省略但恰恰是维护成本的大头。一个小团队只要坚持六个月图库就会从一堆死图片变成一套活的文档资产。我现在维护的很多图改一次需求只需要十几分钟因为源文件、命名规范、版本历史都是齐全的改动就像改代码一样有迹可循。5. 常见问题与排查技巧实录5.1 图越画越乱三个信号判断“这张图废了”第一个信号主链路需要用鼠标指给同事看才能找到。如果读者看第一眼找不到主链路说明信息层级已经失衡。第二个信号颜色或线型超过三种但没有图例。没有图例的颜色体系对读者来说是纯粹的噪音。第三个信号改需求时需要同时移动超过六个框体才能保持图正确。这说明模块化拆分已经失败了。出现任何一个信号我的建议都不是“继续修图”而是重画。重画不是推倒重来而是基于刚刚走过的信息分层流程重新组织。大多数情况下重画只需要原时间的三分之一因为素材已经齐了只是重新摆放和整理而已。我对团队说过一句话“继续修一张坏图和重新画一张好图前者往往是更慢的。”5.2 别人看不懂我的图先查信息层级如果评审时大家反复问“这个框是什么”“这条线什么关系”先不要怪读者回头检查三件事有没有一句话说明这张图的主题主链路是否比辅助信息更粗、更显眼每个符号和颜色是否都有图例这三条检查完大部分读图问题都能解决。剩下少数情况是图本身没有逻辑漏洞只是读者背景差异大那就需要给图配一小段文字说明而不是调整图形的视觉效果。有时候问题不是图不清晰而是业务上下文没交代清楚加一句“这张图画的是下单高峰期的降级方案”就完全不一样了。5.3 团队协作里图表冲突源头往往在图没有进版本库多人协作修改一张图最怕的是你改完导出 A 版本同事改完导出 B 版本两个人对照着看才发现差分不清。解决方法是让图进入和代码一样的版本管理流程。文本绘图直接走 git桌面绘图工具保存为 xml 或 svg 源文件进 git再配好渲染工具review 时看渲染图。不要用网盘来回传最终版这样只会制造混乱。我经历过一次线上事故排查发现文档里的拓扑图和实际部署结构差了一个节点。查下来发现是有人改了图之后没有同步到文档直接发了新版图片给别人。如果当时源文件在 git 里有记录这个差异在提交时就会被 review 拦截根本不会流到线上。5.4 高频问题速查表这里整理一份很实用的速查表遇到问题先对着找答案可以省下大量返工时间。症状可能原因处理方式图看起来密密麻麻信息密度过高拆分图表一张图只讲一个主题读者总问“这条线是什么意思”线型/颜色无图例增加图例统一符号体系一改需求就要重画半小时没有模块化分组用子图/泳道/分组把元素拆成独立模块图和文档正文对不上源文件未归档建立“图源文件渲染图”双归档复盘时找不到历史图文件命名混乱按“序号-类型-主题-日期”命名这五条基本覆盖了我和团队两三年里踩过的大部分坑。把它们贴在手边当 checklist每次画图前扫一眼能规避掉很多低级的返工。我自己现在画图之前都会快速过一遍这些点已经形成条件反射了。我自己在这套东西上最大的体会是diagram-design 不是一个工具也不是一套模板而是一种把“画图”从手艺变成工程的习惯。刚入门的人不妨先做两件事一是把接下来要画的五张图都按“先结构、再连线、后美化”的顺序来一遍二是给每张图配一句图题和一个图例。这两条动作看起来很小但坚持三个月后你再回头看以前画的图大概会和我当年一样一边觉得以前画得真不行一边庆幸还好没有一直那样画下去。如果你手里正好有张画到一半就乱掉的图别急着继续先退回去把那句话说明写清楚。写不清楚就说明还没画明白。