1. 从一张草图到一套系统：diagram-design 到底在解决什么问题

第一次听到 “diagram-design” 这个词，很多人会下意识觉得它只是“画图”的另一种说法。但真正在项目里被图表折磨过的人知道，画图只是冰山一角，水面下藏着的是一整套关于信息结构、视觉语法和协作效率的工程问题。diagram-design 的核心，不是教你用某个工具拖几个方框，而是建立一套可复用、可维护、可交接的图表设计体系——让一张架构图在三个月后还能被新人看懂，让同一套图在文档、演示、白板等不同场景下保持一致的表达逻辑。

我做过一个粗略统计：在一个中等规模的技术团队里，一个项目从立项到交付，平均会产生 40 到 60 张不同用途的图表。需求阶段的业务流程图、设计阶段的系统架构图、开发阶段的时序图、测试阶段的用例图、运维阶段的部署拓扑图，再加上各种汇报用的数据看板。这些图如果各自为政，每张都按画图人当时的直觉来，最后就会变成一场灾难——同一个服务在五张图里有五个名字，同一个数据流在三个地方画了三种箭头，新人接手时光是搞清楚“这张图到底在说什么”就要花掉半天。

diagram-design 要解决的，正是这种“图与图之间没有共同语言”的问题。它适合的人群比想象中广：不只是设计师，还包括需要画架构图的后端工程师、需要画流程图的產品经理、需要画数据流向图的数据分析师，以及需要把复杂逻辑讲清楚的技术写作者。哪怕你自认为“没有设计细胞”，只要你的工作里需要让别人通过一张图理解一个系统，这套思路就能帮上忙。

我个人的体会是，图表设计的门槛不在审美，而在结构。审美可以慢慢养，但结构一旦错了，图越漂亮反而越误导人。diagram-design 的价值，就是先把结构这件事说清楚，再谈视觉。

2. 图表设计的底层逻辑：为什么大多数图都“不好看又不好懂”

2.1 信息层级混乱是万恶之源

一张图让人看不懂，九成以上的原因不是画得丑，而是信息层级没有拉开。什么叫信息层级？简单说就是：读者第一眼该看到什么，第二眼该看到什么，第三眼才该看到什么。很多图的问题在于，所有元素都在抢注意力——标题和正文一样大，核心服务和边缘依赖用同一种颜色，关键路径和备选路径用同一种线型。读者的眼睛在图上乱撞，找不到入口。

我见过一张典型的“反面教材”：一个微服务架构图，二十多个服务全部用同样的圆角矩形，同样的蓝色填充，同样的黑色文字。图例倒是画了，但图例里区分了“核心服务”“支撑服务”“外部依赖”三类，图上却完全看不出来。这种图的问题不是画图人不用心，而是他在画的时候脑子里没有“读者视角”。他画的是“我知道有什么”，而不是“读者需要先知道什么”。

解决这个问题的办法，是在动手之前先问自己三个问题：这张图的第一读者是谁？他看这张图的目的是什么？如果只能保留三个元素，是哪三个？这三个问题的答案，直接决定了图的信息层级。比如给管理层看的架构图，第一层级应该是业务能力和它们之间的关系，技术细节要压到第二甚至第三层级；给开发看的架构图，第一层级应该是服务边界和调用关系，业务描述反而可以简化。

2.2 视觉语法不统一，读者就要重新学习

视觉语法这个词听起来有点玄，其实很具体：颜色代表什么、形状代表什么、线型代表什么、箭头方向代表什么。一套好的视觉语法，应该让读者在看第二张图的时候不需要重新学习。但现实中，很多团队的图表是“一张图一套语法”。这张图里红色代表错误，那张图里红色代表核心；这张图里虚线代表异步，那张图里虚线代表可选。

我自己的做法是，在项目启动阶段就定一份极简的“图表语法约定”，不超过一页纸，包含四件事：主色不超过三种，分别对应“核心”“支撑”“外部”；形状不超过四种，分别对应“服务”“数据存储”“用户”“外部系统”；线型不超过两种，实线同步、虚线异步；箭头方向统一为“调用方指向被调用方”或“数据流向”，二选一，全项目统一。这份约定不需要多完美，关键是“有”并且“被遵守”。

提示：语法约定不要定得太细。我见过一份二十多页的图表规范，结果没人看。三色四形两线，足够覆盖大多数场景。

2.3 布局不是艺术，是逻辑的外化

很多人以为布局是“摆得好看”，其实布局是逻辑的外化。一张图的布局方式，直接暴露了画图人对系统结构的理解程度。分层布局适合表达“上层依赖下层”，左右布局适合表达“输入到输出”，环形布局适合表达“循环往复”，网格布局适合表达“对等协作”。选错布局，逻辑就会拧巴。

举个例子，一个典型的三层架构——接入层、逻辑层、存储层——用分层布局（从上到下）是最自然的，因为依赖关系是单向的。但如果硬要用左右布局，读者就会下意识地寻找“从左到右”的流转关系，而实际上并没有，这就造成了认知负担。反过来，一个数据流水线，从数据源到清洗到分析到展示，用左右布局就比上下布局更符合直觉，因为“流动”的方向感更强。

我在实际项目里总结了一个简单的判断方法：如果元素之间的关系是“依赖”，优先用分层；如果是“流转”，优先用左右；如果是“协作”，优先用网格；如果是“循环”，优先用环形。这个判断不需要精确，但能避免大多数布局上的低级错误。

3. 从零搭建一套可复用的图表设计体系

3.1 第一步：定义你的图表类型清单

不要一上来就画图，先列清单。一个项目里通常需要哪些类型的图？我一般会分成四类：结构类（架构图、部署图、组件图）、行为类（流程图、时序图、状态图）、数据类（ER 图、数据流图、数据血缘图）、叙事类（用户旅程图、故事板、汇报看板）。这四类图的读者、目的、详细程度都不一样，不能用同一套标准去要求。

结构类图的核心是“边界和关系”，要清楚画出什么在系统内、什么在系统外、什么之间有什么依赖。行为类图的核心是“顺序和条件”，要清楚表达先做什么、后做什么、什么情况下走哪条分支。数据类图的核心是“来源和去向”，要清楚标注数据从哪来、经过什么处理、最终到哪去。叙事类图的核心是“情绪和节奏”，要清楚传达用户在什么阶段有什么感受、关键转折点在哪里。

列清单的好处是，你能提前发现“缺图”和“重图”。缺图是指某个关键视角没有图覆盖，比如只画了架构图没画部署图，导致运维同事看不懂怎么上线。重图是指同一件事画了好几张图，比如既画了流程图又画了时序图，但两者表达的信息高度重叠，维护起来就是双倍成本。

3.2 第二步：建立最小可用的视觉规范

视觉规范不需要复杂，但需要“可执行”。我通常从四个维度来定：颜色、字体、间距、线型。颜色方面，主色三种足够：一种用于核心元素，一种用于支撑元素，一种用于外部或次要元素。辅助色可以加一两种用于强调或警示，但不要超过五种。字体方面，标题和正文用同一字体家族的不同字重即可，字号差距要拉开，标题至少是正文的 1.5 倍。间距方面，元素之间的间距要有一致性，要么统一 16px，要么统一 24px，不要这里 10px 那里 30px。线型方面，实线用于主要关系，虚线用于次要或异步关系，点线用于可选或未来规划。

这套规范的关键不是“好看”，而是“一致”。一致带来的直接好处是，读者在看第二张图时不需要重新建立认知映射。我见过一个团队，他们的图表规范只有一页 PPT，但全组严格执行了两年，结果就是任何一张新图出来，大家都能在几秒内找到自己关心的部分。这就是规范的价值。

注意：规范一旦定下，就要有“违反成本”。我一般会在团队里约定，如果一张图不符合规范，评审时直接打回，不讨论内容。听起来有点严，但执行两周后大家就习惯了，反而省下了大量“这张图为什么和上一张不一样”的沟通时间。

3.3 第三步：用模板固化高频图表

高频图表一定要模板化。什么叫高频？一个项目里出现五次以上的图表类型，就值得做模板。模板不是让你偷懒，而是让你把精力从“怎么画”转移到“画什么”。我自己的模板库里有这么几类：分层架构模板、左右流程模板、时序图模板、ER 图模板、用户旅程模板。每个模板都预设好了颜色、字体、间距、图例位置，打开就能用。

模板的另一个好处是“交接友好”。新人入职时，不需要从零学习这套视觉语法，直接看模板就知道该怎么画。我带过的一个项目，前后换了三拨人画图，但因为模板统一，最后交付的图表集看起来像一个人画的。这在交接场景下价值巨大——接手的人不需要先花一周时间“翻译”前任的图表语言。

模板的维护也有讲究。我一般会每季度回顾一次模板库，看看哪些模板用得多、哪些用得少、哪些需要调整。用得少的模板要么删掉，要么合并；用得多的模板要考虑是否要拆出更细的变体。模板不是越多越好，多了反而增加选择成本。

3.4 第四步：把图表纳入版本管理

图表也是代码，应该纳入版本管理。我见过太多项目，图表散落在各个人的电脑里，最后要汇总时发现版本混乱，不知道哪张是最新的。正确的做法是，图表源文件（无论是哪种格式）和代码一样，放在同一个仓库里，用同样的分支策略和评审流程。

具体操作上，我一般会建一个docs/diagrams目录，按图表类型分子目录，每个图表文件命名遵循类型-主题-版本的格式，比如arch-payment-service-v2。每次修改图表，都走一次合并请求，至少一个人评审。评审的重点不是“好不好看”，而是“信息是否准确”“是否符合视觉规范”“是否和代码一致”。

这样做的好处是，图表的历史可追溯。三个月后有人问“这个服务是什么时候加进来的”，直接看提交记录就知道。半年后有人问“为什么这里画了虚线”，看当时的评审讨论就知道。图表不再是“一次性消耗品”，而是和代码一样，成为项目资产的一部分。

4. 实操：一张架构图的完整设计过程

4.1 需求澄清：先搞清楚这张图给谁看

假设现在要画一张“订单系统”的架构图。动手之前，先问清楚：这张图给谁看？如果是给新加入的开发看，重点应该是服务边界和调用关系，技术栈和中间件要标清楚。如果是给产品经理看，重点应该是业务能力和数据流向，技术细节可以省略。如果是给运维看，重点应该是部署单元和依赖关系，网络分区和容灾策略要体现。

我一般会做一个简单的“读者画像”：第一读者是谁，他的技术背景如何，他看这张图最想回答什么问题。这三个问题的答案，直接决定了图的详细程度和侧重点。比如第一读者是后端开发，他最想回答的问题是“我改这个服务会影响谁”，那么图里就必须清楚画出调用方和被调用方，以及调用的同步异步属性。

这一步最容易被跳过，但恰恰最重要。我见过太多图，画得精美无比，但读者看完还是不知道“所以呢”。问题就出在，画图人没有想清楚“这张图要回答什么问题”。一张图回答一个问题，不要贪多。

4.2 元素梳理：把系统拆成可画的块

需求清楚后，开始梳理元素。我一般会拿一张白纸，先把系统里所有的“东西”列出来：服务、数据库、缓存、消息队列、外部系统、用户角色。然后归类：哪些是核心服务，哪些是支撑服务，哪些是外部依赖。归类之后，再梳理它们之间的关系：谁调用谁，谁依赖谁，数据往哪流。

这一步的关键是“粒度一致”。不要有的服务拆得很细，有的服务又合并成一个大块。粒度不一致会让读者困惑：为什么这个画得这么细，那个画得这么粗？我一般会按“部署单元”来定粒度，一个独立部署的服务就是一个块，数据库和缓存按实例或集群来画，外部系统按系统边界来画。

梳理完之后，我会做一个“减法”：如果只能保留十个元素，保留哪十个？这个减法强迫我区分“必要”和“想要”。很多图之所以乱，就是因为画图人把“想要”的东西也画进去了。比如一个内部监控服务，对理解主流程并不关键，但画图人觉得“画上更完整”，结果就增加了噪音。

4.3 布局推演：从逻辑结构到视觉结构

元素梳理完，开始布局。我一般会先用纸笔快速画三到四个布局方案，然后选一个最符合逻辑的。比如订单系统，可能的布局有：按业务域分层（订单、支付、库存、物流），按调用链左右排布（用户到网关到服务到存储），按部署环境分区（生产、预发、测试）。选哪个取决于这张图要回答什么问题。

如果是给开发看调用关系，左右排布最直观。如果是给产品看业务能力，分层布局最清晰。如果是给运维看部署，分区布局最合适。我一般会选一个主布局，然后在局部做微调。比如左右排布的主布局下，把共享的数据库放在底部，用虚线连到各个服务，这样既保持了主流程的清晰，又表达了共享依赖。

布局推演的时候，我会特别注意“交叉线”的数量。交叉线是认知负担的主要来源，能避免就避免。如果两条线必须交叉，我会考虑调整元素位置，或者用不同的颜色/线型来区分。实测下来，一张图里交叉线超过五条，读者的理解速度就会明显下降。

4.4 视觉细化：颜色、字体、间距的最终调整

布局定了之后，才是视觉细化。这一步我一般会按顺序来：先定颜色，再定字体，最后调间距。颜色方面，核心服务用一种主色，支撑服务用浅一号的同色系，外部系统用灰色，数据库用另一种颜色以示区分。字体方面，标题加粗加大，正文统一字号，注释用更小的字号和更浅的颜色。间距方面，同层元素间距一致，层与层之间间距更大，形成视觉分组。

这一步最忌讳“过度设计”。我见过一些图，用了渐变、阴影、圆角、图标，看起来很“高级”，但信息传达效率反而下降了。图表设计的目的是“传达信息”，不是“展示设计技巧”。能用纯色就不用渐变，能用文字就不用图标，能用直线就不用曲线。简洁不是简陋，而是把注意力留给信息本身。

提示：如果你不确定颜色搭配是否合适，把图转成灰度看看。如果灰度下信息层级依然清晰，说明颜色用得合理；如果灰度下一团糊，说明你过度依赖颜色来区分信息了。

4.5 评审与迭代：让图在反馈中变好

图画出第一版后，一定要找人评审。评审的对象最好是“目标读者”的代表。如果这张图是给开发看的，就找一个没参与画图的开发来看，让他在不看解释的情况下说出“这张图在讲什么”。如果他能准确说出核心信息，说明图成功了；如果他说得含糊或者理解偏了，说明图还有问题。

评审的时候，我一般会问三个问题：第一眼看到了什么？哪里看不懂？如果只能改一处，改哪里？这三个问题的答案，往往能揭示画图人自己意识不到的盲区。我印象最深的一次，我画了一张自认为很清晰的架构图，结果评审时一个同事说“我不知道从哪里开始看”。后来我加了一个简单的阅读顺序标注（用数字或箭头），问题就解决了。

迭代不要超过三轮。第一轮解决结构问题，第二轮解决视觉问题，第三轮解决细节问题。三轮之后如果还有大问题，说明前面的需求澄清或元素梳理没做好，要回头重来。不要在一张图上无限打磨，时间成本不划算。

5. 常见问题与排查技巧实录

5.1 图太乱怎么办：从“减法”开始

图太乱是最常见的问题。我的第一反应永远是“删”，而不是“调”。先删掉所有非必要元素，再看剩下的元素能不能用更简单的布局表达。很多时候，图乱不是因为元素太多，而是因为元素之间的关系没有理清。把关系理清后，你会发现有些元素根本不需要画出来。

如果删完之后还是乱，那就考虑“分图”。一张图讲一件事，如果一件事讲不完，就拆成两张。比如一张总览图加几张细节图，总览图只画核心服务和主流程，细节图分别展开每个核心服务的内部结构。这样读者可以先看总览建立全局观，再按需深入细节。

5.2 颜色不够用怎么办：用形状和线型补位

颜色不够用是另一个常见问题。我的建议是，不要试图用颜色区分所有东西。颜色只用来区分“最重要的两到三类”，剩下的用形状和线型来区分。比如服务用矩形，数据库用圆柱，外部系统用圆角矩形；同步调用用实线，异步调用用虚线。这样即使颜色只有两三种，信息也能区分清楚。

如果形状和线型也不够用，那就考虑“分组”。用背景色块或边框把相关元素框在一起，组内用颜色区分，组间用位置区分。分组的好处是，读者可以先看组，再看组内元素，认知负担会小很多。

5.3 图例没人看怎么办：把图例融入图本身

图例没人看，是因为图例和图是分离的。读者需要先在图上看到某个符号，再跑到图例里查这个符号是什么意思，然后再回到图上。这个来回本身就是认知负担。我的做法是，尽量把图例融入图本身。比如在第一个出现的服务旁边直接标注“核心服务”，在第一个出现的虚线旁边直接标注“异步调用”。这样读者不需要查图例，直接在图上看懂。

如果图例实在无法融入，那就把图例放在读者视线自然落点的位置。一般来说，读者的视线从左上角开始，所以图例放在左上角或右上角比放在底部好。图例的样式也要和图保持一致，不要图例是一种风格，图是另一种风格。

5.4 图更新后没人知道怎么办：建立变更通知机制

图更新后没人知道，是协作层面的问题。我的做法是，把图表变更纳入常规的代码评审流程。每次图表有实质性变更，就在合并请求里 @ 相关的人，并在描述里写清楚“改了什么、为什么改、影响谁”。这样相关的人会在评审时看到变更，而不是等到用图的时候才发现图变了。

另外，我会在图表文件里加一个简单的“变更记录”区块，记录每次变更的日期、内容和原因。这个记录不需要很详细，一两句话即可。但它的存在，让后来的人能快速了解图表的演进历史，避免“这张图为什么是这样”的困惑。

5.5 常见问题速查表

6. 工具选型与协作流程的实战建议

6.1 工具不是关键，但选错工具很痛苦

图表工具大致分三类：代码化工具（用文本描述生成图）、拖拽式工具（手动摆放元素）、混合式工具（两者结合）。代码化工具适合需要频繁更新、纳入版本管理的图，比如架构图和流程图。拖拽式工具适合一次性或低频更新的图，比如汇报看板。混合式工具适合既要灵活又要可维护的场景。

我自己的选择是：结构类和行为类图用代码化工具，因为这类图更新频繁，且需要和代码保持一致。叙事类图用拖拽式工具，因为这类图更依赖视觉表达，代码化反而限制发挥。数据类图看情况，ER 图用代码化，数据看板用拖拽式。

选工具的时候，不要只看功能，要看“协作成本”。一个工具如果只有你能用，别人改不了，那它就是协作的障碍。我一般会优先选团队里大多数人能上手的工具，哪怕功能少一点。工具的统一性比功能的丰富性更重要。

6.2 协作流程：谁画、谁审、谁维护

图表协作最大的问题是“责任不清”。一张图出来后，没人知道该找谁改。我的做法是，每张图都有一个明确的“负责人”，负责图的准确性和及时更新。负责人不一定是画图的人，但一定是最关心这张图的人。比如架构图的负责人通常是架构师，流程图的负责人通常是产品经理。

评审流程我一般设两道：第一道是“内容评审”，由领域专家确认信息准确；第二道是“视觉评审”，由设计或前端确认符合规范。两道评审可以合并，但不要省略。我见过太多图，内容对了但视觉乱了，或者视觉美了但内容错了，都是因为少了一道评审。

维护方面，我一般会约定一个“保鲜期”。超过保鲜期（比如三个月）的图，要么更新，要么标记为“历史版本”。不要让过期的图留在文档里误导人。标记为历史版本也是一种负责，至少读者知道这张图可能不代表现状。

6.3 从个人习惯到团队资产

图表设计这件事，从个人习惯到团队资产，需要一个过程。最开始可能只是你一个人按这套方法画图，然后你发现效率提高了、沟通成本降低了。接着你开始影响身边的人，让他们也用同样的方法。最后这套方法变成团队的默认做法，新人进来自然就学会了。

这个过程的关键是“示范”而不是“要求”。不要一上来就写规范、定流程，而是先自己做出几张高质量的图，让别人看到效果。当别人问“你这张图怎么画的”时，你再分享方法。这样推广起来阻力小得多。

我自己的经验是，一个五人团队，从第一个人开始用这套方法，到全团队默认使用，大概需要两到三个月。前一个月是个人实践，第二个月是小范围推广，第三个月是形成共识。不要急，图表设计的价值是长期的，不是一次性的。

7. 图表设计的长期价值：从“画图”到“思考”

7.1 图表是思考的工具，不是思考的结果

很多人把图表当成“思考完之后”的输出，其实图表本身就是思考工具。画图的过程，就是强迫自己把模糊的想法变清晰的过程。我经常在画图的过程中发现逻辑漏洞——某个服务的输入没定义清楚，某个数据流的异常分支没考虑，某个依赖关系是循环的。这些问题在纯文字描述时不容易发现，但一画图就暴露了。

所以我的建议是，不要等到想清楚了再画图，而是通过画图来想清楚。先画一个粗糙的版本，然后不断迭代。每迭代一次，你对系统的理解就深一层。最终交付的图，只是这个思考过程的副产品。

7.2 好的图表能降低组织的沟通成本

一个组织里，沟通成本往往被低估。同样一件事，用文字描述可能需要十分钟，用一张图可能只需要一分钟。而且图的信息密度更高，误解更少。我做过一个对比：同一个架构变更，用文字邮件通知，平均会产生三到五轮追问；用一张标注清楚的架构图通知，追问通常不超过一轮。

图表设计的长期价值，就是持续降低这种沟通成本。当团队里每个人都习惯用图来表达和沟通时，信息的传递效率会显著提升。这不是一次性的收益，而是随着图表资产的积累，收益会越来越大。

7.3 从图表设计到系统思维

最后说一点个人的体会。图表设计做久了，你会发现它训练的不只是画图能力，而是系统思维。画一张架构图，你需要理解系统的边界、组件的职责、依赖的方向、数据的流向、异常的处理。这些思考方式和系统设计是相通的。很多工程师在画图的过程中，反过来加深了对系统的理解，甚至发现了设计上的改进点。

我在实际项目里不止一次遇到这种情况：画图时发现某个服务依赖了不该依赖的东西，或者某个数据流绕了远路。这些问题在代码里可能不明显，但在图上一眼就能看出来。所以我现在会把画图当成一种“设计审查”的手段，定期画一画，往往能发现一些平时忽略的问题。

这个内容后续还可以这样扩展：把图表设计和文档体系结合起来，让图表成为文档的骨架；或者把图表设计和代码生成结合起来，让图能自动从代码里生成。这些都是值得探索的方向，但前提是先把基础的图表设计能力打扎实。