1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次听到“diagram-design”这个词很多人会下意识觉得它只是“画图”的另一种说法。但真正在项目里被图表折磨过的人都知道画一张图不难难的是让这张图在三个月后还能被自己看懂让同事看一眼就明白数据怎么流、状态怎么变、模块怎么拆。diagram-design 要处理的恰恰是“画图”背后那套更麻烦的事图的语义结构、视觉规范、复用机制以及它和代码、文档之间的同步关系。我最早接触这个概念是在一个内部工具重构的项目里。当时团队有五个人每个人画架构图的习惯都不一样有人用圆角矩形表示服务有人用直角矩形有人把数据库画成圆柱有人画成方块箭头方向更是随心所欲实线、虚线、带箭头、不带箭头混着来。结果就是同一套系统五张图讲出五个故事。后来我们花了两周时间才把图表的“设计语言”统一下来。diagram-design 这个方向本质上就是把这套统一过程产品化、规范化让图表从“个人表达”变成“团队资产”。它适合谁如果你只是偶尔画一张流程图发群里可能用不上这么重的思路。但如果你在维护一个持续迭代的系统需要反复向不同角色解释同一套逻辑或者你正在做技术文档、产品说明、教学材料那 diagram-design 的很多思路会帮你省下大量返工时间。它不挑工具Visio、Draw.io、Excalidraw、Mermaid、PlantUML 都能用核心在于你如何定义图的“语法”和“词汇表”。提示不要把 diagram-design 理解成某个具体软件的功能它更像是一套约束规则。工具会换规则可以迁移。2. 图表设计的核心思路拆解为什么先定规则再动手2.1 从“画什么”到“怎么画”的思维转变大多数人画图的过程是打开工具拖一个框写几个字连几条线觉得差不多就导出。这种“边想边画”的方式在临时沟通里没问题但一旦图要进入文档、要评审、要迭代问题就暴露了。diagram-design 的第一个核心思路是把顺序倒过来先定义“什么形状代表什么含义”再定义“什么关系用什么线”最后才去填充具体内容。这就像盖房子先定图纸规范而不是让每个工人凭感觉砌墙。我习惯把图表设计分成三层语义层、语法层、视觉层。语义层回答“这个图要表达什么概念”比如服务、队列、存储、用户语法层回答“这些概念之间允许哪些关系”比如调用、订阅、写入、读取视觉层回答“每种概念和关系长什么样”比如颜色、形状、线型、字号。三层定清楚后面画图就是填空题而不是创作题。2.2 为什么“一致性”比“好看”更重要很多新手会花大量时间调颜色、找图标追求图表的“高级感”。但在实际项目里一致性带来的收益远大于美观。一张图里如果“数据库”一会儿是蓝色圆柱一会儿是绿色方块读者的大脑就要额外做一次映射这个成本会随着图的数量增加而累积。diagram-design 强调的是一套稳定的视觉词汇表同一种事物在所有图里保持同一种表现方式。我自己的做法是先列出项目里最常见的 8 到 12 种元素给每种元素分配一个固定形状和固定颜色。比如矩形代表计算单元圆柱代表持久化存储菱形代表判断节点圆角矩形代表外部系统。颜色只用来区分“层级”或“环境”不用来区分“类型”。这样即使图很复杂读者也能靠形状快速识别而不是靠图例反复对照。2.3 图表与代码、文档的同步难题diagram-design 还有一个容易被忽略的价值它让图表变得“可维护”。传统画图工具产出的是一张静态图片代码改了图不会自动变。时间一长图和代码就脱节了。解决这个问题的常见思路有两种一种是用“图表即代码”的方式比如 Mermaid、PlantUML、Graphviz把图写成文本纳入版本管理另一种是建立“图表源文件”和“导出图片”的分离机制源文件定期更新导出图片只用于发布。我试过纯手绘加截图的方式也试过全代码生成的方式。实测下来混合方案最稳核心架构图用代码生成保证和代码结构同步偏概念性的示意图用手绘工具保证表达灵活。关键是无论哪种方式都要有一个“图表清单”记录每张图的用途、负责人、最后更新时间和对应的代码版本。3. 核心细节解析与实操要点形状、连线、布局的隐藏规则3.1 形状语义别让读者猜你的意思形状是图表里最基础的语义单元。diagram-design 里有一条经验规则形状的种类不要超过 6 种。超过 6 种读者就记不住了。我常用的六种形状和它们的含义如下形状含义使用场景矩形计算单元、服务、模块微服务、函数、类圆角矩形外部系统、第三方依赖支付网关、消息推送圆柱持久化存储数据库、对象存储、缓存菱形判断、分支条件路由、开关平行四边形数据输入输出文件、消息、请求体圆形起点或终点用户、定时器、事件源这张表看起来简单但真正执行起来最容易犯的错是“混用”。比如有人用矩形表示数据库又用圆柱表示某个服务读者就会困惑。我的建议是把这张表贴在项目文档里每次画图前先对照一遍。如果发现某个元素找不到对应形状优先考虑是不是可以归入已有类别而不是新增形状。3.2 连线规则箭头方向、线型和标签的约定连线比形状更容易被忽视。我见过太多图箭头方向混乱实线和虚线混用标签写在线的中间还是两端全凭心情。diagram-design 对连线的要求可以总结成三条方向一致、线型有含义、标签有位置。方向一致是指数据流或调用流的方向要统一。比如从左到右表示请求方向从右到左表示响应方向从上到下表示层级关系。不要一会儿左到右一会儿右到左读者会晕。线型有含义是指实线表示同步调用虚线表示异步消息点线表示可选依赖。标签有位置是指标签统一放在线的上方或左侧不要一会儿上一会儿下。注意如果一张图里连线超过 20 条考虑拆成两张图。连线密度过高任何设计规则都救不了可读性。3.3 布局原则分层、分组、留白布局是图表的“呼吸感”来源。diagram-design 里常用的布局策略是分层把系统按“接入层、逻辑层、存储层”从上到下排列或者按“用户侧、服务侧、数据侧”从左到右排列。分层之后再用浅色背景框把同一层的元素分组最后留出足够的空白。留白这件事新手最容易忽略。我见过很多图元素挤在一起连线交叉得像蜘蛛网。我的经验是元素之间的最小间距不要小于元素宽度的三分之一连线交叉超过三处就要重新调整布局。如果实在调不开就把图拆成“总览图”和“细节图”总览图只画核心模块细节图再展开。3.4 颜色使用克制比丰富更难颜色在图表里的作用不是装饰而是编码。diagram-design 建议把颜色数量控制在 3 到 5 种并且每种颜色要有明确含义。比如蓝色表示核心服务灰色表示辅助组件橙色表示警告或异常路径绿色表示成功路径。不要用红色表示“重要”因为红色在大多数文化里都暗示“危险”或“错误”。还有一个细节打印或投影时颜色可能会失真。所以不要只靠颜色区分元素形状和标签也要能独立表达含义。我习惯在导出图片时额外导出一份灰度版本检查一下在黑白模式下是否还能看懂。4. 实操过程与核心环节实现从零搭建一套图表规范4.1 第一步盘点现有图表找出混乱源头在制定规范之前先看看现状。我通常会收集项目里最近三个月用到的所有图表按类型分类架构图、流程图、时序图、状态图、ER 图。然后统计每种图里用到的形状、颜色、线型、标签格式。这一步的目的是找出“不一致”的具体表现而不是凭感觉说“太乱了”。比如我曾经统计过一个项目的 15 张架构图发现矩形出现了 4 种不同的圆角半径圆柱出现了 3 种不同的颜色箭头有 5 种不同的样式。这些具体数字比“图很乱”更有说服力也更容易让团队达成共识。4.2 第二步定义最小可用规范规范不要一上来就追求大而全。diagram-design 的实践里最小可用规范只需要覆盖三件事形状表、连线表、颜色表。形状表就是前面提到的六种形状和含义连线表定义实线、虚线、点线的含义颜色表定义每种颜色的用途。我建议把这三张表写进一个 Markdown 文件放在项目仓库的docs/diagram-guide.md里。每次画图前花两分钟对照一下。如果发现规范里没有覆盖的情况先讨论再补充不要临时发挥。4.3 第三步选择工具链并统一导出格式工具选择上我的建议是“一个主工具加一个辅助工具”。主工具用来画需要纳入版本管理的图比如 Mermaid 或 PlantUML辅助工具用来画概念示意图比如 Excalidraw 或 Draw.io。主工具的产出是文本方便 diff 和 review辅助工具的产出是图片方便插入文档和演示。导出格式也有讲究。如果是插入在线文档用 SVG 或 PNG如果是打印用 PDF 或高分辨率 PNG。我习惯把源文件和导出文件放在同一个目录下源文件用.mmd或.puml后缀导出文件用.svg后缀文件名保持一致。这样找起来方便也不容易搞混版本。4.4 第四步建立图表清单和更新机制图表最容易出的问题是“过期”。代码改了图没改后来的人照着旧图理解就会踩坑。解决这个问题靠自觉是不够的要有机制。我的做法是在项目仓库里维护一个diagrams/README.md里面用表格列出每张图的名称、用途、负责人、最后更新时间和关联的代码模块。图表名称用途负责人最后更新关联模块系统总览展示核心服务与依赖某开发者2025-03-10src/core订单流程展示下单到履约的状态流转A同学2025-03-08src/order数据同步展示主从库同步机制某导师2025-02-28src/sync每次代码合并请求涉及架构变更时负责人要检查关联图表是否需要更新。如果不需要更新在合并请求里说明原因如果需要更新更新后再合并。这个机制听起来麻烦但执行几次之后就会变成习惯比事后补图省事得多。4.5 第五步定期评审和迭代规范规范不是一成不变的。每季度或每半年花半小时回顾一下图表规范的使用情况。哪些规则经常被违反哪些规则已经过时有没有新的图表类型需要支持我通常会收集团队成员的反馈然后小步调整而不是一次性大改。比如我们最初规定所有服务都用蓝色矩形后来发现“核心服务”和“辅助服务”需要区分就增加了浅蓝和深蓝两种变体。这种调整是基于实际使用中的痛点而不是凭空设计。5. 常见问题与排查技巧实录那些年我们踩过的图表坑5.1 图表太复杂读者看不懂怎么办这是最常见的问题。解决方案不是把图缩小而是拆图。我通常按“总览、模块、细节”三层来拆。总览图只画 5 到 7 个核心模块用最简单的连线表示关系模块图展开每个模块的内部结构细节图只画关键流程或关键数据结构。每张图只回答一个问题不要试图用一张图讲完整个系统。如果拆完还是复杂那就检查是不是“信息密度”太高。比如一张图里同时有同步调用、异步消息、数据流、控制流读者要不断切换思维模式。这时候可以考虑用不同颜色的线区分或者干脆拆成两张图一张画调用关系一张画数据流向。5.2 图表和代码不一致怎么排查先确认“不一致”的具体表现是模块名称变了还是依赖关系变了还是数据流向变了。然后找到对应的代码模块用git log查看最近的变更记录。如果变更发生在图表更新之后那就是图表过期了如果变更发生在图表更新之前那就是图表画错了。排查的时候我习惯用“反向验证”的方法从代码里导出模块依赖关系和图表里的连线做对比。Mermaid 和 PlantUML 都支持从代码生成图虽然自动生成的图通常比较丑但用来验证关系是否正确非常有效。5.3 团队不愿意遵守规范怎么推动规范推行不下去通常是因为“遵守规范的成本”大于“不遵守的收益”。所以降低遵守成本是关键。我的做法是把规范做成模板。比如在 Draw.io 里建一个模板文件里面预置好形状、颜色、连线样式团队成员打开就能用不需要从头设置。在 Mermaid 里把常用样式写成 CSS 类画图时直接引用类名不用每次写样式。另一个方法是“先示范再推广”。我自己先用规范画几张图在评审会上展示效果让大家看到一致性带来的可读性提升。然后邀请一两个愿意尝试的同事一起用形成小范围共识再逐步扩大。不要一上来就强制所有人遵守那样容易引起抵触。5.4 图表文件太大版本管理困难如果图表是图片格式每次修改都会产生一个全新的二进制文件Git 无法有效 diff仓库体积也会迅速膨胀。解决方案是尽量用文本格式的图表工具比如 Mermaid、PlantUML、Graphviz。这些工具的源文件是纯文本Git 可以逐行对比仓库体积也小。如果必须用图片格式比如手绘风格的示意图那就把源文件和导出文件分开管理。源文件放在diagrams/source/目录下导出文件放在diagrams/export/目录下并且把导出文件加入.gitignore只在发布时手动导出。这样仓库里只保留源文件体积可控。5.5 常见问题速查表问题可能原因排查方法解决建议图表看不懂信息密度过高数一数图里的元素和连线数量拆成总览图和细节图图表过期代码变更后未更新对比代码模块和图表模块建立图表清单和更新机制风格不一致缺少统一规范统计形状、颜色、线型的使用情况制定最小可用规范文件太大使用二进制图片格式检查仓库里图片文件的数量和大小改用文本格式图表工具团队不配合遵守成本太高了解团队成员画图时的痛点提供模板和样式类提示排查图表问题时先问“这张图给谁看”再问“他们需要从中获取什么信息”。答案不同解决方案也不同。6. 图表设计的进阶思路从静态图到可交互文档6.1 用图表驱动文档结构当图表规范稳定之后可以尝试让图表成为文档的“骨架”。比如系统设计文档的每个章节都对应一张架构图里的模块。读者可以先看总览图了解系统全貌然后点击或跳转到对应章节查看细节。这种“图文档一体”的结构比纯文字文档更容易导航也比纯图表更容易补充细节。我试过用 Markdown 加 Mermaid 的方式来实现这种结构。在 Markdown 里嵌入 Mermaid 代码块渲染出来就是图图下面紧接着写该模块的详细说明。这样文档和图表在同一个文件里修改时不容易脱节。如果团队用支持 Mermaid 的文档平台效果会更好。6.2 图表作为代码审查的辅助工具在代码审查时如果变更涉及架构调整可以要求提交者附上一张更新后的架构图。审查者对照图和代码能更快理解变更的影响范围。我自己的经验是带图的合并请求审查时间平均能缩短三分之一。因为图能直观展示“改了什么”和“影响了谁”比纯代码 diff 更容易理解。为了让这个做法落地可以在合并请求模板里加一个检查项“本次变更是否涉及架构调整如果是请更新diagrams/目录下的相关图表。”这样每次提交时都会提醒久而久之就形成了习惯。6.3 图表规范的跨项目复用如果你在多个项目里工作可以把图表规范抽出来做成一个独立的模板仓库。新项目启动时直接复制模板仓库里的diagram-guide.md和模板文件稍作调整就能用。这样既保证了跨项目的一致性又减少了重复劳动。我自己的模板仓库里除了规范文档还包含几个常用图表的示例系统总览、请求流程、数据模型、状态机。每个示例都有对应的 Mermaid 源文件和导出图片。新项目需要画图时先看看示例里有没有类似的有就改没有就新建。这样起步速度会快很多。6.4 图表设计中的常见误区第一个误区是“追求大而全”。一张图想讲完所有事情结果什么都讲不清楚。第二个误区是“过度装饰”。加太多图标、阴影、渐变反而干扰了信息传达。第三个误区是“忽视读者背景”。给业务方看的图和给开发看的图详细程度和术语使用应该不同。第四个误区是“一次定终身”。规范制定后从不回顾导致规范越来越脱离实际。避开这些误区的方法很简单每次画完图问自己三个问题。这张图给谁看他们需要从中获取什么信息如果我是他们能看懂吗如果答案不确定就找一个人实际看一下收集反馈再调整。7. 我个人在实际操作中的体会这套 diagram-design 的思路我断断续续用了两年多最大的感受是图表的混乱本质上是沟通的混乱。形状、颜色、连线这些视觉元素只是表象背后是团队对系统理解的不一致。统一图表规范的过程其实也是统一认知的过程。当大家用同一套词汇描述系统时讨论效率会明显提升。另一个体会是规范要“活”的不要“死”的。我见过一些团队规范写得很详细但没人看因为太复杂了。好的规范应该像交通规则简单、明确、容易记住。如果一条规则需要解释五分钟才能让人明白那它大概率不会被遵守。所以宁可少几条规则也要保证每条规则都能落地。最后分享一个小技巧每次画完图把图发给一个不熟悉这个系统的同事让他用自己的话复述一遍图的内容。如果他复述得准确说明图画清楚了如果他卡在某个地方那个地方就是需要改进的地方。这个方法比任何规范都有效因为它直接检验了图表的沟通效果。