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

第一次看到 “diagram-design” 这个标题，很多人会以为它只是一个画图工具的教程，或者某个图表库的使用说明。但真正做过技术方案、写过设计文档、给团队讲过架构的人会明白，图只是表象，设计才是核心。diagram-design 这个主题，本质上讨论的是：如何把脑子里那些模糊的、线性的、散落各处的想法，转化成一张结构清晰、信息密度合理、别人一眼就能看懂的图，并且让这张图能持续维护、迭代、复用。

我做了十多年技术方案和架构梳理，画过的图少说也有几千张。早期用 Visio，后来用各种在线工具，再后来干脆用代码画图。踩过的坑包括但不限于：图太复杂没人看、图太简单说不清、图更新了文档没更新、图里的缩写只有自己看得懂。这些问题表面上是“画图技巧”问题，实际上是信息设计问题。diagram-design 要解决的，就是这一整套从信息梳理到视觉呈现再到长期维护的方法论。

这篇文章适合谁看？如果你是技术负责人、产品经理、系统架构师、技术文档写作者，或者任何需要把复杂逻辑讲清楚的人，那这套东西你迟早用得上。它不挑工具，不挑平台，甚至不挑你画的是架构图、流程图、时序图还是业务链路图。核心思路是通用的：先想清楚要表达什么，再决定怎么画，最后考虑怎么让它活得久。

我见过太多团队在“画图”这件事上浪费大量时间：有人花两小时调对齐，有人为了一个箭头方向争论半天，有人画完图之后再也没有打开过。这些问题的根源，不是工具不好用，而是没有一套从设计到落地的完整思路。diagram-design 这个主题，就是把这套思路拆开揉碎，让你下次画图的时候，脑子里先有一张“设计图”，再动手画那张“展示图”。

2. 核心设计思路：为什么你的图总是“看起来对，读起来累”

2.1 图的本质是信息压缩，不是信息堆砌

很多人画图有一个误区：觉得图里信息越多越显得专业。于是把所有的模块、所有的接口、所有的字段都塞进去，最后得到一张密密麻麻的“蜘蛛网”。这种图的问题在于，它把压缩做成了堆砌。图的本质是信息压缩，是用更少的视觉元素传递更清晰的结构关系。一张好的图，应该像一句好文案：每个元素都有存在的理由，删掉任何一个都会损失信息。

我在实际项目中总结了一个判断标准：如果你把图里的文字全部去掉，只看框和线，能不能大致猜出结构关系？如果能，说明你的视觉层次是清晰的；如果不能，说明你过度依赖文字标注，图本身的结构没有立起来。diagram-design 的第一个核心原则就是：先定结构，再填内容，最后调视觉。顺序反了，就会陷入“越画越乱、越乱越改”的死循环。

具体怎么做？我通常分三步走。第一步，用纸笔或者纯文本列出所有需要表达的元素和关系，这时候不考虑布局和样式。第二步，把这些元素按照层级、流向、分组进行归类，确定哪些是核心、哪些是辅助、哪些可以合并。第三步，才是选择图形和布局方式。这个过程听起来简单，但实际操作中，很多人跳过前两步直接进入第三步，结果就是一边画一边想，最后画出来的图自己都不想看第二遍。

2.2 视觉层次决定阅读顺序，阅读顺序决定理解效率

一张图被打开之后，读者的眼睛会按照一定的顺序移动。这个顺序不是随机的，而是被视觉层次引导的。视觉层次包括大小、颜色、位置、粗细、留白等多个维度。diagram-design 的核心工作之一，就是主动设计这个层次，而不是让读者自己去猜。

举个例子，如果你画一张系统架构图，核心服务应该放在视觉中心，用较大的块和较深的颜色；辅助服务放在边缘，用较小的块和较浅的颜色；数据流向用箭头表示，箭头的粗细可以反映调用频率或数据量。这样读者第一眼看到的是核心服务，第二眼看到的是它们之间的关系，第三眼才会去看辅助细节。这个顺序和你想要传达的信息优先级是一致的。

我见过很多图的问题在于：所有元素一样大、一样粗、一样颜色。这种“平均主义”的图，读者需要自己判断哪个重要哪个不重要，认知负担很重。更糟糕的是，有些图用颜色区分模块，但颜色选择毫无逻辑，红绿蓝紫随便用，结果读者把时间花在“这个红色代表什么”上，而不是理解结构本身。颜色应该服务于语义，而不是服务于装饰。比如用暖色表示输入、冷色表示输出，用同色系深浅表示层级，用对比色表示异常或重点。这些规则一旦建立，读者就能快速建立心理映射，理解效率会大幅提升。

2.3 一致性比创意更重要

在 diagram-design 的实践中，我越来越觉得：一致性是专业度的第一体现。同一份文档里的多张图，如果风格不统一，读者每看一张图都要重新适应一套视觉语言，这种切换成本非常高。一致性包括：相同的元素用相同的形状、相同的颜色代表相同的含义、相同的连线风格表示相同的关系类型、相同的字体和字号层级。

我通常会在项目开始之前，先定义一套简单的“图例规范”。比如：矩形代表服务、圆角矩形代表模块、菱形代表判断、圆柱代表存储、实线箭头代表同步调用、虚线箭头代表异步消息、粗箭头代表高频调用。这套规范不需要很复杂，但一旦定下来，所有图都严格遵守。这样做的好处是，读者看第一张图的时候需要学习一下图例，看第二张图的时候就可以直接进入内容，认知成本大幅降低。

注意：图例规范不是越细越好。我见过有人定义了二十多种形状和线型，结果自己都记不住。一般控制在五到八种基本元素就够了，超过这个数量，读者记不住，你也画得累。

2.4 从“一次性交付”到“可持续维护”

很多图的生命周期很短：画完、发出去、没人看、过期、被遗忘。diagram-design 要解决的另一个核心问题是：如何让图可持续维护。这个问题在快速迭代的项目中尤其突出，系统每周都在变，图如果跟不上，很快就会变成“历史文物”。

我的做法是：把图当成代码来管理。具体来说，能用文本描述的结构，就不要用纯图形工具画。比如用 Mermaid、PlantUML、Graphviz 这类文本化绘图工具，图的定义就是一个文本文件，可以进版本控制、可以 diff、可以 review。系统变了，改几行文本，图自动更新。这种方式特别适合架构图、流程图、时序图这类结构化程度高的图。

当然，不是所有图都适合文本化。比如需要精细排版的业务蓝图、需要手绘风格的示意图，还是得用图形工具。但即使是这类图，我也会尽量把“结构定义”和“视觉呈现”分开。结构定义用文本或表格维护，视觉呈现用工具生成。这样即使视觉部分需要重画，结构信息也不会丢失。

3. 核心细节解析：从需求到成图的完整拆解

3.1 先问清楚：这张图给谁看，看完要做什么

这是 diagram-design 的第一步，也是最容易被跳过的一步。很多人接到“画个架构图”的需求，打开工具就开始拖框，结果画完发现：给领导看的图太技术，给开发看的图太抽象，给运维看的图缺部署信息。问题出在：没有明确读者和目的。

我通常会问三个问题：第一，这张图的主要读者是谁？第二，读者看完这张图之后，需要做出什么决策或执行什么操作？第三，这张图会在什么场景下被打开？是放在文档里供人查阅，还是放在 PPT 里辅助讲解，还是贴在墙上供团队日常参考？这三个问题的答案，直接决定了图的详细程度、视觉风格和信息密度。

举个例子，如果读者是高层管理者，目的是让他们快速理解系统全貌和关键风险点，那图应该高度抽象，只保留核心模块和关键流向，用颜色标注风险等级，文字标注尽量少。如果读者是开发人员，目的是让他们理解模块之间的调用关系和接口定义，那图应该包含具体的服务名、接口名、数据格式，甚至可以把关键字段列出来。如果读者是运维人员，目的是让他们知道部署拓扑和故障排查路径，那图应该包含机房、集群、节点、网络分区等信息。

实操心得：我习惯在图的角落加一行小字，写明“本图面向 XX 读者，用于 XX 目的，最后更新于 XX 时间”。这行字看起来不起眼，但能省掉很多沟通成本。有人问“为什么图里没有 XX”，你可以直接指给他看：这张图不是给他看的。

3.2 信息分层：核心层、支撑层、细节层

确定读者和目的之后，下一步是信息分层。我通常把图里的信息分成三层：核心层是必须让读者看到的，通常不超过七个元素；支撑层是帮助理解核心层的上下文，可以多一些，但也要控制数量；细节层是备查信息，通常放在附录或折叠区域，不直接画在主图上。

为什么是七个？这是基于认知心理学的经验值。人在短时间内能记住的元素数量大约是五到九个，超过这个范围，理解效率会急剧下降。所以主图上的核心元素，我一般控制在七个以内。如果确实有更多核心元素，我会考虑拆成多张图，或者用分组的方式把相关元素打包成一个“超级元素”，需要的时候再展开。

支撑层的元素可以多一些，但也要有明确的组织方式。比如按功能分组、按层级排列、按数据流向串联。支撑层的作用是让核心层不孤立，读者能看到核心元素所处的上下文。细节层则是“按需展开”，比如某个服务的具体配置、某个接口的字段定义，这些信息不需要画在主图上，但可以在图旁边用表格或注释的方式提供。

3.3 布局选择：为什么你的图总是“看起来很乱”

布局是 diagram-design 中最考验功力的部分。同样的元素，不同的布局方式，可读性可能差十倍。我总结了几种常见的布局模式，以及它们适用的场景。

层级布局适合表达上下级关系，比如组织架构、系统分层、功能模块树。核心元素放在顶部或中心，下级元素依次展开。这种布局的阅读顺序是从上到下、从中心到边缘，符合大多数人的认知习惯。

流向布局适合表达过程或数据流，比如业务流程、数据管道、请求链路。元素按照时间或数据流动的方向排列，通常是从左到右或从上到下。这种布局的关键是保持流向的一致性，不要一会儿左一会儿右，读者会晕。

网络布局适合表达复杂的依赖关系，比如微服务调用关系、系统集成关系。元素之间的连线比较多，布局的难点在于减少交叉线。我的经验是：先把连接最多的元素放在中心，然后按照连接关系依次向外扩展，同时尽量让相关元素靠近。如果交叉线还是太多，可以考虑用颜色或线型区分不同的关系类型，或者拆成多张图。

分组布局适合表达模块化结构，比如功能分区、业务域划分。把相关元素放在同一个视觉容器里，用背景色或边框区分。这种布局的关键是分组要有逻辑，不能为了分组而分组。我通常按照“高内聚、低耦合”的原则来分组，把交互频繁的元素放在一组，组与组之间的连线尽量少。

3.4 连线设计：箭头不是越多越好

连线是图里最容易失控的元素。我见过一张图里几十条箭头交叉在一起，完全看不出谁连谁。连线设计的核心原则是：每一条线都要有明确的信息量。如果一条线不能告诉读者“这两个元素之间有关系”，那它就不应该存在。

我通常会把连线分成几类：强关系用实线粗箭头，表示核心调用或主要流向；弱关系用虚线细箭头，表示辅助调用或次要流向；双向关系用双向箭头或两条平行线，表示互相依赖；间接关系用虚线或不同颜色，表示通过中间层传递的关系。分类之后，图里的线虽然多，但读者能快速区分哪些是主要的、哪些是次要的。

另一个常见问题是：连线上的文字标注太多。我见过有人在箭头上写一整句话，结果箭头被文字撑得变形。我的做法是：连线上的文字只保留最核心的信息，比如接口名或数据格式，详细说明放在图旁边的表格里。如果确实需要标注很多信息，可以考虑用编号，然后在图下方列出编号对应的说明。

注意：连线交叉是不可避免的，但可以通过调整元素位置来减少。我的经验是：先把所有元素按照连接关系排布，然后手动微调位置，每调整一次就看一眼交叉线数量。这个过程可能需要反复几次，但最终效果值得。

4. 实操过程：从零开始设计一张架构图

4.1 需求梳理与信息收集

假设我现在要为一个模拟的电商系统设计一张架构图。第一步不是打开工具，而是打开一个空白文档，开始列信息。我会问自己几个问题：这个系统有哪些核心模块？模块之间怎么交互？数据存在哪里？外部依赖有哪些？部署方式是什么？

然后我把这些信息列成一个清单，大概长这样：

• 核心模块：用户服务、商品服务、订单服务、支付服务、库存服务
• 交互关系：用户服务调用订单服务、订单服务调用商品服务和库存服务、支付服务被订单服务调用
• 数据存储：用户库、商品库、订单库、库存库
• 外部依赖：支付网关、短信服务、物流服务
• 部署方式：容器化部署，按服务拆分

这个清单不需要很精确，但要把主要元素和关系覆盖到。列完之后，我会再问一遍：这些信息里，哪些是核心读者必须知道的？哪些是支撑信息？哪些是细节？然后按照核心层、支撑层、细节层进行分类。

4.2 结构设计与布局规划

信息分类完成之后，开始设计结构。我通常会在纸上画一个草图，确定大致的布局。对于这个电商系统，我选择分层布局：最上面是接入层（用户端、管理端），中间是服务层（各个微服务），下面是数据层（各个数据库），右侧是外部依赖（支付、短信、物流）。

服务层的布局是关键。我把订单服务放在中心，因为它连接了用户、商品、库存、支付四个服务。用户服务和商品服务放在左侧，库存服务和支付服务放在右侧。这样连线的时候，订单服务到其他服务的线都比较短，交叉也少。

数据层放在服务层下方，每个服务对应一个数据库，用垂直虚线连接。外部依赖放在右侧，用不同颜色的虚线连接，表示它们是外部系统，不受我们控制。

4.3 工具选择与绘制过程

工具选择上，如果这张图需要频繁更新，我会优先考虑文本化工具。比如用 Mermaid 的 flowchart 语法，把结构定义写成文本：

flowchart TD A[用户端] --> B[用户服务] A --> C[商品服务] A --> D[订单服务] D --> C D --> E[库存服务] D --> F[支付服务] F --> G[支付网关] D --> H[短信服务] E --> I[物流服务] B --> J[用户库] C --> K[商品库] D --> L[订单库] E --> M[库存库]

这段文本定义好之后，渲染出来的图就是结构化的。如果系统变了，比如新增了一个服务，只需要改几行文本，图自动更新。这种方式特别适合放在文档里，因为文档本身也是文本，图和文档可以一起维护。

如果这张图需要精细的视觉设计，比如放在 PPT 里给高层汇报，我会用图形工具手动绘制。但即使手动绘制，我也会先把上面的文本定义作为“结构底稿”，确保结构关系不会画错。手动绘制的时候，我会严格按照之前定义的图例规范：矩形代表服务、圆柱代表数据库、实线箭头代表同步调用、虚线箭头代表异步消息、不同颜色区分不同的业务域。

4.4 视觉优化与细节调整

图基本画完之后，进入视觉优化阶段。这个阶段我主要做几件事：统一字体和字号、调整颜色对比度、对齐元素、检查连线交叉、添加图例和标注。

字体和字号方面，我通常只用两种字号：标题用大一号，正文用小一号。字体统一用无衬线字体，因为屏幕阅读更清晰。颜色方面，我通常用三到四种主色，分别代表不同的业务域或层级，避免颜色过多导致视觉混乱。对齐方面，我会用工具的对齐功能，确保同一层级的元素左对齐或居中对齐，同一列的元素顶对齐或底对齐。

连线交叉是视觉优化中最耗时的部分。我的做法是：先看哪些连线是必须的，哪些可以合并或省略；然后调整元素位置，尽量让相关元素靠近；最后如果还有交叉，就用“跳线”或不同颜色区分。这个过程可能需要反复几次，但每减少一条交叉线，可读性就提升一点。

4.5 交付与维护

图完成之后，交付方式也很重要。如果是放在文档里，我会同时提供图片和源文件。图片用于快速查看，源文件用于后续修改。如果是文本化工具生成的图，我会把源文本也放在文档里，方便别人直接修改。

维护方面，我会在图的角落标注“最后更新时间”和“对应系统版本”。如果系统有重大变更，我会同步更新图，并在更新记录里注明改了什么。这样做的好处是，读者知道这张图是不是最新的，需不需要找你要更新版本。

实操心得：我习惯在项目仓库里建一个diagrams目录，所有图的源文件都放在里面，和代码一起版本控制。每次系统变更，代码 review 的时候顺便看一眼图要不要更新。这个习惯坚持下来之后，图过期的概率大大降低。

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

5.1 图太复杂没人看，怎么办

这是最常见的问题。图太复杂的原因通常有两个：一是信息没有分层，所有细节都画在主图上；二是布局没有优化，元素和连线随意摆放。解决方法：先做信息分层，把细节移到附录或折叠区域；然后优化布局，按照核心层、支撑层、细节层的顺序重新排列元素；最后精简连线，去掉不必要的箭头和标注。

如果做完这些还是复杂，那就考虑拆图。一张图只讲一件事，多张图组合起来讲一个完整的故事。我见过一个系统架构被拆成五张图：总体架构、服务调用关系、数据流向、部署拓扑、外部依赖。每张图都很清晰，合起来又很完整。

5.2 图更新了，但别人看的还是旧版

这个问题本质上是版本管理问题。我的做法是：图的源文件和文档放在同一个版本控制体系里，每次更新都提交变更记录。同时在图的显眼位置标注版本号和更新时间。如果图是放在共享文档里的，我会在文档开头加一个“更新日志”，记录每次修改的内容和时间。

另一个技巧是：给图加一个“有效期”。比如在图的角落写“本图基于系统 v2.3 版本，有效期至 v2.5 版本”。这样读者知道什么时候该找你要新图。如果系统迭代很快，可以考虑用文本化工具自动生成图，每次系统变更自动触发图更新，彻底解决同步问题。

5.3 颜色用了很多，但看起来还是很乱

颜色多不等于视觉丰富，反而可能造成视觉噪音。我的经验是：主色不超过三种，辅助色不超过两种。主色用于区分核心模块或层级，辅助色用于标注重点或异常。颜色选择上，尽量用同一色系的深浅变化，而不是红绿蓝紫随便用。

另一个常见问题是：颜色没有语义。比如红色有时候表示错误，有时候表示重点，有时候只是装饰。这种不一致会让读者困惑。我的做法是：定义一套颜色语义规范，比如红色只用于表示风险或异常，绿色只用于表示正常或成功，蓝色用于表示核心模块，灰色用于表示辅助信息。规范定下来之后，所有图都严格遵守。

5.4 文本化工具画出来的图太丑，怎么办

文本化工具的优势是结构清晰、易于维护，劣势是视觉定制能力有限。我的做法是：结构用文本化工具，视觉用图形工具。先用文本化工具定义结构，确保逻辑正确；然后把结构导出或参考，用图形工具重新绘制视觉版本。这样既保证了结构的可维护性，又满足了视觉的定制需求。

如果不想用两个工具，也可以选择支持主题定制的文本化工具。比如 Mermaid 支持自定义主题，可以调整颜色、字体、间距等参数。虽然不如图形工具灵活，但通过合理的主题配置，也能达到不错的视觉效果。

5.5 常见问题速查表

6. 工具选型与个人实践体会

6.1 文本化工具 vs 图形化工具：怎么选

文本化工具和图形化工具各有优劣，选择的关键在于图的更新频率和维护方式。如果图需要频繁更新，且更新内容主要是结构关系，那文本化工具更合适。如果图需要精细的视觉设计，且更新频率不高，那图形化工具更合适。

我个人的做法是：架构图、流程图、时序图用文本化工具，业务蓝图、汇报材料、品牌相关图用图形化工具。文本化工具里，Mermaid 适合快速绘制和文档集成，PlantUML 适合更复杂的 UML 图，Graphviz 适合自动布局的复杂网络图。图形化工具里，我倾向于选择支持图层和组件的工具，这样可以把常用元素做成组件库，提高绘制效率。

6.2 我踩过的三个坑

第一个坑：过度追求视觉完美。早期我花大量时间调整对齐、颜色、字体，结果图是好看，但内容没讲清楚。后来我明白，图的第一目标是传递信息，第二目标才是视觉美观。信息不清楚，再好看也没用。

第二个坑：图例规范太复杂。我曾经定义了一套包含二十多种形状和线型的图例规范，结果自己都记不住，每次画图都要翻规范。后来简化到五种基本元素，效率大幅提升，读者也更容易理解。

第三个坑：图更新不及时。有一次系统架构变了，图没更新，结果新来的同事按照旧图理解系统，排查问题时走了弯路。从那以后，我把图纳入版本控制，每次系统变更都同步更新图，再也没出现过这个问题。

6.3 一个让我受益匪浅的习惯

我现在画任何图之前，都会先写一段图的说明文字，大概一百字左右，讲清楚这张图要表达什么、给谁看、核心信息是什么。这段文字不放在图里，而是放在图的旁边或文档里。写完之后再开始画图，画的过程中不断对照这段文字，确保图没有偏离目标。

这个习惯看起来简单，但效果非常好。它强迫我在动手之前想清楚目的，避免画到一半发现方向错了。而且这段文字本身也可以作为图的“摘要”，读者看文字就能快速判断这张图是不是他需要的，不需要打开图仔细看。

6.4 后续可以扩展的方向

diagram-design 这个主题往下挖，还有很多可以展开的方向。比如自动化图表生成：从代码注释、接口定义、数据库 schema 自动生成架构图或 ER 图，彻底解决图与代码不同步的问题。再比如交互式图表：图不是静态的，点击某个模块可以展开细节，或者跳转到对应的文档。还有图表可访问性：考虑色盲用户、屏幕阅读器用户的需求，让图对所有人都友好。

这些方向我都在陆续尝试，有些已经用在项目里，效果不错。如果你也在做类似的事情，欢迎交流。图这件事，看起来是小事，但做好了，能省掉很多沟通成本，也能让团队的知识沉淀更扎实。