diagram-design是我给自己的一份技术文档整理工作起的项目代号，起因很简单：代码写得清楚，可一到画架构图、流程图、数据交互图，团队里就各显神通——有用白板拍照的，有用在线工具随手拖的，有靠代码生成但样式完全失控的。结果就是文档里的图五花八门，配色随缘、箭头乱飞、层次不明，新同事接手时盯着一张图看十分钟也不知道系统到底是怎么转的。

这个项目做的事情，就是把“画图”从一种即兴表达变成一套可复用、可维护、有参数标准的产出流程：从信息梳理、图表类型选择、布局与配色规范，到工具选型、实操落地、长期维护，完整走了一遍。整篇文章就是这次实践的总结，适合后端开发者、技术文档工程师、架构师，以及任何一个需要在方案里配图、在文档里讲清系统结构的人。

1. 图表设计的底层逻辑：先搞清楚图是给谁看的

1.1 图解的本质是降低认知成本，不是展示画技

很多团队把架构图画不好的原因，不是工具不行，而是没想明白一个问题：一张图的价值到底在哪里。

我的理解是，图表是信息压缩与认知减负的工具。人的视觉通道带宽很高，但工作记忆容量极有限。一张合格的系统图，应该让人在5秒内看出核心结构，30秒内理解主要模块之间的关系，3分钟内能顺着关键链路回答“某个请求到底经过了哪些服务”这类问题。如果一张图看完还得出动当事人逐段讲解，那这张图就已经失败了。

这里有个经常被误解的点。有人觉得图越复杂越显专业，于是一个系统图恨不得把所有表结构、所有接口、所有配置项全塞进去。结果就是节点叠节点、线缠线，视觉密度远超大脑处理上限。我自己踩过这个坑，一开始给某个模拟项目画重构方案图，把十几张真实接口关系全部画上去，最后图缩到50%都看不清字，评审会上没人看懂。后来删掉三分之二的细节，只保留模块边界、核心调用链和数据流转，整张图突然就“通”了。

地图是个很好的类比。地图不会把每一棵树都画出来，它只保留和导航相关的东西：路网、地名、水系、建筑轮廓。多余的信息不是帮助，是噪声。架构图也一样，画什么是取舍，不画什么也是设计。

1.2 同一个系统，可以有三张完全不同的图

图表设计的第一步，不是打开工具，而是回答三个问题：这张图给谁看，看什么，看完要做什么。

我给“diagram-design”定了个原则：不允许用一张图应付所有场景。同一个订单系统，我至少要画三版：

• 面向开发人员的版本：关注模块划分、服务间调用关系、数据流向、部署边界，可以精确到接口级别，因为开发要用它来定位代码。
• 面向管理者的版本：关注业务闭环、核心链路、资源依赖、风险点，不需要细节，只需要“业务是怎么跑通的”这个主干。
• 面向新人和客户的版本：关注角色、流程、概念，用业务语言而不是技术语言，目标是让人快速建立认知框架。

很多人画图累、改图烦，就是因为妄想用一张“大全图”覆盖所有读者。结果开发嫌太粗，领导嫌太细，新人嫌太乱，谁都不满意。把读者拆开，每张图只服务一个目标，设计难度瞬间下降一大截。

判断标准也很简单：拿图给目标读者看5秒，然后合上图，问他还记得什么。如果回答和这张图的核心意图一致，就说明图成了；如果只能蹦出“很多框、很多线”，就说明信息架构出了问题，回去重新梳理。

2. 动手之前的信息架构：先把图画在脑子里

2.1 一张图的四个必备元素：实体、关系、边界、方向

我画任何一张系统相关图之前，都会先在文档里列一份信息清单，把这张图会出现的“内容”穷举一遍。清单里固定有四个维度：

• 实体：系统里的模块、服务、存储、外部依赖、角色。这是图里的“节点”。
• 关系：实体之间的调用、依赖、数据流、消息传递。这是图里的“连线”。
• 边界：哪些东西属于同一个子系统、同一个部署环境、同一个信任域。这是图里的“分组/泳道”。
• 方向：请求从哪里进来、数据往哪里流、时序是什么。这是图里的“箭头”。

列清单的时候不要追求一步到位，想到什么写什么，像倒垃圾一样倒出来。比如给一个模拟的订单中心列素材，我会写：API网关、H5客户端、管理后台、订单服务、支付服务、库存服务、用户服务、优惠券服务、物流服务、订单MySQL、商品Redis、消息队列Kafka、日志监控、K8s集群、支付渠道、物流平台、短信服务。

这一列可能很乱，但没关系。乱是正常的，信息架构的工作就是把这一堆乱素材变成有结构的东西。

2.2 用“主干、分支、细节下沉”三层结构控制复杂度

素材列完，接下来做减法。这里我用的方法是“三层信息结构”：

• 主干层：一张图只讲一个核心故事。订单中心的架构图，核心故事就是“一次下单请求的完整链路”。凡是和这个故事主线无关的节点，原则上要不砍掉，要不挪到分支层。
• 分支层：支撑主要故事但非主角的部分。比如优惠券服务、用户服务，它们在子场景里重要，但订单主链路里只需要作为“被调用的外部服务”出现。
• 细节下沉层：接口名、表名、字段、端口、参数，这些内容不允许出现在主架构图上，要下沉到子图、附录或者对应的接口文档里。

这条原则对应到心理学里的“7±2法则”也很好理解：人的工作记忆同时能处理的信息块有限。当一张图的顶级节点超过7个，认知负担就开始陡增。我自己的经验是，一张系统架构图的可视化主节点数量尽量控制在5到9个之间，再多就必须靠分组来压。

具体操作时，“分组聚合”是最常用的减负手段。订单服务、支付服务、库存服务、物流服务，单个拎出来是4个节点，视觉上占4个框；用一个虚线大框把它们包起来，标注为“订单中心业务集群”，视觉上就变成了1个框里面3个点，外部连线肉眼可见地减少，图面立刻清爽。

2.3 图表类型别乱选：四种图各管一段事

“diagram-design”项目里，我踩过最尴尬的坑是把流程图画成了架构图，又把架构图画成了部署图。四者看着都是“框+箭头”，其实表达逻辑完全不同。这里做个区分：

一张图里可以混合多种表达，但必须分清主次。比如架构图里可以带数据流箭头，也可以画一个异步消息链，但你不能在一张架构图里把某个接口的完整时序交互细节全画出来，那是时序图的活。混用表达方式，轻则难读，重则误导。

我的习惯是，给一个复杂系统配图时，先画一张全局架构图定总览，再为关键链路配一张时序图或流程图作细节展开。一张总览 + 若干子图，比一张巨无霸图高效得多。

3. 布局与视觉规范：把审美变成可执行的参数

3.1 布局方向：从上到下还是从左到右，别凭感觉

布局是图表设计里最容易被忽视但影响最大的环节。很多人画图是“哪里空放哪里”，画完一看，节点排布毫无规律，阅读顺序全靠猜。

我给自己定的规则是：先定主方向，再排节点。

• 分层架构类图（最常见）：用从上到下的布局。接入层在最上面，业务层在中部，数据层在底部，外部依赖放侧边。这和阅读习惯一致，也符合“请求从上往下走，数据结果从下往上回”的心理模型。
• 流程时序类图：用从左到右的布局。时间或流程顺序天然适合左右阅读，分支向下延伸。
• 概念关系类图：用中心放射布局。核心对象居中，周边模块环绕，焦点突出。

定了方向之后，需要把节点在网格上定位。这里我强烈建议打开工具的“网格吸附”和“对齐参考线”功能。节点不在同一水平线上是新手图最明显的特征之一，明明可以对齐，视觉上却高高低低。对齐完成之后，图的专业感至少提升一倍。

3.2 间距、尺寸、对齐的硬性参数

“diagram-design”项目沉淀了一套我自己的默认参数，记在这里供参考。这些数值不是拍脑袋，是从可读性反推出来的：图形之间有足够留白，信息密度适中。

• 画布建议从1600×1200开始（16:10左右），这个尺寸导出后缩放裁剪余地大。
• 节点最小尺寸：宽200、高80，字号14px，标题20px加粗。再小在缩放时会糊成一团。
• 相同层级节点间距：水平方向80，垂直方向60。太挤则视觉粘连，太疏则被误认为不同组。
• 不同分组之间的间距：至少160，用作视觉分隔空间。
• 分组边框距内部节点的内边距：40以上。
• 连线拐弯处圆角半径：8，太小显得生硬。

这些参数的意义在于，它把“好看”转化成可复测的标准。团队里不同人画图，用的同一套数值，产出的图天然具有一致性，这才是规范的价值。

3.3 配色系统：四种颜色打天下，别让图变成彩虹

配色是另一个容易翻车的地方。常见的灾难现场是：一个模块一个颜色，一屏图里有十几种颜色，看久了眼睛疼，分不清主次。

我的配色方案非常克制，只有四类颜色：

• 中性色：黑、白、灰，用于文字、边框、次要节点。
• 主色：一个蓝色系（建议取HSL中S=70%、L=50%左右的鲜艳蓝），用于核心业务模块。
• 语义色：绿色代表正常/成功/可用，橙色代表异步/中间状态，红色代表异常/告警/不可用。
• 辅助色：一个黄色系或紫色系，用于和主色形成对比的外部依赖或特殊节点。

用颜色的时候有一个铁律：颜色必须有含义，用了就保持一致。比如红色是告警，那所有红色节点都必须和告警相关，否则读图的人会把正常模块误认为故障点。语义不一致的配色比没有配色更糟。

另外要考虑到色弱人群。如果图里只靠红绿色区分链路，会有一部分读者完全看不懂。我的做法是：颜色只作为信息的第一层编码，第二层编码靠形状和线型。比如告警节点除了红色，还加上“警示图标”或粗边框；成功链路除了绿色，还加上实线粗箭头。这样即使颜色识别不了，结构依然可读。

3.4 字体、线条和图标：细节决定能不能“看完了还舒服”

• 字体：全图最多两种字体，中文用无衬线体（系统默认即可），英文/数字也统一。标题加粗，正文常规，代码类标注可以用等宽字体。不要用艺术字，不要为了让某个词显眼随意改字体，强调靠字重和字号，不靠字体变化。
• 线条：核心链路用粗实线（4px），普通调用/关联用细实线（2px），异步消息/非关键路径用虚线（2px）。线条粗细要有语义，如果全图所有线一样粗，层次就消失了。
• 箭头：单箭头代表单向调用，双箭头代表双向交互，空心箭头代表数据流，实心箭头代表强流程导向。箭头样式在整张图里必须统一，不能混用。
• 图标：能用文字标注解决的，不要用图标。图标风格很难统一，用不好反而显得廉价。如果要用，选同一套线性图标，尺寸统一，颜色继承所属节点的颜色。

字体、线宽这些细节，单看都不起眼，但累计起来决定一张图最终是“看着专业”还是“看着业余”。区别往往就在这些地方。

4. 工具选型解析：七类产出方式实测对比与选型建议

4.1 工具选型，本质是选维护策略

画图工具的选择，很多人只看“哪个好用”，但我觉得更应该看“这个工具产生的文件，三个月后还能不能改得动”。图表最大的敌人是过时。系统一重构，架构图就废了；如果工具的源文件还打不开，那这张图就只能重画。所以我把“可维护性”作为选型的第一权重。

4.2 七类方案实测体验

“diagram-design”项目期间，我把市面上主流的画图方式都试了一圈，结论如下：

实测下来有个明显的现象：越“好看”的工具，越难维护；越“好维护”的，视觉越受限。这是没得办法的事。

4.3 我的组合方案：分场景使用，不指望一个工具吃天下

在“diagram-design”项目里，我最终确定的组合是：

• 思考阶段：用最普通的白板（物理或在线都行），只画草图，不在乎美观。目标是快速验证结构对不对。
• 正式文档阶段：优先用桌面通用绘图工具（如draw.io类），因为它格式开放、离线可用、导出清晰。凡是需要放进技术方案的架构图，都用它产出。
• 代码仓库里的图：用代码化图表。源文件是文本，能跟着代码一起评审、一起进版本库，改起来用diff就能看清楚改了什么地方，这是图形文件完全做不到的。
• 对外展示的高视觉图：交给专业设计工具做美化，但那属于“包装”环节，不是日常文档主流程。

这个组合的核心逻辑是：用白板解决思考，用通用工具解决文档，用代码化解决维护，用设计工具解决门面。各有各的边界，互不越界。

如果你问我“只选一个工具进文档流程会推荐哪个”，我的答案是：优先桌面通用绘图工具，因为它的学习曲线最平缓，导出质量足够，源文件又是标准格式；其次如果你所在团队开发属性重，直接在文档里用代码化图表也很香，我个人现在大部分内部文档的图都是用代码化方案生成的，省心太多。

5. 实操全过程：从零设计一张订单中心架构图

5.1 一个具体场景：给模拟商城订单中心画架构图

纸上谈兵说了一堆，这里放一个完整的实操案例。背景是我在整理某个模拟商城系统的重构方案，需要画一张订单中心架构图放进设计文档。这个系统规模中等，核心服务包括订单、支付、库存、用户、优惠券、物流六个服务，底层依赖MySQL、Redis、Kafka，对外接支付渠道和物流平台。

我按照前面说的方法一步步走。

第一步，梳理信息清单。把实体、关系、边界、方向全部列出来，形成下面这样一份素材表：

5.2 确定主链路和布局结构

信息清单列完，先画主干。这张图的主干故事是：用户通过客户端发起下单请求，订单服务协同库存、用户、优惠券完成订单创建，然后支付服务完成收款，支付成功后通过消息通知物流服务发货。

因此主链路的顺序是：

客户端/管理后台 → API网关 → 订单服务 → 库存服务 → 订单数据库 → 支付服务 → 支付渠道 → MQ → 物流服务 → 物流平台

确定主链路后，布局方案顺理成章：

• 画布1600×1200。
• 从上到下分四层：
  • 顶部接入层：y范围80~180。放H5客户端、管理后台、API网关三个节点，网关居中。
  • 中部业务层：y范围350~800。放六个业务服务，采用两排排列，订单服务和支付服务是主角，放在中间并略微突出。
  • 底部数据层：y范围950~1100。放订单数据库、Redis、Kafka三个存储节点。
  • 右侧边栏：x范围1250~1550，放支付渠道、物流平台、短信服务三个外部依赖。
  • 底部或全局用虚线框标注K8s集群边界，把部署环境表达出来。

5.3 用网格坐标把节点排布算出来

这一步很多新手会跳过，直接手动拖，结果越拖越歪。我的做法是先在脑子里计算网格坐标。

已知业务层有6个服务节点，每个宽200，横向间距80，则一行放3个节点的总宽度是 3×200 + 2×80 = 760。画布宽1600，则起始x = (1600 - 760) / 2 = 420。第一排三个节点的x坐标分别是420、700、980。

第二排同理，但为了视觉层次，第二排的起始x偏移半格，改为 (1600 - 760) / 2 + 40 = 460，形成一点锯齿排布，避免两排节点完全对齐导致的呆板感。当然，完全对齐也是一种风格，只要统一就好。

节点y坐标：第一排业务服务定在y=380，第二排定在y=520，层间距140，留出连线空间。

这些计算看起来很笨，但算完再画，节点的相对位置基本一次成型，后续只需要微调。比起随机拖动再手动对齐，效率高得多。

5.4 绘制与样式细节落地

坐标系确定，开始绘制。这个阶段我关心的都是“参数级”的细节：

• 节点样式：核心业务服务用圆角矩形（圆角半径8），填充浅蓝色，边框用主色蓝2px，标题字号20加粗，说明文字用14常规。外部依赖用灰色填充、灰色边框。存储节点用绿色系。所有节点填色后必须保留边框，纯色块在缩小时边缘会糊。
• 分组边界：用虚线大框把业务服务层整体框起来，标注“订单中心业务集群”；把数据层用虚线框标注“持久层”；整个部署环境再用一个大虚线框标注“K8s集群”。分组边框用2px虚线，颜色用和内部节点不同但协调的灰蓝色。
• 连线与箭头：主链路用4px实线加实心箭头，从网关指向订单服务，再指向库存服务、支付服务、物流服务。异步调用（如订单服务发消息到Kafka）用2px虚线加空心箭头。查询类调用（如订单服务读Redis）用2px细实线。外部依赖用3px深灰实线。
• 核心链路标注：在关键边上加文字标签，比如“下单请求”“扣减库存”“支付回调”“发货消息”。标签字体14，颜色跟随连线。

这里我要特别强调一点：连线尽量画成横平竖直，避免斜线，尤其是跨层长连线。斜线会让整张图显得乱。如果两个节点相距很远且必须连线，优先考虑调整节点位置，或者引入“消息总线”中间节点来缩短物理距离。我见过太多图，结构本身不复杂，因为两根斜线交叉，瞬间乱成蜘蛛网。

5.5 自检清单与导出

画完不到终点，还需要自查一遍。我把自检做成了一张固定清单：

导出这里有个经验：优先导出SVG，矢量格式在任何尺寸下都清晰。但如果文档平台不支持SVG，就导出高分辨率PNG。图像分辨率怎么算？目标展示宽度是1600px，如果要支持2倍屏，PNG宽至少需要3200px。120dpi只是底线，我一般按150-200dpi导出，文件大小可以接受，清晰度绰绰有余。

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

6.1 图面混乱的四大根源与解法

我复盘“diagram-design”项目期间所有的翻车现场，总结出图面混乱的四个共性根源，以及对应的解法。

根源一：信息过载。所有内容都想画上去，节点数量爆掉。解法：回到第2章的信息分层方法，把细节下沉到子图。自问：这张图的核心故事是什么？和这个故事无关的，全删。

根源二：布局无方向。节点位置凭感觉，阅读顺序混乱。解法：提前确定主方向（从上到下或从左到右），同一层级节点严格对齐。画完后整体缩放一下，如果缩到50%看起来还乱，说明布局有问题。

根源三：颜色没有语义。颜色纯装饰，没有在传达结构。解法：引入语义色系统，每种颜色绑定一种信息含义，并在图的角落放一个简短的“图例”说明色块和线型的含义。一张有图例的图，比没有图例的好理解得多，这一点很多人忽略。

根源四：箭头含义不统一。有的画实线，有的画虚线，有的带箭头，有的不带，全无规则。解法：建立线型规范表，贴在团队文档里，画图前先对照一遍，画完再检查一遍。

6.2 工具层面的翻车现场

• 导出图片模糊：大概率是导出的PNG分辨率太低。解决方法是导出SVG，或者把缩放比例调到150%-200%再导出PNG。不要直接用截图工具截画布，截图的清晰度永远不够。
• 多人协作互相覆盖：在线白板和多人编辑虽好，但架构图这种需要结构统一的内容，多人同时改很容易产生风格分裂。我的做法是：一个时间段只设一个“图 owner”，其他人在评论区提修改意见，由 owner 统一落地。图不是代码，不适合大规模并发编辑。
• 中文乱码或字体缺失：部分代码化图表工具对中文支持一般，生成出来的图中文是方块。解决方法是检查导出环境，优先选择支持中文渲染的引擎，或者在工具配置里指定中文字体路径。
• 文件打不开/格式不兼容：用专有格式的在线工具，一旦工具调整或停运，源文件可能直接报废。这也是我不把所有图表押在单一在线协作工具上的原因。通用格式（如SVG、XML）虽然老土，但至少五年后还能打开。

6.3 长期维护的实战心得

图表是软件文档里最容易过时的部分。代码变了，模块拆了，接口换了，图却没人更新，三个月后就是一幅“历史遗迹”。针对这个问题，我长期维护的思路是：让图和代码一起进版本库。

具体做法是：凡是代码仓库内的技术文档配图，优先使用代码化图表方案，因为源文件是文本，可以直接跟随代码提交、参与代码评审。修改一张图，走得是普通的Git分支合并流程，reviewer能看到diff，改了哪个节点、加了哪条链路一清二楚。这比下载一个图形文件、修改、再上传要可靠太多。

如果是非代码化工具画的架构图，我也会把源文件放进文档目录，并额外导出一份SVG。表格里维护一张“图片资产清单”，记录每张图对应的文档、最后更新时间、源文件位置。维护成本不高，但能避免“图不知道哪里去了”的问题。

7. 最后说几个攒下来的私人习惯

“diagram-design”这个项目做下来，工具和方法随时可以换，但有几个习惯是我现在画任何图都改不掉的，也一并分享出来。

第一，画图之前先写一段文字描述。哪怕只有三五行，把这张图要表达的“故事”用自然语言写下来。写不出来的图，说明自己还没想清楚；能写出来的图，画起来只是时间问题。文字是图最好的设计稿。

第二，坚持“电梯测试”。每次画完一张图，我都要能在30秒内把它讲清楚。如果讲的时候需要回头数节点、找箭头，那就是图太复杂了，需要拆，而不是更强地解释。这个习惯帮我砍掉了大量无效复杂度。

第三，源文件和导出文件永远双份保存。源文件保证可编辑，导出文件保证任意平台可展示。缺了源文件，图是有去无回；缺了导出文件，文档平台可能渲染不了。两个都留着，不占多少空间，省的是重画的时间。

第四，图上永远带“画图时间”或版本号。哪怕只写一个日期，也能让看的人知道这张图是不是过时了。没有时间戳的架构图，迟早会变成一张让人不敢相信的废图。

图表设计这件事，单看每个环节都不复杂，难的是把它当成一个系统来对待。把读者、信息、布局、视觉、工具、维护串成一条完整的链路，每一环都给足参数和标准，画出来的图自然就立得住。这套方法我还会继续完善，如果你在自己的图表实践里有更好的招，也欢迎拿去用、改造成自己的版本，这本来就是“diagram-design”项目最想做到的事。