画图这件事很多团队都低估了。早些年我还在做技术架构梳理的时候最烦的环节不是写文档而是画图。需求讨论会上白板画得飞起会后就靠手机拍照等真正要落到设计文档里才发现那些随手画的方框和箭头连自己都解释不清。后来接触的项目多了我才慢慢意识到diagram-design并不是“把图画出来”那么简单它背后是一门关于信息组织、视觉表达和协作沟通的完整方法。把图表设计这套逻辑捋顺了技术方案评审能少吵一半的架产品流程图能让研发和运营不在同一个节点上反复拉扯甚至给客户汇报时的沟通成本都能明显降一截。这篇内容我想把我在 diagram-design 这件事上积累的经验完整地梳理一遍。从最核心的设计原则讲起到不同场景下的工具选型再用一个实际案例演示一套从需求到成图的完整流程。最后一章我整理了一些我自己踩过的坑以及排查图里“看不懂”这个问题的具体思路。无论你是在做系统架构图、业务流程图还是平时需要画架构说明和汇报材料这篇内容应该都能给你一些可以直接拿去用的方法。1. 先搞清楚diagram-design到底在解决什么问题1.1 为什么“会画图”不等于“会做图表设计”我见过太多人打开画图工具第一件事就是拖一个矩形框出来然后在里面打字。这个动作本身问题不大问题在于大多数人是“边画边想”的——先画一个模块再画一条连线然后觉得线不对删掉重来画到一半发现少了一个层级又得整块复制移动。折腾两三个小时产出的图自己看得懂别人拿到手里一脸懵。图表设计的第一步不是“打开工具开始画”而是想清楚这幅图到底要回答什么问题。你要画的是系统架构图那核心是展示模块边界和依赖关系你要画的是业务流程图那核心是展示角色、动作和分支条件你要是画时序图那核心是展示消息的先后顺序和跨系统调用路径。同样是图信息颗粒度、布局方式、视觉强调的侧重点完全不同。我习惯把图表设计拆成“信息架构 视觉层次 图面规范”三层。信息架构解决的是“画什么”视觉层次解决的是“重点看什么”图面规范解决的是“怎么被人持续复用”。很多人画图只盯着第二层觉得加个颜色、加个阴影就是设计了结果信息架构本身就是乱的视觉做得越漂亮误导性越强。1.2 一份合格图表设计的四层结构我自己的经验一份能经得起评审、能沉淀到知识库里、半年后拿出来还能改的图表至少要满足四层结构。第一层是语义层。每个节点必须有明确的含义每一条连线必须有明确的语义。是用箭头表示数据流向还是用连线表示依赖关系还是用无箭头的线段表示关联这必须在同一张图里保持一致。经常有人把“数据流”和“调用关系”混用一张图里既有实线箭头又有虚线箭头但不说明区别读图的人只能靠猜。我现在的习惯是图里出现超过两种连线类型时必须先在图例区写清楚。第二层是层级层。信息要有主次核心链路必须在视觉上第一时间跳出来。常见的做法是分层布局把核心系统放到中间主区域外部依赖系统放到边缘位置底层基础设施统一沉到底部。图面不是越满越好留白不是浪费留白不清就没有“重点”可言。第三层是描述层。也就是每个节点上写什么文字、要不要加编号、要不要加注释说明。描述层的信息密度要克制节点名称用一个短语不要写完整句子跨区域的说明放到图例里或注释框里不要直接在连线中央塞一大段文字那样会打断连线的视觉连续性。第四层是结构层。结构层保证的是这份图表可以被持续维护。源文件的命名规则、组件分组方式、样式模板存储位置、多人协作时的版本约定这些看起来和“画图”无关其实决定了这份图能不能活过三个版本。我个人强烈建议 diagram 要和代码一起进 Git 仓库用文本化或可导出的格式管理这样每次改动都能追踪而不是发一个“架构图最终版(3).drawio.png”在群里传。2. 设计原则先行信息架构与视觉层级2.1 先分清类型流程、架构、状态机不是一回事diagram-design 里最容易犯的错就是拿同一种布局思路去套不同类型的图。我把日常工作中碰到的高频图表类型分成几类每一类的设计约束都不一样。第一类是流程类图表包括业务流程图、审批流程图、操作步骤图。这类图的核心是“时序和分支”所以布局上以自上而下或从左到右为主关键节点必须是明确的活动动词比如“提交申请”“审核通过”“回调通知”。流程图的开始节点和结束节点要显式标注分支条件的文字要贴近分支线而不是放在老远的地方用数字标注。分支有三条以上时建议拆成子图不要在一张图里画“蜘蛛网”。第二类是架构类图表包括系统架构图、应用部署图、网络拓扑图。这类图的核心是“层级和边界”所以布局上天然适合分层。我习惯把整个技术栈从下往上分成基础设施层、数据层、服务层、应用层、接入层每一层用一个虚线框圈起来框外写层名。架构图里的连线要如实反映依赖方向被依赖的一方放在下方或右方依赖方放在上方或左方读图的人视线从上往下正好是调用链方向这种方式最符合认知习惯。第三类是结构类图表包括类图、ER图、组织架构图。这类图的核心是“实体和关系”重点在实体属性字段的呈现和关系基数的表达。画这类图时不要为了美观把实体框缩得太窄字段文字被截断会让信息直接失效。关系基数像 1:N、M:N 这种必须明明白白写在连线端点上。第四类是状态类图表包括状态机图、时序状态图。这类图的核心是“状态迁移和事件”重点在状态节点的合法转换路径不在状态本身。很多人把状态图画成了流程图的变体这是错的。状态图里没有“开始和结束”的强约束只有“从状态A到状态B在事件X触发下发生”这样的语义画图时要把事件条件写在迁移线上不要写在状态框里。2.2 从“被看见”到“被遵守”的视觉规范图表设计做到一定阶段你会发现最难的其实不是单张图画得好而是整个团队产出的图能够保持一致的观看体验。这不是靠审美天赋而是靠视觉规范。我所在的团队后来定了一套很简单的图表视觉约定所有核心服务节点用主色填充颜色饱和度稍高所有外部依赖系统用中灰色填充弱化视觉权重所有数据存储节点用同类色系的浅色填充代表“底层支撑”。连线方面数据流用实线箭头异步消息用虚线箭头配置关联用细实线。这套规范最早只是几个人之间的默契后面写进团队的文档规范里新同学加入后照着标准拖模板产出的图基本不会跑偏。视觉规范还包括字体和尺寸。图上文字我强烈建议统一用同一种无衬线字体字号分为三个级别图标题用 16 到 18 号节点标签用 12 到 14 号注释辅助文字用 10 到 11 号。不要在一张图里出现四种以上字号更不要为了把某个节点填满随意放大文字。另一个常被忽略的细节是颜色数量控制。一张架构图里出现超过 6 种高饱和颜色基本就会变成“圣诞节彩灯”人眼无法迅速区分优先级。我的经验是大部分图控制在 3 到 4 个颜色以内颜色只用于表达类型差异不用于表达装饰性审美。2.3 信息架构的取舍节点、连线与层级一张图好不好的底层指标是看图者能不能在 30 秒内锁定核心链路。要做到这一点信息架构阶段就得做好舍取。节点的数量控制是第一关。一张架构图里超过 25 个节点读图的负担就会急剧上升。不是信息不能多而是要拆分——一个复杂的系统拆成“总览图”和若干“局部图”总览图只保留一级模块局部图再展开二级模块。这好比地图的缩放级别用户在全景阶段只关心主干道路放大之后才有必要展示街区细节。连线是第二关。连线的数量增长速度远快于节点节点增加 5 个连线最坏情况下可能增加 20 多条。连线逻辑非常密集时我的处理方法是引入“总线”或“数据总线”节点把网状连接改成星型连接。另一个方法是把语义相似的连线合并例如多个服务都要读同一张配置表不必每个服务画一条线指向配置中心可以用一个大的分组区域框住服务集群再用一条线指向配置中心并标注“全部服务”。层级是第三关。我经常对团队说画图时要像写目录一样组织信息。一级画面只展示一级目录二级细节放到子图里或者放到附录里。把三级细节全部塞进主图只会让图面信息密度过载识别率反而急剧下降。3. 工具链选型不同场景下我推荐什么3.1 开源桌面派的代表diagrams.netdiagrams.net 就是在很多技术社区里常见的 draw.io这个工具我前前后后用了好几年墙裂推荐作为团队的默认选型。它免费、开源、支持离线和本地存储关键是从浏览器里直接打开就能用不需要安装重型客户端。diagrams.net 我最看好的一点是它的文件格式很“干净”默认保存为 XML 文本。这意味着图文件可以直接放进 Git 仓库提交之后每次改动都有 diff 记录。团队协作时两个人同时改一张图会产生冲突但因为有版本记录出问题可以回滚这一点对技术类图表的长期维护非常关键。用 diagrams.net 的时候我习惯从它的模板库开始比如有现成的“云架构图”模板和“流程图”模板。模板可以快速提供一套基础的形状库和线条样式自己在此基础上调整成团队规范。它的自定义样式也比较灵活可以在“样式”选项卡里预留填充色、边框色、字体大小等参数调整好一套之后存为自定义模板后面每次新建图都基于这套模板来画。3.2 快速草图与头脑风暴ExcalidrawExcalidraw 是我用来做前期构思和快速讨论的利器。它最大的特点是手绘风格画出来的框框线线都带一点自然的粗细变化显示上就显得非常轻松随意适合在需求讨论、研讨会、白板协作时快速记录思路。Excalidraw 的协作体验很轻生成一个链接就能共享给多人大家在同一张画布上拖框打字画箭头延迟很低。它的插件生态里也有很多实用的图形库比如可以插入常用的架构组件图标虽然图标数量不如专业产品多但做中早期讨论稿足够了。不过我必须提个醒Excalidraw 更适合做“过程稿”不适合做“交付物”。它的文本文件格式是 JSON虽然也可以存到 Git 里但 diff 的可读性很差。手绘风格的图直接放进正式技术方案文档里有时候会显得不够严谨。所以我的流程是先在 Excalidraw 里快速把信息架构和布局理顺然后再到 diagrams.net 里产出规范化的正式版。3.3 文档驱动与Git托管Mermaid和PlantUML如果你的团队崇尚“文档即代码”那么 Mermaid 和 PlantUML 值得认真研究。Mermaid 是基于 JavaScript 的图表描述语言支持流程图、时序图、甘特图、状态图、类图等常见类型。它最大的优势是和 Markdown 生态无缝集成很多代码仓库或文档平台都支持直接渲染 Mermaid 代码块。写代码的人改动图里某个节点只需要修改一行文本这个体验对程序员特别友好。PlantUML 更偏重 UML 建模方向时序图和用例图支持得非常成熟语法生态也很完整。它的渲染后端是 Java在本地搭建稍微有一点重量级但胜在输出的图形非常规范。画时序图的时候 PlantUML 的自动排版做得很好基本不需要手动调整布局而 Mermaid 的时序图在复杂场景下时常需要手动加分组和换行。文档驱动型工具的共同优点是图天生就能进入代码评审流程。图表改动的 diff 清清楚楚评审人不需要打开画图工具就能看懂改了什么。这在跨团队、跨地域协作时价值很大。缺点是排版自由度和可视化精细度有限难以胜任复杂的架构图一般我用来画流程、时序、状态这类结构化图表。3.4 选型对照表与我的取舍习惯画图工具没有绝对的最好关键看你要拿图做什么。我把这几个常用工具做了一张对照方便按场景快速决策工具适用场景协作方式文件格式学习成本diagrams.net系统架构图、部署图、正式文档配图支持多人实时协作也可本地使用XML文本适合Git托管低Excalidraw头脑风暴、需求讨论、手绘风草图链接实时协作JSON适合临时共享极低Mermaid流程图、时序图、简单状态图适合嵌入Markdown代码评审/文档协作文本语法较低PlantUMLUML建模、复杂时序图代码评审/文档协作文本语法中等Figma产品原型、高保真视觉图实时协作最强在线文件中等我自己的取舍习惯是草稿和讨论用 Excalidraw正式静态图用 diagrams.net文档内嵌图优先用 MermaidUML 类型图用 PlantUML涉及产品交互设计的时候才动用 Figma。这个组合已经能覆盖我 90% 以上的场景。4. 一个完整案例从需求到成图的实操流程4.1 需求梳理先做信息列表再动手画框我拿一个实际的例子来演示整个 diagram-design 流程。假设团队成员需要设计一张“订单履约系统”的架构图目标读者是研发新同学和协同团队的技术负责人。拿到这个需求我的第一步不是打开工具而是先在文档里列出所有必要信息。我列的信息列表大致长这样核心系统订单中心、履约引擎、库存中心、支付系统外部依赖商品服务、用户服务、物流网关、消息推送平台数据存储订单数据库、库存数据库、消息队列接入方Web端、小程序端、开放平台API关键链路下单支付 - 库存锁定 - 订单履约 - 物流同步 - 消息通知列表列完之后我会继续补充一些非功能性的信息包括接口协议、通信方式、异步或同步标记。这些信息在最终成图时不一定全部体现但它们是判断连线语义的重要依据。没有这份列表直接开画十有八九会漏掉依赖关系。信息列表整理完成之后我会用 Excalidraw 快速搭一版信息架构草稿。草稿阶段完全不关心对齐、颜色和美感只关心模块怎么分组哪些模块应当放在核心位置哪些模块属于外部边界这一步跑顺了后面画正式图的速度会快很多。4.2 布局与构图分层、分区、锁定主干在草稿的基础上进入正式布局阶段。我用的布局策略是“分区 分层 主干优先”。先把整张画布横向分成三个大区左侧是“接入层”中间是“业务核心层”右侧是“外部依赖层”。然后用纵向方式把中间的核心区再分为“应用服务区”和“数据存储区”。这样画布的自然语义就是左侧的请求进入中间的模块处理业务逻辑底层的数据存储提供保存能力右侧的外部依赖提供辅助能力。主干链路是“Web端下单 - 订单中心 - 履约引擎 - 库存中心 - 支付系统 - 物流网关”这条链路要放在画布最核心的位置节点尽量保持同一水平中轴线上。次要的模块比如消息通知、用户服务、商品服务放到主干的上方或下方用辅助线路连接视觉权重上不跟主干抢注意力。连线的排法是关键一步。主干链路用加粗实线颜色用高对比色异步消息用虚线箭头查询依赖用细实线。线之间要有足够的间距交叉点越少越好。出现交叉不可避免时可以用“跨线跳转”样式或者把一个端点的出口调整到另一侧来减少交叉。4.3 样式落地颜色、字体、线宽、间距的通用标准正式画图时大多数人的犹豫都花在“这里用浅蓝还是深蓝”这种问题上。我的建议是这些细节根本不应该在制图当时花时间纠结直接把标准定好每次套用就行。我整理了一套适用于绝大多数架构类图表的通用标准直接抄作业即可。背景色统一用纯白或者非常浅的灰色。圆角矩形用于服务类节点直角矩形用于数据存储类节点椭圆或扁胶囊形用于外部角色或系统边界。核心服务填充色用主品牌色比如蓝色系外部依赖用中灰色数据存储用浅绿色系。字体统一无衬线字体节点内文字 13 号图例和注释 10.5 号。连线默认 2px主干链路 3px。节点间距至少保持一个节点宽度的 1/2避免狭小空间内密集排布。正规做法是所有节点边框保持同一粗细统一不要使用阴影。阴影会让打印和投屏的时候出现杂乱感觉也会显著增加导出后的文件体积。如果团队的模板没做好节点边框粗细不一致说服力会大打折扣。所以我在团队内部强制要求所有节点样式由母版统一驱动不允许个人在单张图里手工微调。4.4 检查和交付让图真正被“读动”图完成后我会给自己留一个强制检查环节这个环节我用四个问题来问自己。第一不看注释能不能在 20 秒内说出这张图的核心链路答不上来说明主干链路不够突出或者节点标签模糊。第二每条连线有没有明确的动词或语义比如“调用”“写入”“订阅”连线上没有语义读图者就只能自己联想。第三把颜色转成灰度还能不能凭边框和位置区分不同区域如果全靠颜色区分色弱用户和黑白打印场景会直接失效。第四这张图放置半年后再更新别人能不能快速找到需要改的位置如果结构分层不规范任何人拿到手都会觉得无从下手。交付的时候我通常会同时导出两个版本SVG 格式用于文档插入保证放大不糊PNG 格式用于沟通和预览。源文件本身保存为 diagrams.net 的 XML 格式放进 Git 仓库和代码一起管理。每次改动后提交信息里写明变更内容比如“订单履约架构图调整库存中心依赖方向”这样后续追溯成本极大降低。5. 常见问题与排查技巧实录5.1 典型翻车现场这些年做 diagram-design 相关支持我见过了太多种“图翻车”的现场。这里我挑几个高频的场景大家可以对照一下自己有没有中招。第一个翻车现场是“大而全”。有人希望一张图表达整个公司的业务于是把所有服务、所有数据库、所有第三方系统全塞进去结果图导出之后宽度接近一两万像素屏幕上根本看不了全貌打印更是糊成一团。解决方案前面其实已经说过总览图只保留一级模块细节放到子图。这背后有个很底层的逻辑图表的职责不是“穷尽信息”而是“引导注意力”。一张图读者扫过去只能处理 5 到 9 个信息块的注意力是有限的超载就失去意义。第二个翻车现场是“箭头满天飞”。有些图里每个节点之间都有双向箭头或者乱交的交叉线搞得人心烦意乱。真正常见的系统依赖是“核心服务依赖数据层”数据层很少反向依赖业务服务。画图前先梳理清楚依赖方向能合并的连线坚决合并不能合并的尽量绕开主干。箭头方向必须语义清晰不能为了装饰给每条线加箭头而是要去想清楚到底是要表达流向还是关联。第三个翻车现场是“命名玄学”。节点里写“系统A”“模块B”“服务C”缩写满天飞读者不翻上几十页文档根本对不上号。节点命名的原则是在 80% 的时间里能脱离上下文看懂。使用标准业务名称不使用内部代号首次出现时可以在图例中补充全称。第四个翻车现场是“版本失控”。一个架构图文件通过邮件反复发或者用“-v2”“-final”“-最终版”来命名。最终图源文件无法追溯大家各自为阵改出形形色色的版本。应对方法就是前面反复强调的源文件进 Git 仓库或者至少进团队统一的 wiki/知识库系统并标注负责人和最后更新时间。5.2 收到“看不懂”反馈后的排查思路当别人拿到你的图说“看不懂”先别急着觉得对方水平有问题。绝大多数情况确实是图本身在设计层面有缺陷。我习惯了用一套固定的排查顺序去定位问题。先查信息架构。核心链路是否突出节点分组是否清晰如果读者找不到第一眼应该看哪里那就说明主次设计没有做好。这个问题的修法通常是重新组织布局把主干放到视觉中心弱化边缘信息。再查连线语义。每条线是否都在传递有效信息是否有没有说明的箭头含义如果读者不知道一条线表达的到底是调用、依赖还是数据流那这条线就是噪声。修法是统一连线类型补充图例。再查文字信息。节点名是否是团队公认的术语缩写是否说明过注释是否过多或过少文字的修复通常比布局容易但影响面很大。最后查图面规范。字体是否统一对齐是否有规律颜色是否太多这些属于“图面卫生”问题虽然不影响语义但极大影响专业感。我在排查完这些问题之后经常会有一个体会一张图被说“看不懂”通常不是某个单一问题而是上述多个问题叠加起来的后果。信息架构不清加上连线语义混乱加上命名随意三重叠加之后读者自然放弃读图。所以修图的时候也不要只盯着局部补丁要整张图从架构和层级上重新过一遍。这个内容后续还可以这样扩展团队内部可以做一套图表规范速查卡把配色、线型、字号、层级结构的约定浓缩在一张图里挂在文档库首页也可以用 scripts 做 Mermaid 图表的自动检查脚本比如检测连线是否都带语义标签更进一步的团队还可以沉淀一个“图表评审清单”每次评审图之前先对照清单打分这样长期坚持下来整个团队的 diagram-design 水平会提升得非常明显。