1. 从一张草图到一套系统：diagram-design 到底在解决什么问题
第一次听到 “diagram-design” 这个词，很多人会下意识觉得它只是“画图”的另一种说法。但真正在项目里被图表折磨过的人知道，画图只是冰山一角，水面下藏着的是一整套关于信息结构、视觉语言和协作流程的设计系统。我最早接触这个概念，是在一个跨平台系统的重构项目里，当时团队有五个人，每个人画出来的架构图风格都不一样：有人用圆角矩形，有人用直角；有人把数据库画成圆柱，有人画成方块；连线有的带箭头，有的不带。结果就是，一张图给不同的人看，理解出来的意思能差出十万八千里。
diagram-design 要解决的，正是这种“图不同源、意不同解”的问题。它不是一个具体的软件，也不是某个绘图库的名字，而是一套围绕图表展开的设计方法论——从图表的语义定义、视觉规范，到绘制流程、评审机制，再到最终的交付与维护。你可以把它理解成“图表的 Design System”：就像 UI 设计有组件库和设计规范一样，图表也需要有自己的“组件库”和“规范”。
这套东西适合谁？如果你只是偶尔画一张流程图发在聊天群里，那可能用不上。但只要你满足下面任意一条，diagram-design 就值得你花时间研究：你需要反复向不同角色（产品、开发、测试、运维）解释同一套系统架构；你的项目里有超过 10 张需要长期维护的图表；你所在的团队超过 3 个人需要协同画图；你曾经因为一张图理解偏差导致过返工。这些场景下，图表不再是“辅助说明”，而是“核心交付物”的一部分，它的设计质量直接影响沟通效率和项目质量。
我个人的体会是，diagram-design 的核心价值不在于“画得好看”，而在于“画得一致、画得可维护、画得可验证”。好看是结果，不是目标。目标是让一张图在半年后、换了一个人来看，依然能准确传达同样的信息。这背后涉及三个层面的设计：语义层（图上的每个元素代表什么）、视觉层（每个元素长什么样）、流程层（谁在什么时候怎么画、怎么改、怎么审）。接下来我会把这套东西拆开，结合我在实际项目里踩过的坑和总结出来的方法，一层一层讲清楚。
2. 语义先行：把“图”翻译成“模型”再翻译回“图”
2.1 为什么直接画图一定会乱
大多数人画图的习惯是：打开工具，拖一个方框，写上“用户服务”，再拖一个方框，写上“订单服务”，然后连线。这个过程看起来自然，但它有一个致命缺陷——你在画图的同时在做设计决策，而且这些决策是隐式的、不可追溯的。比如你画了一个方框代表“用户服务”，但你没有定义这个方框的语义：它是一个部署单元？一个逻辑模块？一个业务能力？还是一个团队边界？不同的人看到这个方框，会根据自己的经验去填充语义，偏差就此产生。
我在一个模拟项目里做过实验：让五个人根据同一段文字描述画架构图，结果五张图里出现了三种不同的方框含义、两种不同的连线语义、四种不同的层级划分。这不是因为他们不专业，而是因为文字描述本身没有强制语义，而画图工具也没有强制语义。diagram-design 的第一个原则就是：先定义语义模型，再画图。图只是模型的一种视图，模型才是唯一真相源。
2.2 定义图表的“元模型”
所谓元模型，就是“描述模型的模型”。听起来很绕，其实很简单：你需要先规定，在你的图表体系里，允许出现哪些类型的元素，每种元素代表什么，元素之间允许存在哪些关系。这就像给图表制定一套“语法”。
以常见的系统架构图为例，我通常会定义下面这几类元素和关系：
| 元素类型 | 语义定义 | 视觉表现 | 允许的关系 |
|---|---|---|---|
| 服务 | 一个可独立部署的运行单元 | 圆角矩形，蓝色填充 | 调用、依赖、发布事件 |
| 数据库 | 持久化存储 | 圆柱体，灰色填充 | 被读写、同步 |
| 消息队列 | 异步通信通道 | 菱形，橙色填充 | 生产、消费 |
| 外部系统 | 不在本系统控制范围内的实体 | 虚线矩形，白色填充 | 调用、被调用 |
| 用户角色 | 与系统交互的人或角色 | 小人图标，绿色 | 触发、接收 |
| 调用关系 | 同步请求-响应 | 实线箭头 | 从调用方指向被调用方 |
| 事件关系 | 异步消息 | 虚线箭头 | 从生产方指向消费方 |
这张表看起来简单，但它是整个 diagram-design 的基石。有了它，任何人画图时都必须从这张表里选元素，不能随意发明。这就消除了“同一个东西在不同图里长得不一样”的问题。更重要的是，这张表本身就是一份沟通文档——当有人问“这个菱形是什么意思”时，你不需要口头解释，直接指这张表就行。
注意：元模型不是越细越好。我见过一个团队定义了 30 多种元素类型，结果画图的人记不住，每次都要翻文档，效率反而下降。我的经验是，一个项目里的元素类型控制在 8 到 12 种之间比较合适，超过 15 种就需要考虑拆分图表类型了。
2.3 从模型到视图的映射规则
定义了元模型之后，下一步是规定“什么情况下画什么图”。同一个模型可以有不同的视图，就像同一栋建筑可以有平面图、立面图、剖面图。diagram-design 要求你明确：每种视图的用途是什么、包含哪些元素、隐藏哪些元素、用什么布局。
我通常会把视图分成三类：
- 上下文视图：只画系统边界和外部交互，不画内部细节。用于向非技术人员解释“这个系统是干什么的”。
- 容器视图：画系统内部的主要容器（服务、数据库、队列等），以及它们之间的关系。用于技术方案评审。
- 组件视图：深入某个容器内部，画组件和模块。用于开发人员理解代码结构。
这三类视图对应不同的受众和不同的详细程度。关键规则是：低详细程度的视图不能包含高详细程度的元素。比如上下文视图里不能出现数据库，因为数据库是内部细节。这条规则听起来理所当然，但实际画图时很容易违反——因为你知道数据库的存在，就忍不住想画出来。一旦违反，视图的受众就会困惑：“这个数据库是外部系统还是内部系统？”
2.4 语义一致性的检查清单
在完成语义定义后，我建议用下面这个清单做一次自检：
- 每个元素类型是否都有明确的、无歧义的定义？
- 是否存在两个元素类型语义重叠的情况？（比如“服务”和“模块”）
- 每种关系是否都有方向性定义？
- 是否规定了哪些关系可以跨层级？（比如组件能否直接调用另一个容器的数据库）
- 是否规定了元素命名的规则？（比如统一用“XX服务”还是“XX Service”）
- 是否规定了废弃元素的处理方式？（比如一个服务下线了，图上是删除还是标记为灰色）
这六个问题如果都能回答清楚，语义层就基本稳固了。我踩过最大的坑是第 4 条：早期没有规定跨层级关系，结果有人画了一张图，组件直接连到了另一个容器的数据库，评审时吵了半天——有人说这表示直接访问，有人说这表示通过服务访问。后来我们明确规定：组件只能通过本容器的服务访问外部，不能直接连外部数据库，这类争议就消失了。
3. 视觉规范：让每一张图都“长一样”
3.1 视觉规范不是审美问题，是效率问题
很多人觉得视觉规范是设计师的事，跟工程师无关。但在 diagram-design 里，视觉规范是效率工具。原因很简单：当所有图表的视觉语言一致时，读者不需要重新学习“这张图的箭头是什么意思”，可以直接把注意力放在内容上。这就像交通标志——如果每个城市的红灯形状都不一样，司机早就崩溃了。
视觉规范要解决的问题包括：颜色怎么用、形状怎么选、字体和字号怎么定、连线怎么画、布局怎么排。每一项都需要有明确的规则，而不是“看着顺眼就行”。
3.2 颜色：用色相区分类型，用明度区分层级
颜色是最容易被滥用的视觉元素。我见过一张图用了 12 种颜色，结果读者根本记不住哪种颜色代表什么。diagram-design 的颜色规则应该遵循“色相管类型，明度管层级”的原则。
具体来说：同一类型的元素用同一个色相。比如所有服务都用蓝色系，所有数据库都用灰色系，所有外部系统都用白色。然后，同一类型内部如果有层级差异，用明度区分。比如核心服务用深蓝，辅助服务用浅蓝。这样读者一眼就能看出“这些都是服务，但深浅不同表示重要性不同”。
下面是我在一个项目里实际使用的颜色规范：
| 元素类型 | 色相 | 填充色 | 边框色 | 文字色 |
|---|---|---|---|---|
| 核心服务 | 蓝 | #1E5AA8 | #0D3A6E | 白色 |
| 辅助服务 | 蓝 | #4A90D9 | #2C6BA8 | 白色 |
| 数据库 | 灰 | #6B7280 | #4B5563 | 白色 |
| 消息队列 | 橙 | #D97706 | #B45309 | 白色 |
| 外部系统 | 无 | #FFFFFF | #9CA3AF | #374151 |
| 用户角色 | 绿 | #059669 | #047857 | 白色 |
这套颜色用了不到 6 个色相，但足以区分所有元素类型。关键是，它不依赖颜色本身来传达信息——即使打印成黑白，明度差异依然能区分层级。这一点很重要，因为很多图表最终会被打印或截图，如果只靠色相区分，黑白打印后就全糊了。
提示：避免使用红色和绿色作为主要区分色，因为色盲人群无法区分。如果必须用，确保同时有形状或文字标签作为辅助区分。
3.3 形状：语义的视觉锚点
形状比颜色更容易被记住。圆形、矩形、菱形、圆柱体，每种形状都应该有固定的语义。在 diagram-design 里，形状的选择不是随意的，而是基于“这个元素在现实世界中是什么形态”的隐喻。
比如数据库用圆柱体，因为它隐喻“存储罐”；消息队列用菱形，因为它隐喻“中转站”；服务用圆角矩形，因为它隐喻“可替换的模块”。这些隐喻不是绝对的，但一旦选定，就要在整个项目里保持一致。
我建议在项目初期就确定一套形状规范，并且写进文档。下面是一个常见的形状-语义对照：
- 圆角矩形：可部署单元、服务、应用
- 直角矩形：逻辑模块、组件、包
- 圆柱体：数据库、存储、缓存
- 菱形：消息队列、事件总线、网关
- 平行四边形：外部系统、第三方服务
- 圆形：用户、角色、参与者
- 虚线矩形：边界、范围、分组
形状规范的关键是“不重叠”：一个形状只能代表一种语义。如果你用圆角矩形代表服务，就不能再用它代表模块。否则读者会混淆。
3.4 连线：方向、样式与标签
连线是图表里最容易被忽视的部分。很多人画连线就是“从 A 拉到 B”，不关心箭头方向、线型、标签。但在 diagram-design 里，连线承载了关系语义，必须严格规范。
我通常规定：
- 实线箭头：同步调用，箭头指向被调用方
- 虚线箭头：异步消息，箭头指向消费方
- 无箭头实线：关联关系，无方向性
- 带标签的连线：标签写在连线中间，用动词短语，如“读取”“写入”“发布”
连线的标签尤其重要。我见过太多图，连线没有标签，读者只能猜“这两个服务之间到底是什么关系”。是调用？是依赖？是数据同步？没有标签，图的信息量就少了一半。
还有一个细节：避免连线交叉。如果两张图之间连线太多，交叉严重，说明布局有问题，或者应该拆成两张图。连线交叉不仅影响美观，更影响可读性——读者会沿着错误的线去追踪关系。
3.5 字体与布局：被低估的细节
字体和布局是视觉规范里最“琐碎”的部分，但也是最能体现专业度的地方。我的建议是：
- 字体：统一使用无衬线字体，如系统默认的 sans-serif。避免使用多种字体。
- 字号：标题 16px，元素名称 14px，标签 12px。字号层级不超过 3 级。
- 对齐：所有元素对齐到网格，避免手动微调。
- 间距：元素之间的间距统一，通常为元素宽度的 1/4 到 1/2。
- 布局方向：统一从左到右或从上到下，不要混用。
这些规则看起来简单，但执行起来需要工具支持。我建议使用支持“对齐网格”和“样式复用”的绘图工具，这样每次新建元素时自动应用规范，而不是手动设置。
4. 流程设计：谁在什么时候画什么图
4.1 图表不是一个人的事
diagram-design 的第三个层面是流程。即使语义和视觉都定义好了，如果流程不对，图表依然会乱。最常见的流程问题是：一个人画图，其他人不参与，画完直接发出来。结果就是，画图的人觉得自己表达清楚了，看图的人觉得“这跟我理解的不一样”。
我在一个模拟项目里推行过“三方评审”流程：每张核心图表必须经过三类人评审——领域专家（确认语义正确）、实现者（确认技术可行）、消费者（确认能看懂）。这三类人缺一不可。领域专家确保图上的元素和关系符合业务逻辑；实现者确保图上的技术细节没有错误；消费者确保图的详细程度和表达方式适合他们的理解水平。
这个流程听起来很重，但实际执行下来，每张图的评审时间不超过 15 分钟。相比返工的成本，这 15 分钟花得非常值。
4.2 图表的生命周期管理
图表不是画完就完了。在项目进行过程中，系统会变化，图表也需要跟着变。如果没有生命周期管理，图表很快就会过时，而过时的图表比没有图表更危险——因为它会误导人。
我建议给每张图表定义明确的生命周期状态：
| 状态 | 含义 | 处理方式 |
|---|---|---|
| 草稿 | 正在绘制，未评审 | 不对外分享 |
| 已评审 | 通过三方评审，可对外 | 作为当前有效版本 |
| 已过期 | 系统已变化，图表未更新 | 标记为过期，不删除 |
| 已归档 | 系统已下线，图表保留 | 移入归档目录 |
关键规则是：图表必须和代码或文档一起更新。我通常会把图表源文件放在代码仓库里，和代码一起提交。这样每次代码变更时，评审者会看到图表是否也需要更新。如果图表没有更新，评审就不通过。
注意：不要删除过期图表。过期图表是历史记录，可以帮助后来的人理解“为什么当时这样设计”。删除过期图表等于丢失了设计决策的上下文。
4.3 工具选型：文本化还是图形化
工具选型是 diagram-design 里争议最大的部分。有人喜欢拖拽式工具（如某绘图软件），有人喜欢文本化工具（如某图表描述语言）。我的经验是：两者都需要，但用途不同。
拖拽式工具适合探索性画图——当你还不确定要画什么时，拖拽可以快速尝试不同布局。文本化工具适合确定性画图——当模型已经定义好，只需要生成视图时，文本化工具可以保证一致性和可维护性。
我通常的工作流是：先用拖拽工具画草图，确定布局和元素；然后把草图翻译成文本化描述，纳入版本控制；最后用文本化工具生成最终图表。这样既有探索的灵活性，又有维护的可靠性。
文本化工具还有一个好处：可以自动检查语义一致性。比如你可以写一个脚本，检查所有图表里是否出现了未定义的元素类型，或者是否出现了跨层级的非法关系。这种自动化检查在拖拽工具里很难实现。
4.4 协作规范：命名、版本与注释
协作画图时，命名和版本是最容易出问题的地方。我见过一个项目，同一个服务在三张图里有三个不同的名字：“用户服务”“User Service”“用户中心”。读者看到这三个名字，会以为是三个不同的东西。
diagram-design 要求：每个元素必须有唯一的标准名称，所有图表必须使用标准名称。标准名称应该来自一个统一的术语表，这个术语表由领域专家维护。画图时，从术语表里选名称，不能自己发明。
版本管理也很重要。我建议每张图表都有一个版本号，格式为“主版本.次版本”。主版本变更表示语义变化（比如新增了元素类型），次版本变更表示内容更新（比如新增了一个服务）。版本号写在图表标题下方，方便读者确认自己看的是哪个版本。
注释是另一个容易被忽视的细节。图表里应该允许添加注释，但注释必须有明确的格式和位置。我通常规定：注释用黄色便签样式，放在相关元素旁边，注释内容用完整句子，避免缩写。
5. 常见问题与排查技巧实录
5.1 图表太多，找不到想要的
这是最常见的问题。项目进行到中期，图表数量超过 20 张，每次找图都要翻半天。我的解决方法是：建立图表索引。索引是一个表格，包含图表名称、类型、版本、负责人、最后更新时间、链接。索引本身也纳入版本控制，每次新增或更新图表时同步更新索引。
索引的另一个好处是：可以快速发现“哪些图表过期了”。如果一张图表的最后更新时间是三个月前，而系统已经变了，那它很可能需要更新。
5.2 不同人对同一张图理解不同
这个问题通常源于语义定义不清晰。排查步骤是：
- 让每个人用自己的话描述图上的每个元素和关系。
- 对比描述，找出分歧点。
- 回到元模型，检查分歧点的定义是否模糊。
- 如果定义模糊，补充定义；如果定义清晰但有人理解错，补充示例。
我遇到过一次，两个人对“服务”的理解不同：一个人认为服务是部署单元，另一个人认为服务是逻辑模块。结果一张图里，有人画了 5 个服务，有人画了 3 个服务。后来我们在元模型里明确规定：服务是部署单元，逻辑模块用组件表示，问题就解决了。
5.3 图表更新不及时
这个问题的根源通常是流程问题，而不是态度问题。如果更新图表需要额外打开一个工具、手动调整布局、重新导出，那没人愿意做。我的解决方法是：把图表更新纳入代码提交流程。具体来说，图表源文件放在代码仓库里，每次代码变更时，如果涉及架构变化，必须在同一个提交里更新图表。CI 流程可以检查图表文件是否被修改，如果没有修改但代码涉及架构变化，CI 会发出警告。
这个方法的难点是“如何判断代码变更是否涉及架构变化”。我的经验是：不要试图自动化判断，而是靠代码评审。评审者如果发现架构变化但图表没更新，就要求补充。时间长了，团队会形成习惯。
5.4 图表风格不统一
即使有了视觉规范，不同人画出来的图还是会有差异。常见差异包括：圆角半径不同、箭头样式不同、间距不同。解决方法是：提供模板。模板里预置了所有样式，画图时从模板复制元素，而不是从头创建。模板本身也纳入版本控制，每次规范更新时同步更新模板。
我还会定期做“图表走查”：随机抽取几张图，对照视觉规范检查。走查结果不用于考核，只用于发现规范本身的漏洞。比如如果发现很多人都在用同一种“非规范”样式，那可能说明规范需要更新。
5.5 常见问题速查表
| 问题 | 可能原因 | 排查方法 | 解决方案 |
|---|---|---|---|
| 图表太多找不到 | 缺少索引 | 检查是否有图表索引 | 建立索引并纳入版本控制 |
| 理解不一致 | 语义定义模糊 | 让多人描述同一张图 | 补充元模型定义和示例 |
| 更新不及时 | 流程太重 | 检查更新步骤是否超过 3 步 | 纳入代码提交流程 |
| 风格不统一 | 缺少模板 | 对比多张图的样式 | 提供模板并定期走查 |
| 连线交叉严重 | 布局不合理 | 检查元素排列 | 重新布局或拆图 |
| 颜色难以区分 | 色相过多 | 检查颜色数量 | 减少色相，增加明度差异 |
| 打印后看不清 | 依赖颜色 | 黑白打印测试 | 增加形状和文字区分 |
5.6 独家避坑技巧
最后分享几个我在实际项目里总结的避坑技巧，这些在常规文档里很少提到：
技巧一：先画草图，再定规范。不要一开始就花大量时间定义元模型和视觉规范。先画几张草图，看看实际需要哪些元素和关系，然后再提炼规范。规范是从实践中来的，不是凭空想出来的。
技巧二：让消费者参与规范制定。画图的人往往高估读者的理解能力。让实际看图的人参与规范制定，他们会告诉你哪些地方看不懂、哪些地方容易混淆。这比画图的人自己猜要准确得多。
技巧三：定期清理过期图表。过期图表不删除，但必须标记。我通常会在过期图表的标题旁加一个“已过期”标签，并在索引里注明替代图表。这样读者看到过期图表时，知道去看新版本。
技巧四：用真实数据测试图表。画完图后，用真实的系统数据测试一遍：图上的每个服务是否真实存在？每个关系是否真实发生？每个标签是否准确？我见过太多图，画的时候觉得没问题，一对照真实系统就发现漏了一个服务或者多了一个关系。
技巧五：保持图表数量可控。一个项目的核心图表控制在 10 到 15 张之间比较合适。超过 20 张，维护成本会急剧上升。如果确实需要更多图表，考虑拆分成多个子项目，每个子项目有自己的图表集。
这些技巧的核心逻辑是：diagram-design 不是一次性工作，而是持续的过程。规范会变，系统会变，人也会变。重要的是建立一套机制，让图表能够跟着变化，而不是变成一堆过时的文档。我在实际项目里最大的体会是，图表的价值不在于画得多漂亮，而在于它是否被真正使用。一张被频繁引用的草图，比一张无人问津的精美图表有价值得多。所以，不要追求完美，追求可用。先让图表被用起来，再逐步优化规范。这个顺序反了，规范就会变成负担。
