在技术评审和新人培训里，我见过太多图的“事故现场”。负责某跨平台系统的同学台上讲得慷慨激昂，投到大屏上的架构图却让人完全看不懂：连线绕成毛线团，节点尺寸忽大忽小，颜色像盲盒开出来的一样，关键链路没有高亮，依赖方向全靠猜。这不是某一个团队的毛病，而是大量个人项目和团队文档的通病。diagram-design 看起来只是“画图”这件事，本质上解决的是信息传递效率：让一个复杂系统在三十秒内被人看懂主干，让新人十分钟内定位到要找的模块，让评审会上不再因为一张图产生三种理解。
这篇文章不打算教你某个具体绘图软件怎么点按钮，而是把 diagram-design 当成一个可沉淀、可复用、可评审的设计项目来讲。内容包括设计前的思考方式、节点和关系的梳理方法、布局与连线的关键参数、一套可以直接抄作业的视觉规范，以及我踩过的坑和排查思路。适合正在写技术方案、做系统设计、维护项目文档，或者辅导新人看架构图的开发者和技术负责人参考。就算你目前只画过简单的流程图，按这套思路走，也能把图的质量拉高一大截。
1. 先把Diagram这件事想清楚：它到底在解决什么问题
1.1 图的第一价值是压缩认知差
动手开画之前，先回答一个最基本的问题：我们为什么需要图？
文字描述一个“五节点、六条边”的关系，需要读两遍甚至三遍才能理清。而一张结构到位的图，扫一眼就能抓住主干。图的核心价值不是美观，而是压缩认知差：让不同背景的读者在最短时间内达成一致理解。
实际工作中，Diagram 承担的任务通常是三件事。第一件是降低沟通成本，评审会、跨部门对接、新人答疑，一张图抵过千行文字。第二件是暴露逻辑漏洞，画图会强迫你把每个节点、每条连接线都落实，平时口头讲述能蒙混过去的模糊地带，落到图上就必然显形。第三件是形成公共语义，团队维护同一套图的标准，讨论“网关挂了会怎样”这类问题时，每个人脑中的拓扑是一致的，才不会各说各话。
这一点极其重要。因为市面上大多数绘图工具只是帮助你表达，真正决定图的质量的，是你对内容本身的理解程度。工具不背锅，逻辑不清才是图乱的根源。
1.2 两类典型误区：把图当文案、把图当画作
这两类错误我在评审里见过太多次。
第一类，把图当成详细文档。某流程本来只有三个判断节点，硬是每个节点都附上一大段描述文字，把所有例外情况、参数细节全部塞进节点框。结果图上密密麻麻全是字，节点倒是齐了，信息反而没法消化。图是索引，不是全文；细节应该放文档或注释层，而不是霸占节点。
第二类，把图当成插画比赛。阴影、渐变、立体效果、像素级图标，什么东西炫就上什么。画完一看确实漂亮，但你问读者“谁依赖谁、哪里会失败、主链路是什么”，他们答不上来。视觉层次一旦被装饰淹没，信息就失去了优先级。
这两种模式，最终都会导致同一个结果：图没人看，没人维护，半年之后沦为文档废墟。这也是我写这篇文章的出发点——希望你把 diagram-design 当成一个设计流程来对待，而不是把它当成一次性的“画图任务”。
2. 高质量Diagram的完整设计拆解
2.1 第一步：先梳理节点与关系，而不是先开画布
大多数人画图的姿势是：打开画布，拉几个框，连线，发现不对，再拉框，再连线。最后图上全是半途而废的残留物。我的习惯完全相反：先不开画布，只用文档工具列清单。
以某跨平台系统为例，我想描述它的整体架构，第一件事是列出所有对象：
- 客户端（三个平台形态）
- 接入层
- 网关服务
- 核心业务服务（可继续拆成用户、订单、消息三个子模块）
- 缓存集群
- 消息队列
- 数据库
- 外部依赖（第三方开放接口）
- 日志与监控组件
列完清单后，每个对象打三个标签。类型：是系统、服务、模块、数据存储，还是人的角色？维度：属于接入层、应用层、基础设施层中的哪一层？权属：是当前项目自己负责的，还是依赖别人的，或是被外部依赖的？
标签的意义是为后面的层级和配色做准备。如果一个对象连类型和归属都说不清，那画上图也一定会造成歧义。
接下来画关系。关系的语言越简单越好，我基本只用四类：
- 依赖：A 需要调用 B 才能完成功能，用带箭头的实线表达。
- 数据流：A 向 B 发送数据，重点在数据本身，用虚线或带特定颜色的线表达。
- 时序调用：强调业务场景下的先后顺序，用于排查超时和链路问题。
- 泛化归属：A 是 B 的一种或一部分，用空心箭头或包含结构表达。
这一步是纯逻辑工作，先别着急画线。把关系逐条列成表格，这是整张图真正的骨架。
| 源节点 | 目标节点 | 关系类型 | 触发条件 / 备注 |
|---|---|---|---|
| 客户端 | 接入层 | 依赖 | 首次启动时建立连接 |
| 接入层 | 网关 | 依赖 | 统一鉴权后转发 |
| 网关 | 核心业务服务 | 依赖 | 按路由分发 |
| 业务服务 | 缓存集群 | 数据流 | 读多写少场景走缓存 |
很多图乱成一团，不是因为线条画得不直，而是因为关系表根本没梳理过。上来直接连线，画一笔想一笔，最后连自己都要顺着线走三遍才认得出，读者怎么可能看得懂。
2.2 第二步：选图类型，别让形式拖累内容
分析完节点和关系之后，要判断该用哪种图。常见类型有这么几种：
- 流程图：有明确的开始、判断、分支、结束，适合描述业务操作流程。
- 架构图：强调层级、从属、分区，适合表达系统结构。
- 时序图：强调消息先后顺序和交互过程，适合定位超时、排查链路。
- 状态图：强调状态与事件，适合有限状态机，比如订单状态的流转。
- 鱼骨图与思维导图：强调拆解和归因，适合做问题分析和范围梳理。
问题在于，多数实际场景用最简单的有向图就够了，不需要套任何特殊图型。把复杂关系硬塞进三明治一样的架构框里，或者把所有调用关系画成流程图，都会逼着读者强行脑补。我的选型原则就三条：主线是步骤，选流程类；主线是结构层级，选架构类；主线是交互时序，选时序类。如果发现一张图又像流程又像架构，说明内容还没想清楚，先拆视图，别硬画一张四不像。
2.3 第三步：布局与层级，决定可读性的关键参数
到了这一步，才真正开始考虑视觉。先说层级。
架构图的典型布局是自上而下分成入口层、业务层、应用层、数据层。流程图的典型布局是自左而右画主流程，分支自上而下展开。层级的作用是给读者一个默认的阅读路径，让视线有方向感。
几个参数是我反复验证后觉得最有效的：
- 主流程方向统一：从上到下，或从左到右，二选一，不要在一个大图里混用两种主方向。
- 节点间距：主流程相邻节点间距建议不小于 48px，分支与分支间距至少保持 24px。间距太小，视觉会糊在一起，读者分不清模块边界。
- 连接线走向：尽量走直角，同一层级之间避免交叉。交叉线是让图显乱的最大原因，宁可适当拉大间距、调整节点排列顺序，也要减少交叉。
- 对齐方式：所有同层节点中心对齐到同一根水平线或垂直线上。手拖是凌乱的最常见来源，开启吸附网格是基本操作。
如果你觉得这些数字太细，可以这么理解：布局的目标是让读者不看连线也能大致猜出结构，看了连线之后更加确定。如果读者需要在线与线之间“走迷宫”，那布局就是失败的。
2.4 第四步：连接线的语义化与颜色编码
节点解决“有哪些东西”，连接线解决“它们之间什么关系”。连接线最容易犯的错，是全程一种样式、一个粗细。读者只能看到密密麻麻的线，却分不清哪些是主链路的调用，哪些是旁路的数据同步，哪些是异常情况才会触发的路径。
我给连接线定义了一套语义：
- 普通依赖线：1px 或 1.25px，灰色或中性色，不抢注意力。
- 关键链路：2px 到 3px，用强调色，整条链路从起点到终点统一加粗。
- 异步关系：虚线表达，比如消息队列的生产消费。
- 异常路径：红色，只有在错误或降级场景才会走。
颜色编码和线型语义一旦固定，就要在全图范围内保持一致。半路改方案是大忌。我见过一张图里虚线一会儿表示异步、一会儿表示历史数据过期，读者看到最后只能放弃理解。所以要在图的左下角或右下角放一个图例，哪怕图很小，图例也能让新读者快速了解约定。
3. 实操：从零落地一套diagram-design设计规范
3.1 标准化形状与线型，先从“标准件”做起
这套方法来自前端组件库的思路：把常用的视觉元素固化成标准件，用时直接拼装，而不是每次重新发明。
节点形状可以按语义约定：
- 矩形：通用模块或服务。
- 圆角矩形：业务活动或用户动作。
- 菱形：判断分支。
- 扁六边形：外部系统或依赖方。
- 圆柱体：数据存储。
这套约定不需要多复杂，但必须落实到团队里的每一张图。很多项目的问题是每张图都由不同人画，形状含义完全随机：这个人的矩形代表模块，下个人的矩形代表操作。图与图之间无法复用，更无法横向对比。固定形状体系之后，团队里任何一个人看到菱形就知道是判断，看到圆柱体就知道是存储，不用重新解读。
3.2 配色体系与使用比例，别让重点沉没在色彩里
颜色在图中承载两个职责：区分类型、强调重点。但在实际图里，颜色最常被滥用。
我给一套典型系统图推荐过这样的配色逻辑：
- 主体模块：中性灰蓝色系，饱和度低，大面积使用不刺眼。
- 核心链路：一个强调色，比如偏橙或偏蓝的亮色，只用在主干上。
- 警示异常：红色，限定在故障点、降级路径。
- 分组背景：极浅的灰色或对应分区色，用于泳道和区域框。
关键参数是强调色的覆盖面积。我一般控制在全图面积 10% 以内，最多不超过 15%。如果一张图里三成区域都是高亮色，那等于没有重点。读者会习惯性地忽略所有颜色信息。
更需要警惕的是彩虹图禁忌：一个模块一个色，一条链路一个色，最终整张图花花绿绿。颜色一旦过度离散化，就失去了编码意义。颜色应该表达“类”，而不是表达“个体”。
3.3 文字、间距与图例
图里的文字是为定位服务的，不是为阅读服务的。节点内文字尽量控制在 16 字以内，超过这个量，要么说明节点拆得太大，要么说明文案过度浓缩。实在放不下，应该用注释层补充，而不是把节点框拉得越来越大。
字号参考比例：图标题 16 至 20px，节点内容 12 至 14px，注释说明 10 至 12px。注意这里说的是导出尺寸还是编辑尺寸需要统一设定，否则换台电脑打开比例就乱。适配显示器就是消费者视角看，字体缩放到 80% 或 90% 时仍然可读。
图例不是可有可无的东西。哪怕是团队内部使用的图，半年后回来维护的人也可能不是你本人。图例里写明：实线=同步依赖，虚线=异步消息，红色=异常路径，蓝色粗线=关键链路，菱形=判断。这样图才具备自解释能力，不依赖作者在场。
3.4 图层管理：背景层、内容层、标注层
复杂一点的图，我会明确分三个图层来管理。
背景层放分区容器：泳道框、区域名、灰色底色区块。背景层的作用是划清地界，让读者第一时间知道“这里属于网关区，那里属于业务区”。
内容层放节点、连接线，这是图的主体，所有关键信息都在这一层。
标注层放补充说明：某个接口超时时间的备注、某个模块的未来改造点、TODO 标记、评审问题记录。这些信息如果混进内容层，会让正文变得嘈杂；独立放在标注层，就可以在评审后整体清除，不影响图的主体。
图层管理的价值在于，清晰分离“稳定结构”和“临时信息”。正文结构几个月不变，标注每周都在更新。分层的图，维护成本会低非常多。
3.5 一套可以直接抄作业的五步绘制流程
把前面所有原则串起来，我落地一张图的标准流程是这样的：
- 列清单：把所有对象用文本列出来，打上类型、维度、权属三类标签。
- 列关系表：逐条写下节点间的关系，只描述逻辑，不画图。
- 定主路径：找出从入口到核心结果的最关键链路，这条链路必须高亮。
- 按层级摆布局：先放背景区域框，再放节点，最后连线。连线时主动调整顺序以规避交叉。
- 做视觉统一：套用团队规范检查形状、颜色、线宽、字号、图例，最后导出。
这套流程里，前两步占比最大，也最容易被人跳过。很多人一上来就做第三步，跳过了逻辑梳理，结果就是反复返工。正确的顺序能让你少走弯路。
4. 工具选型与协作提速，让Diagram成为团队资产
4.1 选工具之前，先对照这五个检查点
市面上的绘图工具五花八门，有在线白板类、桌面客户端类、还有代码生成类。我不推荐具体某款，因为需求差别太大，但选型前，可以拿五个检查点过一遍：
- 协作能力：多人能不能同时编辑同一张图？改动是不是实时可见？
- 数据可移植：源文件能不能导出标准格式？导出的图片清不清晰？
- 批量能力：有没有模板库？能不能批量对齐、批量改样式？
- 版本管理：能不能回滚到历史版本？有没有操作记录？
- 键盘效率：对齐、分布、微调这些常用操作，能不能脱离鼠标完成？
团队规模小、单次交付，随便选个在线白板都行。团队需要长期维护几十张架构图时，必须考虑模板化和版本管理能力，这对后期的影响比想象中大得多。
4.2 模板化与源文件管理
团队协作里，比画图技巧更影响效率的是规范落地的机制。我建议团队维护两套模板：一套是空白规范模板，包含预设的图层、配色、图例，直接用于新图；另一套是季度评审模板，包含统一的标题栏、日期、版本号、责任人信息。
源文件的存储同样重要。导出的图片只用于展示和汇报，永远不要直接用图片当协作源文件。任何改动都应该发生在源文件上。以图片形式在群里传来传去，最后一定会出现“你改的版本和我改的版本混在一起”的灾难。文件名建议带上项目代号和日期，例如 arch-core-v2-202504，避免一堆文件都叫“最终版”。
4.3 导出与分享的几个细节
导出图片时，最常遇到两个问题：模糊和断截。
模糊问题的根源是分辨率不够。架构图需要放大看细节，导出时要选择矢量格式，或在位图格式里设置足够高的缩放倍率。不要用默认尺寸直接导出，一定要放大到 150% 以上，最好导出后自己缩到 50% 再检查一遍文字可读性。
断截问题的根源是画布边界设置错误。很多工具默认按内容边界导出，但边界附近如果有阴影或外发光效果，就会被截掉。导出前手动设置边距，至少留出画布四周的余量。
分享链接时，记得设置好权限。内部评审用可评论权限，外部评审用只读权限。不然客户截图里出现一堆光标和批注气泡，体验很差。
5. 常见问题与排查技巧实录
5.1 图“看着乱”的排查步骤
收到最多的反馈就是“这图看着乱”。但“乱”是个模糊词，不拆解就无从下手。我一般按固定顺序排查。
第一步，关掉所有颜色，只看黑白灰。如果黑白灰状态下结构仍然清晰，问题出在配色；如果黑白灰状态下已分不清边界，那就是布局和层级的问题。
第二步，把所有连接线交叉点标出来。交叉点多的区域，优先调整节点左右顺序和纵向间距，目标是交叉数降到最低。
第三步，检查节点是否对齐。手动拖出来的节点很少严格对齐，直接用对齐工具一键处理，视觉立刻干净很多。
第四步，问自己一个问题：谁来读这张图？如果是评审会上的架构师，重点应该放在分层和依赖；如果是新人的入职文档，重点应该放在模块职责和主链路。读者不同，内容的取舍完全不同。
5.2 图太长太宽，总是被截断
流程图特别容易画成横向一盘长蛇，架构图特别容易画成纵向一座高塔。前者在汇报时被屏幕宽度截断，后者在打印时超页。
处理思路有两个。第一个是改变主方向，把横向长蛇改成纵向分段，或者把纵向高塔改为横向分层，适配阅读载体。第二个是拆子图：主图只保留主干结构，把某一层的内部细节单独拆分出来放在附录或附加页面，用链接或编号关联。
一张图的信息密度应该像一篇文章的段落：每段有个明确主题，段落之间靠逻辑相连，而不是把所有字都堆在同一页。
5.3 多人协作下频繁被覆盖
多人同时编辑一张图，最怕的不是功能冲突，而是有人不小心拖动了大区域节点，导致整块布局错位，其他人基于错误布局继续改。这种事发生后往往要花半小时重新整理。
我的应对方式是约定编辑区：动某个模块之前，先在图上标注或口头知会队友；结构性调整和内容补充分开进行，不要在同一时间段里既挪布局又加节点。此外，协作工具的版本历史功能必须勤用，每次大改动前手动打一个版本标记，误操作后回滚也方便。
5.4 导出模糊、文字被拉伸
这个问题在 PPT 汇报场景里高发。图导出来放大后，文字边缘全是锯齿。解决方案我之前说过：导出矢量格式，或高倍率位图，不要用默认缩略图。另外要注意字体兼容性，有些工具在协作端字体缺失，会自动替代，导致导出后文字位置偏乱。团队里统一一种免费商用字体，可以大幅减少这种意外。
5.5 我自己的纠错习惯
最后分享一个我从屡次翻车经历里沉淀出来的习惯：画完图之后，把图缩小到 50% 看一眼，再放大到 200% 看一眼。50% 检查的是整体节奏和留白，200% 检查的是对齐与细节。如果两个尺度下都能瞬间抓住主干、找到入口节点，这张图就基本过关了。每次评审前，我都会用这套“双尺度检视法”把图过一遍，比对着原图反复找毛病高效很多。
diagram-design 这件事，做久了会发现一个规律：好的图很少是一遍画出来的，都是先搭对逻辑骨架，再慢慢打磨视觉。如果你看完这篇文章只带走一点，我希望是“先列表格、再连线、最后做美化”的顺序。这个顺序能帮你省掉大量返工时间，也能让团队里的每一张图都变成真正可以依赖的沟通工具。
