图表这件事，说难不难，说容易也容易翻车。我见过太多技术方案里，堂堂一个核心链路图，画完没人看得懂；也见过明明逻辑很清楚的一个流程，因为节点堆得太满，评审时被反复追问。后来我把一套叫“diagram-design”的思路沉淀下来，专门用来处理架构图、流程图、数据流转图这一类技术图表的从零设计。它不是什么高深理论，就是一套从拆需求、选工具、定布局到落文档的可复用方法，适合经常写技术方案、维护知识库、或者在团队里负责文档建设的人参考。这篇文章把整套流程和踩过的坑一起展开，希望能帮你少走点弯路。
1. 先别急着开画：想清楚这张图到底要表达什么
很多图之所以画出来没人看，根本原因不是画得不好看，而是画之前没想清楚“给谁看、在什么场景看、看完要得到什么结论”。diagram-design 的第一步不是打开工具，而是先回答这三个问题。
1.1 图表先回答三连问：读者是谁、场景是什么、结论是什么
我最早画图是典型的学生思维，恨不得把系统里所有模块、所有接口、所有依赖关系全部塞进一张图里，觉得这样才叫“完整”。结果图一拉出来，横向超过显示器两倍，纵向滚两屏，每个节点旁边还有三条注解线。我自己都看不清，更别说别人。
后来我给自己定了一个死规矩：落笔之前先写三句话。第一句写给谁看，比如“给后端同事看”和“给产品经理看”，完全不是一回事。第二句在什么场景看，是评审会上的演示稿，还是文档里冷读的资料。第三句看完要得出什么结论，比如“这个服务的调用链路上存在一个单点，需要冗余”，或者是“状态机的流转是合法的，不存在死循环”。这三句话写不出来，宁可先不开画。
这三连问直接决定了图的抽象层级和省略范围。如果是给非技术同事看，就不该出现数据库连接池、线程数、缓存命中率这些细节；如果是给运维同学看，业务含义反而可以弱化，重点是端口、协议、部署拓扑。
这里有一条经验：一张图只解决一个问题。我发现很多图难懂，是因为作者想把“系统长什么样”和“请求怎么走”以及“异常怎么处理”一次性表达出来，结果三种问题互相干扰。实际上应该拆成部署结构图、逻辑架构图、时序交互图、异常流程图这几张，每张图都只回答一个问题。这样组合起来虽然要多花一点时间，但读者体验是完全不同的。
1.2 分层拆解：别让一图背负所有复杂度
我会把一个待展示的系统，先在脑子里拆成三层：边界层、能力层、链路层。
边界层回答系统与外部世界的交互，画出用户入口、外部依赖、消息队列对端、下游服务。能力层回答系统内部有哪些核心模块或子域，各自职责是什么。链路层则选择一条具体业务场景，画出请求或数据经过哪些模块、每个步骤做了什么。
拆完之后，你会发现大多数情况下根本不需要把这三层画在一张图里。高层文档适合放边界层加能力层，重点讲清楚职责边界。技术评审或排障文档，才需要链路层，而且链路层通常只画一条主线，其他分支用“省略号”或者“详见另一张图”的方式带过。
举个例子，某内部通知系统的整理过程。第一次信息采集时，我把短信、邮件、站内信、Push、管理后台、渠道供应商、重试队列、黑名单服务这些东西全部列了一遍。如果全画在一张图里，至少有三十个节点和五十条连线，根本没法看。拆解后就变成了三张：第一张是通知系统与外部系统的边界图，只有六个节点；第二张是系统内部模块图，约十个节点；第三张是“发送一条短信失败后如何重试”的链路图，只有五个节点。三张图都清晰，组合在一起又完整，评审时大家各取所需，不会再有人对着图发懵。
这件事想表达的其实是：diagram-design 核心能力之一就是做减法。把复杂系统拆成多个单一语义的视图，而不是用一张“巨型全图”来证明你画图很努力。
2. 工具选型：文本优先还是画布优先，各有各的命
工具选择是图表设计里最容易被低估的一环。很多人直接打开一个顺手的绘图工具就开始拖节点，结果到了维护阶段才痛苦。图表也是要维护的，而且图表过期比文档过期更坑人——因为它看起来很正式，大家会下意识当真。选工具时，核心要回答的是：这张图的源文件要放在哪、谁能改、改完怎么评审。
2.1 文本生成派：适合进代码库、可diff、可批量改
文本类绘图工具天生的优势是可以把图“写”出来。节点和连线都以纯文本形式存在，放进代码仓库之后，可以做版本管理、做diff、做review。有人改了一个节点，另一个人能清楚地看到这一版和上一版哪变了。这是一个听起来普通、实际影响巨大的特性。团队协作中，最怕的就是某天有人用画图软件更新了一张设计图，别人完全不知道哪里变了，只能瞪着两张大图眼对眼。
文本方案的另一个优势是批量修改。假设你定义了模板，某个公共组件在整个目录的多张图里都有出现，现在需要改这个组件的名字或颜色。如果是拖拽工具，你要打开每一个文件，手动选节点，改样式，保存。文本工具则只要做一次模式替换，重新生成，全目录图表一次更新完。这种情况在架构演进期特别常见，一个月里组件被改名三四次都是正常的。
文本派也有明显的短板：布局可控性弱。如果图比较复杂，自动布局出来的箭头交叉、标签重叠时常发生。尤其是领导临时让你“把这两个模块放得近一点”时，拖拽工具里两秒钟的事，文本工具可能要调半天顺序和分组。所以文本派更适合逻辑关系清晰、节点数量在可控范围内、且需要长期维护的技术文档图。
2.2 拖拽绘图派：适合快速头脑风暴和精细化排版
画布型工具的强项是自由。你可以随意摆放节点、微调坐标、拉取路径、调整颜色，做到像素级的排版控制。非常适合会议期间快速把想法视觉化、给非技术背景的人做高保真示意图、或者画那种需要把多个小图拼在一起的大图。
在这个流派里，我最常用的工作流是三步：先画出粗糙的方框，确定大致排布；然后调整对齐和间距，锚点吸附保证连线不会歪；最后统一字号、统一配色，导出时候选高清位图或矢量格式。
需要注意的坑也很多。一是画布型工具的文件格式往往是私有格式，换工具迁移成本很高。二是如果你没有刻意保存成兼容格式，别人即使拿到源文件，也可能打不开或打开后排版全乱。三是多人同时编辑一张画布图，传统模式下必然产生冲突，改完也不知道改了什么。这不是说画布型工具不能用，而是要让它的使用场景和文本派区分开。快速讨论、一次性演示、对外高保真图用它；长期维护、多人协作、版本敏感的图用文本派。
2.3 混合工作流：先用文本理逻辑，再进画布调样式
我现在的习惯是混合使用。具体分成三个阶段：结构阶段、样式阶段、发布阶段。
结构阶段，我会在文本工具里把节点和连线全部写出来，强制自己用文本语言描述清楚每个实体和关系。这个阶段最忌讳用眼睛去拖，因为拖拽会让人沉浸在“摆放”的满足感里，反而忽略了逻辑上的漏洞。文本阶段能逼着你先想清楚：A和B是什么关系？是调用、依赖还是数据流？方向是什么？这些文本能明确表达。
样式阶段，再把结构化内容导入到画布工具里做精细排版。调整的主要是视觉引导，比如把主链路摆成一条从左到右的主轴，把辅助依赖放在下方，把异常分支用虚线与其他线区分开。
发布阶段，我会同时输出两样东西：一张高清图片嵌入文档，以及这份图的源文件。如果源文件所在路径能放进代码库或团队共享目录，就更好了。图片负责“看”，源文件负责“改”。很多人只看图，不看源文件，等到图要改的时候找不到源头，这是维护事故，必须避免。
3. 从需求到成品：一张架构图的完整实操过程
前面讲的是方法和选型，这一节走一遍实际过程。用我在某跨平台系统整理的一次图表设计作为案例，从最原始的零散描述开始，到最终产出一张可以直接放进技术方案的架构图。
3.1 信息收集与结构化：从一段“流水账”拆出节点和连线
原始接到的信息是这样的：“我们的系统接收上游平台回传的数据，然后进MQ，消费者去处理消息，其中有一步要把原始数据存一份到对象存储，还可能要调第三方接口做内容审核，审核不通过的要进人工审核池，通过的就正式入库，用户查询走另一套查询服务。”
这段话本身不能用，直接照着画出来的图跟菜单一样，没有重点。先把它拆成节点和连线。
第一轮节点清单大概是这样的：数据源（上游平台）、接入网关、消息队列、消息消费者、对象存储、内容审核服务、人工审核池、业务数据库、查询服务、用户端。连线则有数据源到网关、网关到MQ、MQ到消费者、消费者到对象存储、消费者到审核服务、审核服务到人工池、审核服务回执、消费者到业务库、查询服务到业务库、用户端到查询服务。
到这里信息还不是图，因为缺少层次和分组。我接着做分类：第一层是外部系统，包括数据源、审核服务、用户端。第二层是接入层，包括网关和MQ。第三层是处理层，包括消费者、存储、数据库、审核流程相关。于是这三个分组，正好对应边界层、能力层、链路层的关系。分完组之后，图的骨架就出来了。
操作上，我习惯用一个简单的表格来管理这个信息，表头是节点名、类型、上游来源、下游去向、备注。备注里写清楚这条连接代表调用还是数据流，以及是否属于主链路、是否属于异常分支。做表格的过程，本质上就是预编译，后面画图只是把这个表格“渲染”出来而已。
3.2 布局与视觉规范：主链路靠左到右，层级靠分组，语义靠线型
布局是决定一张图能不能“三秒读懂”的关键环节。我固定的布局原则是：主链路贯穿从左到右的水平方向，尽量少拐弯。支线或辅助流程放在主链路下方，尽量用直线和直角。异常分支、超时补偿、人工处理这些非主流路径，统一用虚线或不同颜色区分。竖向上则用分组代表逻辑层级，比如外部环境、接入层、核心处理层、持久化层，由上而下，一目了然。
有人会问，为什么不是从右到左或者从下到上？因为人的视觉阅读习惯大体上是从左到右、从上到下。图表设计不是艺术创作，它要降低认知负担。遵循阅读习惯，就是让注意力自然落在主流程上，不需要读者额外去猜起点在哪。
配色方面，也要定规矩，避免把一张图搞得像调色盘。我通常只用五种颜色：主流程节点用一种中性色，外部依赖用一种统一的基础色，数据存储用一种偏冷的色，异常分支节点用一种低饱和的警示色，辅助说明文字用灰色。这里的关键是颜色代表“语义”，不是代表“我喜欢”。如果某一天有人打开图发现某个模块换了个新颜色，那么新颜色必须有明确含义，否则就不许换。这一条能让团队维护时的沟通成本大大降低。
命名是另一个容易忽略的点。节点文本建议统一采用“动词短语”或“名词短语”的其中一种，不要混着来。比如同一个图层里，“订单处理”是名词描述，“校验用户权限”是动词描述。实际上我更推荐用动词短语标注动作节点，用名词短语标注实体节点。顺序上，尽量从“读取方”指向“提供方”，或者从“调用方”指向“被调用方”，方向一旦统一，看图的人就不会产生歧义。
3.3 终稿检查清单：导出前的最后一轮自检
图基本画完后，我还留着最后一轮检查，专门抓那些一眼能看出来的低级但致命的错误。这个清单基本是固定的：
- 所有线都有明确的起点和终点，不存在悬空线。
- 每个节点的措辞保持统一粒度，不要出现“用户登录”和“调用用户中心接口获取用户基本信息”这种粒度不一致的并列节点。
- 主链路是否在三秒内能被识别出来，如果不能，说明布局有问题。
- 有没有交叉线超过两处，如果有，考虑是否换主轴方向或者调整节点顺序。
- 标签是否完整，比如“同步接口”“异步消息”“依赖外部服务”这些重要语义是否在图上直接可读，而不是需要看底下的图例去猜。
- 导出图片的清晰度是否足够，直接放缩到200%预览检查边缘是否有锯齿。
- 源文件是否已保存并被引用，文档里的注释或图下说明是否写了这张图表达的核心结论。
这套检查清单看起来很琐碎，但对应到评审会上都是被血泪教训过的。尤其是第一和第三项，只要悬空线存在，或者主链路不清晰，评审一开始就会被人从图上发现漏洞，然后整个方案的说服力都会打折。
4. 典型踩坑与排查记录
最后整理一下，我在图表设计这件事上实际遇到过的几个高频问题，以及排查思路和处理方案。这一节更像一个个人备忘，希望能帮你省掉一些调试时间。
4.1 文字重叠与图片发虚，问题多半在布局而非渲染
文字重叠通常不是工具bug，而是节点大小和内容长度不匹配。我在文本派工具里遇到最多。解决办法是在设计阶段就给节点指定统一的文本宽度预算，比如主名最长八个字，备注最长十二个字。字数超了就换行或缩写，而不是放任节点自动撑大。这一招的好处在画布型工具里也能复刻：先统一设置节点的最小宽度，再排版，画面干净很多。
另一类是导出图片发虚。常见原因是默认导出的位图分辨率不够。建议导出时指定一个截图尺寸放大倍数，比如至少两倍或三倍，确保嵌入文档后即使再放大也不会糊。如果工具支持矢量导出，就直接导矢量格式，再放到文档里拉高放大倍率也不怕。切记，不要在文档里直接贴工具内的截图小图，这种图的观感会瞬间拉低整篇文档的专业度。
4.2 箭头交叉与图过长，可以用“聚合”缓解
图太长或交叉线太多，说明你的图在咬着一个过大的逻辑范围不放。我常用的一个处理技巧是“聚合”。如果三条线同时指向同一个外部系统，可以在图上只画一条线，把它标注为“统一依赖某服务”，然后在图的下方或文档里注明更细的接口关系。如果五个节点之间存在网状依赖，那就把它们折叠成一个“子组件”节点，在另一张“内部细节图”里展开。
聚合的妙处在于它保留了读者理解主干所需的全部信息。对评审人来说，不关心子模块内部连了几条线，只要知道它是个独立单元就足够。等到需要深入单点细节时，再翻开细节图。这个思路和代码重构里“提取函数”的理念很像，目的都是让每一层抽象都保持在可理解的范围。
还有一种情况是图过长，一条纵向链路从顶部一直拉到页面底部。这种图多数因为没有分组。你把节点按照阶段分成两三块，每块间留出明显的间距留存，或者在分组之间加一条明确的阶段注释，就会好很多。人的眼睛需要一个“落脚点”，分组就是那个落脚点。
4.3 颜色杂乱与团队难维护，从“禁止自由配色”开始
团队合用一个文档库时，最容易发生的是：每个人画图都用自己喜欢的颜色。A同学把主要业务模块涂成橙色，B同学把同样的模块涂成蓝色。视觉混乱还是小事，更严重的是语义被破坏。当一张图里颜色不能代表类别时，读者只能靠文字去逐个识别节点，阅读效率极低。
我定的团队约定是：先确定角色再定颜色，每个人的图都要复用同一套模板。新增颜色必须经过一次评审，任何临时想法都不能直接进文档。刚开始有人觉得太死板，实际用了一段时间之后，大家都开始受益。因为看到一个颜色就知道它大概是数据库、外部依赖还是主流程节点，看图速度明显加快。这其实就是把个人审美换成了一种元认知。
另外，画布型工具协作时容易遇到两个问题：同一张图多人同时编辑导致互相覆盖，以及源文件分散在个人电脑上导致版本混乱。我的建议是：所有图源文件统一收口到一个共享目录，和文档同仓库管理，修改前先锁定，修改后记录变更说明。如果确实需要多人高频协同，那就改用文本型工具并走代码评审那道流程。这样虽然多了一步，但能避免很多无谓的返工。
5. 最后说几个提升图质量的意外技巧
有几个小技巧，不在主流程里但很实用。
第一个是给每张图配一句“图下注释”。我见过太多图，光秃秃一张摆在那，读者需要自己猜它的作者到底想表达什么。其实只要在下方加一行小字，比如“图中从支付网关到订单服务的双线表示异步回执链路，下单主流程为灰色粗线”，就能避免大量误读。这句话也逼着画图人自己再一次确认：这张图最重要的事情是什么。
第二个技巧是“先画丑图”。我发现如果中途过于在意美观，思路会被排版干扰。有些图表设计走到瓶颈，不是逻辑不对，而是你已经在摆位置和调样式上花了大量心力，脑子累了。先快速画一版很丑的“骨图”，只表达节点和连线关系，确认逻辑无误后再做样式，效率和效果都更好。这个顺序不要颠倒。
第三个技巧是善用图层的注释和阴影但要克制。给关键节点加一个注记框，说明它的异常行为和降级策略，往往比在正文里写一大段更有效。而阴影、渐变、圆角，这些装饰元素能省则省。技术图表不是海报，信息传递优先级永远排在视觉美观前面。
最后再放一句我踩过多次坑之后总结出来的经验：diagram-design 不是一个画图工具能解决的事情，而是一套推导过程。从读者、场景、结论出发，经过分层拆解、工具选型、结构化清单、布局配色、终稿检查，最后形成可维护的图与源文件。只要你把这套过程理顺，哪怕工具很简陋，画出来的图也不会难看到哪里去；反过来说，工具再强，没有这套过程，最后也难逃一张“好看但没人懂”的图。
到O(n))
