1. 从“diagram-design”这个标题说起它到底在解决什么问题第一次看到“diagram-design”这个标题很多人会下意识觉得它是个画图工具或者某个设计系统的代号。但如果你真正在工程、产品、咨询或者技术写作场景里待过就会明白这个标题背后藏着的是一类非常具体且高频的痛点如何把脑子里那些模糊的、线性的、碎片化的逻辑关系快速、准确、美观地转化成一张别人一眼能看懂的图。这件事听起来简单做起来极其折磨人。我见过太多团队在评审会上因为一张架构图吵得不可开交原因不是技术方案有分歧而是图画得太烂——箭头指向不明、层级混乱、颜色乱用、图例缺失。最后大家花在“解释这张图到底想表达什么”上的时间比讨论方案本身还多。diagram-design 这个主题本质上就是在回答一个问题图不是画给自己看的是画给读者看的而读者的耐心通常只有三秒。所以这篇文章不打算跟你聊什么“设计美学”或者“视觉传达理论”那些东西太虚。我想从实际从业者的角度把 diagram-design 这件事拆成几个真正能落地的层面为什么大多数技术图让人看不懂、画图之前应该先确定什么、不同类型的图分别该怎么处理、有哪些工具和技巧能让你少走弯路、以及我在实际项目中踩过的那些坑。无论你是刚入行的工程师还是需要频繁做汇报的产品经理或者只是想把 PPT 里的流程图改得稍微像样一点这些内容都能直接拿去用。提示本文讨论的 diagram-design 不局限于某一种工具或某一种图。流程图、架构图、时序图、状态机图、思维导图、甚至手绘草图只要涉及“用图形表达逻辑关系”都在讨论范围内。2. 为什么你画的图别人看不懂三个根深蒂固的认知误区2.1 误区一把“画完”当成“画好”这是最普遍的问题。很多人画图的流程是这样的打开工具想到什么画什么连线加文字导出发送。整个过程没有任何“读者视角”的介入。结果就是画的人觉得自己表达清楚了看的人却一头雾水。我做过一个粗略的统计在一个中等规模的研发团队里随机抽取十张架构图给不同角色的人看能在一分钟内准确说出“这张图想表达的核心信息”的人通常不超过三个。这意味着大部分图的信息传递效率低于 30%。问题出在哪出在画图的人默认“读者和我拥有相同的背景知识”。但现实是看你图的人可能根本不了解你的模块划分、不知道你的命名习惯、甚至不清楚你用的那些缩写是什么意思。解决这个问题的办法很简单但需要刻意练习画完图之后先别发出去找一个完全不了解这个项目的人让他看图说一遍他理解的内容。如果他说出来的和你想要表达的有偏差那就改。这个动作我称之为“图的可读性测试”成本极低效果极好。2.2 误区二信息密度越高越好很多人有一种执念觉得一张图里塞的信息越多显得自己越专业、越全面。于是你会看到那种密密麻麻、连线像蜘蛛网一样的“巨型架构图”上面有几十个模块、上百条连线、各种颜色和图标。这种图唯一的用途就是放在文档里当装饰证明“我们系统很复杂”但它几乎不具备任何解释功能。真正好的 diagram-design 遵循一个原则一张图只讲一件事。如果你想表达系统的整体架构那就只画模块和层级关系不要在里面塞数据流向如果你想表达某个请求的完整链路那就只画时序和调用关系不要在里面展示部署拓扑。把不同维度的信息拆到不同的图里每张图都保持“一眼能看懂”的清晰度。我自己的习惯是如果一个图需要超过三种颜色、超过二十个节点、或者需要看图的人花超过十秒才能找到起点那就说明这张图该拆了。2.3 误区三工具决定质量这是新手最容易掉进去的坑。总觉得换了更高级的工具图就会变好看。于是花大量时间研究各种绘图软件的快捷键、主题、插件却忽略了最核心的东西图的逻辑结构。工具当然重要但它只影响“颜值”不影响“可读性”。一张用记事本画的 ASCII 流程图如果逻辑清晰照样能让人秒懂一张用专业工具画的花里胡哨的图如果逻辑混乱照样让人抓狂。我见过用纯文本 mermaid 写的时序图比某些用商业软件画的还清楚原因就是作者把逻辑理顺了。所以我的建议是先用最顺手的工具把逻辑画出来确认结构没问题之后再考虑美化。不要本末倒置。3. 画图之前的必修课先想清楚这四件事再动手3.1 确定图的“读者”和“场景”这是所有 diagram-design 的起点。同一套系统给不同的人看需要完全不同的画法。读者类型关注重点推荐图类型信息密度高层管理者整体结构、关键模块、风险点简化的架构图低不超过10个节点同组工程师接口定义、数据流向、边界条件详细的时序图/流程图中高可到30个节点运维人员部署拓扑、网络分区、依赖关系部署图/网络图中强调连接关系新入职同事模块职责、调用关系、核心链路分层架构图核心时序图中需要图例和注释外部合作方系统边界、交互方式、数据格式上下文图/接口图低只画交互部分这个表格不是死规矩但它能帮你快速定位“这张图该画到什么程度”。我见过太多人给老板汇报时用工程师视角的详细图结果老板看了三分钟只问了一句“所以我们的核心优势是什么”。这就是读者错配。3.2 确定图的“核心信息”在动手之前用一句话写下这张图要表达的核心信息。比如“用户请求从网关进入后经过鉴权、路由、业务处理、数据存储四个阶段”“系统分为接入层、服务层、数据层三层每层包含哪些模块”“订单状态在创建、支付、发货、完成、取消五个状态之间的流转条件”这句话就是你的“图眼”。画完之后检查一遍如果读者看完图之后能复述出这句话说明图成功了如果读者看完之后说了一堆无关的细节说明图失败了。3.3 确定图的“视觉层级”任何一张好图都有明确的视觉层级。什么是视觉层级就是读者眼睛应该先看哪里、再看哪里、最后看哪里。常见的视觉层级设计手法包括大小对比核心模块画大一点辅助模块画小一点颜色对比关键路径用高亮色次要路径用灰色位置对比主要流程从左到右或从上到下辅助信息放在边缘粗细对比主流程连线加粗次要连线变细我个人的习惯是在画图之前先用纸笔勾一个草图标出“第一眼应该看到什么”。这个草图不需要好看只需要把层级关系确定下来。很多图之所以乱就是因为所有元素都在“抢眼球”没有主次之分。3.4 确定图的“边界”一张图必须明确画出“什么在范围内什么在范围外”。这个边界可以是系统边界、团队边界、时间边界、或者职责边界。比如画架构图时我会用虚线框把“本次讨论的范围”框出来框外的部分用灰色表示“不在本次讨论中”。这样做的好处是读者不会问“为什么没有画 XX 模块”这种问题因为图上已经明确说了“XX 不在范围内”。边界不清是导致图越画越大的主要原因。每次有人问“要不要把 XX 也加进去”你就得重新调整整张图的布局。提前画好边界能省掉大量返工时间。4. 不同类型图的实战画法从流程图到架构图的具体套路4.1 流程图重点是“判断条件”和“异常分支”流程图是最常见的图类型也是最容易画烂的。大多数人画流程图只画“正常路径”把异常分支全部省略结果就是图看起来很简洁但实际使用时发现“这个情况没覆盖到”。我的做法是先画正常路径再用不同颜色补上异常分支。正常路径用黑色或深蓝色异常分支用橙色或红色。这样读者一眼就能看出“主流程是什么”和“哪些地方可能出问题”。另一个关键点是判断条件的标注。很多人画菱形判断框时只写“是否满足条件”但不写具体条件是什么。这是大忌。正确的做法是把条件写清楚比如“库存 0”而不是“库存检查”。条件越具体图的可执行性越强。还有一个细节流程图的连线尽量避免交叉。如果实在避不开用“跳线”符号表示交叉但不连接。我见过一张流程图有十几处连线交叉读者根本分不清哪条线连到哪里。这种图还不如不画。4.2 时序图生命线和激活框的取舍时序图是表达“谁在什么时候调用了谁”的最佳工具但它也是最容易画得过于复杂的图类型。一张时序图如果有超过五个参与者基本上就很难在一屏内看清了。我的经验是时序图只画核心链路把非核心的调用折叠成注释。比如一个请求经过网关、鉴权、业务服务、缓存、数据库五个环节如果每个环节内部还有十几个子调用那就只画到“业务服务”这一层内部细节用文字注释说明。另一个技巧是合理使用“激活框”。激活框表示对象在处理请求的时间段但很多人画时序图时把所有对象的激活框都画得很长导致图看起来像一堆重叠的矩形。正确的做法是只给“当前正在处理”的对象画激活框其他对象保持静默。还有一点时序图的返回值不要省略。很多人只画请求箭头不画返回箭头导致读者不知道这个调用是同步还是异步、有没有返回值。返回箭头用虚线表示并在上面标注返回内容。4.3 架构图分层是王道但别硬分架构图的核心是“分层”。常见的分层方式包括按职责分接入层、业务层、数据层按部署分客户端、网关、服务端、存储按团队分前端团队、后端团队、算法团队、基础设施团队但分层不是越多越好。我见过有人把系统分成七层结果每层只有一两个模块图看起来又高又瘦信息密度极低。一般来说三到五层是比较舒服的范围。分层之后层与层之间的连线要尽量简洁。如果两层之间有大量交叉调用说明分层可能不合理需要考虑调整模块归属。架构图的美感很大程度上来自于“层内聚合、层间清晰”。另外架构图一定要有图例。颜色代表什么、形状代表什么、连线样式代表什么都要在图例里说清楚。我见过太多架构图用了一堆颜色但没有任何说明读者只能靠猜。4.4 状态机图状态命名和转移条件是关键状态机图在业务系统里非常实用尤其是订单、工单、审批流这类有明确状态流转的场景。但很多人画状态机图时状态命名很随意比如“处理中”“待处理”“已处理”读者根本分不清这几个状态的区别。我的建议是状态命名要具体、互斥、可判定。比如“待支付”“已支付待发货”“已发货待收货”“已完成”“已取消”每个状态都有明确的进入条件和退出条件。转移条件也要写清楚比如“支付成功”触发“待支付→已支付待发货”“超时未支付”触发“待支付→已取消”。状态机图还有一个容易忽略的点初始状态和终止状态要明确标注。初始状态用实心圆表示终止状态用带圈的实心圆表示。这样读者一眼就能看出流程的起点和终点。5. 工具选型从手绘到代码化绘图什么场景用什么工具5.1 手绘草图被低估的沟通利器很多人觉得手绘草图“不专业”但实际上在早期讨论和快速迭代阶段手绘草图是最有效的沟通工具。原因很简单草图传递的信号是“这个想法还不成熟欢迎修改”而精美的电子图传递的信号是“这个方案已经定了你只需要理解”。我在做方案评审时经常先在白板上画草图边画边讲让参与者随时打断和修改。等讨论得差不多了再拍照存档后续用工具重新画成正式图。这个流程比直接画电子图效率高得多因为电子图的修改成本高会让人不自觉地“护图”不愿意接受修改意见。如果你需要远程协作可以用简单的绘图工具模拟手绘效果比如 Excalidraw 这类工具它的默认风格就是手绘风非常适合早期讨论。5.2 代码化绘图可维护性的终极方案如果你的图需要频繁修改、需要版本管理、需要嵌入文档那么代码化绘图是唯一正确的选择。所谓代码化绘图就是用文本描述图的结构然后由工具渲染成图。常见的方案包括Mermaid语法简单支持流程图、时序图、状态图、类图等适合嵌入 Markdown 文档PlantUML功能更强大支持更多图类型但语法相对复杂Graphviz基于 DOT 语言适合画复杂的依赖关系图Diagrams用 Python 代码画架构图适合有编程背景的工程师代码化绘图的最大优势是可维护性。当你需要修改一个模块名称时只需要改一行文本所有相关的图都会自动更新。而用传统绘图工具你需要手动找到所有出现这个名称的地方逐一修改费时费力还容易漏。我自己的文档里大量使用 Mermaid因为它的语法足够简单而且大多数 Markdown 编辑器都支持渲染。下面是一个简单的时序图示例sequenceDiagram participant C as 客户端 participant G as 网关 participant S as 业务服务 participant D as 数据库 C-G: 发起请求 G-G: 鉴权校验 G-S: 转发请求 S-D: 查询数据 D--S: 返回结果 S--G: 返回响应 G--C: 返回响应注意虽然 Mermaid 很方便但它对复杂布局的控制能力有限。如果你的图需要精确的布局控制还是得用传统绘图工具。5.3 传统绘图工具什么时候必须用传统绘图工具如各种在线绘图平台和桌面绘图软件的优势在于布局自由度高、视觉效果可控。以下场景建议使用传统工具需要精确控制每个元素的位置和大小需要复杂的视觉效果阴影、渐变、图标需要导出高分辨率图片用于印刷或大屏展示需要与不熟悉代码化绘图的同事协作但传统工具也有明显的劣势版本管理困难、修改成本高、难以嵌入文档。所以我的建议是代码化绘图为主传统工具为辅。日常文档用代码化绘图重要汇报和对外材料用传统工具精修。5.4 工具选型对比表工具类型代表方案适合场景学习成本可维护性手绘草图白板、纸笔、手绘风工具早期讨论、快速迭代极低低代码化绘图Mermaid、PlantUML技术文档、版本管理中极高传统绘图在线绘图平台、桌面软件正式汇报、对外材料中高中专业建模建模工具复杂系统建模高中6. 让图“好看”的五个细节颜色、字体、对齐、留白、图例6.1 颜色不超过三种主色且要有语义颜色是 diagram-design 里最容易滥用的元素。很多人觉得颜色越多越好看结果画出来的图像彩虹一样读者根本不知道每种颜色代表什么。我的原则是主色不超过三种且每种颜色都要有明确的语义。比如蓝色核心模块或主流程绿色成功路径或正常状态红色异常路径或风险点灰色辅助信息或不在范围内的内容颜色一旦赋予语义就要在全图中保持一致。不能这张图里蓝色代表“前端”那张图里蓝色代表“数据库”。一致性是图可读性的基础。另外注意颜色的对比度。浅色背景上用深色文字深色背景上用浅色文字。我见过有人在深蓝色背景上用深蓝色文字标注根本看不清。这种低级错误在实际项目中并不少见。6.2 字体统一字号层级分明字体的问题主要有两个字号不统一和字体类型不统一。一张图里如果出现了三种以上的字号读者会感到混乱。我的建议是标题字号最大加粗模块名称字号中等常规注释字号最小可斜体字体类型也要统一。要么全用无衬线字体如黑体要么全用衬线字体如宋体不要混用。混用字体会让图看起来像拼凑出来的。还有一个细节文字不要压在连线上。我见过很多图连线穿过文字导致文字难以辨认。正确的做法是调整文字位置或连线路径让两者互不干扰。6.3 对齐网格化布局是专业感的来源对齐是区分“业余图”和“专业图”的最明显标志。业余图里的元素东一个西一个大小不一、间距不等专业图里的元素整齐排列间距均匀。实现对齐最简单的方法是使用网格。大多数绘图工具都支持网格吸附功能开启之后元素会自动对齐到网格线上。如果没有网格功能可以手动拉辅助线。对齐的另一个层面是间距一致。同一层级的模块之间间距应该相同不同层级之间间距可以不同但也要有规律。我通常用“8 的倍数”作为间距单位比如模块间距 16px、层级间距 32px。这样图看起来会有节奏感。6.4 留白图不是越满越好留白是很多新手忽略的元素。他们觉得图里空白太多是“浪费空间”于是把每个角落都塞满内容。结果就是图看起来拥挤、压抑读者找不到视觉休息的地方。留白的作用是引导视线和划分区域。模块之间的留白表示“这两个模块是独立的”层级之间的留白表示“这是两个不同的层级”。留白越充分图的层次感越强。我的经验是图的边缘至少留出 10% 的空白模块之间的间距至少是模块高度的 20%。如果图看起来太挤宁可拆成两张图也不要硬塞。6.5 图例别让读者猜图例是图的“说明书”。颜色代表什么、形状代表什么、连线样式代表什么都应该在图例里说清楚。但很多人觉得图例“占地方”于是省略不画结果读者只能靠猜。图例的位置通常在图的右下角或左下角不要放在图的中央干扰视线。图例的样式要简洁每个条目只需要“符号 简短说明”即可。如果图里用到的视觉元素很少比如只有两种颜色图例可以简化成一行文字说明比如“蓝色读操作橙色写操作”。但如果视觉元素超过三种就必须画完整的图例。7. 我在实际项目中踩过的坑五个真实教训7.1 教训一图太大导出后根本看不清早期做架构图时我总想把所有模块都画进去结果图越画越大导出成 PNG 之后在文档里缩放到合适大小文字根本看不清。读者需要放大到 200% 才能阅读体验极差。后来我学乖了先确定图的最终展示尺寸再决定画多少内容。如果图最终要放在 A4 文档里宽度不超过 800px那么图里的文字至少要有 12px模块数量不超过 15 个。超过这个限制就拆图。7.2 教训二连线交叉太多读者直接放弃有一次画一个调用关系图模块之间有大量交叉调用我硬是把所有连线都画上了结果图看起来像一团乱麻。评审时有人直接说“这张图我看不懂”然后整个讨论就卡住了。后来我改用“分层 分组”的方式重画把相互调用密集的模块放在同一层层间只画少量跨层连线。虽然丢失了一些细节但图的可读性大幅提升。读者先理解整体结构再根据需要深入细节。7.3 教训三颜色语义不一致造成误解有一次我在两张图里用了同一种颜色表示不同的含义。第一张图里蓝色表示“前端模块”第二张图里蓝色表示“数据库”。结果有人在评审时问“为什么前端模块直接连到了数据库”我才发现是颜色语义不一致造成的误解。从那以后我给自己定了一条规矩同一个项目里的所有图颜色语义必须统一。如果实在需要不同的颜色方案就在图例里明确说明并且尽量避免在同一份文档里混用。7.4 教训四忘记更新图导致文档过期这是最隐蔽的坑。代码改了文档里的图没改结果新同事按照过期的图去理解系统踩了一堆坑。这种问题在快速迭代的项目里尤其常见。解决方法是把图纳入版本管理。如果用代码化绘图图就和代码一起提交改代码时顺手改图。如果用传统工具就在文档里标注图的更新日期和对应版本并在代码变更时检查是否需要更新图。7.5 教训五过度美化反而降低可读性有一段时间我迷上了给图加各种视觉效果阴影、渐变、3D 效果、图标。结果图看起来确实“高级”了但可读性反而下降了。因为那些视觉效果分散了读者的注意力让读者花更多时间在“欣赏”上而不是“理解”上。后来我回归极简风格白底、黑字、少量颜色、无阴影、无渐变。图看起来朴素了但信息传递效率大幅提升。读者能在一秒内找到核心信息这才是 diagram-design 的终极目标。8. 从“能看”到“好用”建立自己的绘图规范和检查清单8.1 建立个人绘图规范如果你经常需要画图建议建立一套自己的绘图规范。规范不需要很复杂但至少要包含以下内容颜色规范每种颜色代表什么含义字体规范标题、正文、注释分别用什么字号和字体布局规范模块间距、层级间距、边缘留白命名规范模块名称的命名风格中文/英文、驼峰/下划线图例规范图例的位置和样式这套规范一旦建立你画图的速度会大幅提升因为不需要每次重新做决策。而且图与图之间的一致性会更好读者看起来更舒服。8.2 发布前的检查清单每次发布图之前花两分钟过一遍这个检查清单这张图的核心信息是什么读者能在一句话内复述出来吗图里的文字在最终展示尺寸下能看清吗颜色语义是否一致是否有图例说明连线是否有交叉交叉处是否有跳线标识是否有明确的起点和终点读者知道从哪里开始看吗是否有不在范围内但容易引起疑问的内容是否需要标注“不在范围内”图是否与当前代码/文档版本一致这个清单看起来简单但能帮你避免 90% 的常见问题。我自己的经验是每次发布前过一遍清单能省掉大量后续解释和返工的时间。8.3 持续迭代图是活的最后想说一点图不是画完就完了它是活的。系统在变图也要跟着变。我见过太多项目文档里的图还是两年前的版本早就和实际系统对不上了。所以我的建议是把图当成代码来维护。每次系统变更时检查相关图是否需要更新。如果图太多维护不过来就只维护核心图把次要图标记为“历史版本仅供参考”。图的价值在于“准确”不在于“多”。一张准确的简图胜过十张过期的详图。这个道理我在踩了无数次坑之后才真正明白。希望这些经验能帮你少走一些弯路画出真正“好用”的图。