1. 从diagram-design这个标题说起它到底在解决什么问题第一次看到diagram-design这个标题我脑子里冒出来的第一个念头是这大概率不是一个单纯的画图工具而是一套关于如何把复杂信息用图形讲清楚的方法论。为什么这么说因为如果只是画图标题通常会叫diagram-tool或者chart-library而design这个词的出现意味着重点在于设计决策——什么时候用流程图、什么时候用架构图、节点怎么排布、颜色怎么分配、信息密度怎么控制。我在实际工作中接触过大量图的需求技术方案评审要画架构图产品需求评审要画流程图给非技术同事讲系统要画数据流图写文档要画状态机图。几乎每一次真正让人头疼的都不是用什么工具画而是这张图到底该怎么设计才能让人一眼看懂。工具只是载体设计才是核心。这就是diagram-design这个主题的价值所在——它关注的是一张图从信息到可读图形的转化过程。这篇文章适合几类人看一是经常需要画技术图但总觉得画出来不够专业的开发者二是需要给团队输出方案图、流程图的 product/项目角色三是对信息可视化有兴趣、想把画图这件事从随手涂鸦提升到有章法可循的任何人。我会从图形类型的选择逻辑讲起一路讲到布局、配色、标注、工具链以及我自己踩过的那些坑。全程不堆砌术语尽量用你拿到一个需求之后该怎么做的视角来展开。需要先说明一点下面涉及的具体工具、参数、代码示例都是基于我个人的常见实践总结出来的合理方案不是唯一答案。你可以把它当成一套默认起点在此基础上按自己的场景调整。2. 先选对图形类型再谈画得好不好看2.1 图形类型选错的代价比画得丑大得多我见过太多这样的情况一个人花了两个小时把一张图画得非常精致配色讲究、对齐完美结果评审的时候别人第一句话是这个图想表达什么。问题不在美观度而在图形类型和表达意图不匹配。举个具体的例子。假设你要说明用户下单后订单系统、库存系统、支付系统之间怎么交互。如果你画成一张流程图flowchart用菱形表示判断、矩形表示步骤那读者会默认这是一条顺序执行的路径但实际上这三个系统之间是并发的消息交互有请求有响应还有超时和重试。这时候正确的选择应该是时序图sequence diagram或者数据流图而不是流程图。再比如你要说明一个服务的内部由哪些模块组成、模块之间怎么调用。这时候用架构图通常用分层或分组的方式表达比用流程图合适得多因为架构图强调的是结构关系而流程图强调的是执行顺序。我把常见的图形类型和它们的适用场景整理成一张表方便你对照图形类型核心表达典型场景容易踩的坑流程图步骤与判断的顺序业务流程、算法逻辑把并发画成串行时序图对象间的消息交互接口调用、系统协作消息过多导致图过长架构图模块的层次与依赖系统组成、部署结构层次混乱、连线交叉状态机图状态与迁移条件订单状态、连接状态漏掉异常状态ER图实体与关系数据库设计关系基数标错数据流图数据的流动与加工数据处理管道和流程图混淆这张表我建议你存下来。每次拿到画图需求先花三十秒对照一下确认图形类型选对了再动手。这三十秒能省掉后面两个小时的返工。2.2 一个判断图形类型的实用口诀如果上面的表你还是记不住我给你一个更简单的判断方法我管它叫三问法第一问读者关心的是顺序还是结构关心顺序往流程图/时序图方向走关心结构往架构图/ER图方向走。第二问有没有时间这个维度如果交互是有先后、有等待、有响应的时序图几乎不会错。第三问有没有状态这个概念如果某个东西会在多个状态之间切换且切换有条件状态机图是最清晰的表达。这三问基本能覆盖八成以上的场景。剩下的两成往往是复合需求需要在一张图里融合多种表达这时候就要考虑主图辅图的方式而不是硬塞进一张图里。2.3 什么时候该拆成多张图我个人的经验是当一张图上的节点超过 15 个或者连线交叉超过 5 处就该考虑拆图了。这不是硬性标准而是一个可读性警戒线。超过这个量级读者的眼睛会在图上迷路再好的配色也救不回来。拆图的原则是按关注点拆而不是按数量平均拆。比如一个电商系统的架构图可以拆成用户侧架构交易侧架构履约侧架构三张每张聚焦一个关注点。这样每张图都清爽读者也能按需查看。3. 布局是图的骨架为什么你的图总是看着乱3.1 布局混乱的根源没有确定主方向一张图看着乱九成情况下不是元素太多而是没有一个明确的主方向。什么叫主方向就是读者的视线应该沿着哪条线走。流程图的主方向通常是从上到下或从左到右架构图的主方向通常是从上层到下层时序图的主方向是从上到下的时间轴。一旦主方向确定所有元素都应该围绕这个方向排列而不是东一个西一个。我见过一张架构图上层模块画在左上角下层模块画在右下角中间还穿插了几个横向的箭头。读者的视线被迫走Z字形看三遍才能理清层次。这就是典型的主方向缺失。3.2 分层与分组让图有呼吸感确定主方向之后下一步是分层和分组。分层解决上下关系分组解决左右关系。以一张典型的后端架构图为例我会这样分层接入层网关、负载均衡应用层各个业务服务领域层核心业务逻辑基础设施层数据库、缓存、消息队列每一层内部再用分组框把相关的模块圈在一起。比如应用层里订单相关服务放一组用户相关服务放一组。这样读者一眼就能看出哪些是一伙的。分组的时候有个细节要注意分组框之间要留出足够的间距。我一般会让组间距至少是组内元素间距的 1.5 倍。这个比例能让视觉上自然形成块的感觉而不是糊成一片。3.3 连线能少则少能直则直连线是图里最容易失控的元素。我的原则是三条能少则少如果两个模块的关系可以通过分组隐含表达就不要画连线。比如同一个分组内的模块默认它们有关系不必每个都连。能直则直优先用直线其次用折线最后才用曲线。曲线虽然好看但容易和其他元素重叠造成视觉干扰。交叉要处理如果两条连线必须交叉用跳线一条线在交叉处画个小弧跳过另一条来区分而不是让它们直接叠在一起。关于连线的方向还有一个经验箭头方向要统一。如果一张图里有的箭头从左到右、有的从右到左、有的从上到下读者会晕。统一成一个主方向例外情况才用反向箭头并且用颜色或线型区分。3.4 对齐最容易被忽视但最影响观感的细节对齐这件事说起来简单做起来很多人会忽略。我见过太多图节点大小不一、位置随意看着就是不专业。其实只要做到两点观感立刻提升一个档次同级元素对齐同一层的节点顶部或中心对齐。等间距同级节点之间的水平或垂直间距保持一致。如果你用的是支持自动布局的工具比如基于文本描述的绘图工具这两点通常会自动帮你处理好。如果是手动拖拽的工具那就得靠网格和参考线。我个人的习惯是打开网格吸附间距统一设为 40px 或 60px这样出来的图整齐度会高很多。4. 配色与标注让图会说话的隐形推手4.1 配色的第一原则颜色是信息不是装饰很多人画图喜欢用一堆鲜艳的颜色觉得这样好看。但从信息传达的角度颜色应该承载信息而不是单纯为了好看。如果两种颜色没有表达任何区别那它们就不该存在。我的配色习惯是这样的主色调整张图用一个主色系比如蓝色系用于大部分普通节点。强调色用一到两个对比色比如橙色、红色用于需要特别注意的节点比如核心服务风险点。中性色灰色用于辅助信息、背景分组框。这样一张图里颜色种类控制在 3 到 4 种读者一眼就能分辨哪些是重点。4.2 具体配色方案参考如果你对配色没把握可以直接用下面这套我常用的方案十六进制色值用途色值说明主色普通节点#4A90D9蓝色稳重不刺眼强调色重点节点#E8833A橙色醒目但不刺眼警示色风险节点#D9534F红色仅用于真正需要警示的地方分组背景#F5F7FA浅灰不抢主体连线#8C9BAB中灰清晰但不突兀文字#2C3E50深灰蓝比纯黑柔和这套配色我用了很久在各种投影仪和屏幕上表现都稳定。红色一定要慎用一张图里红色节点超过两个警示效果就失效了。4.3 标注把图里说不清的话补上图能表达结构但表达不了为什么。这时候就需要标注。标注的形式可以是图上的文字说明也可以是图旁边的注释。我常用的标注方式有三种节点内标注在节点框里写清楚模块名 一句话职责比如订单服务负责下单、取消、查询。连线标注在连线上标注协议或数据比如HTTP/JSON异步消息。图例在图的一角放一个图例说明颜色和线型的含义。标注的文字要短。我见过有人在节点里写了三行字结果节点框被撑得巨大整张图比例失调。节点内的文字控制在 10 个字以内详细说明放到图外的文档里。4.4 一个反直觉的建议先画黑白稿这是我个人的一个习惯也是我强烈推荐给别人的先用黑白灰画一版确认信息结构没问题再上色。为什么因为颜色会掩盖结构问题。一张结构混乱的图上了色之后看着好像还行但把颜色去掉问题立刻暴露。先画黑白稿强迫自己只靠布局和文字把信息讲清楚等结构稳了颜色只是锦上添花。5. 工具链选择从手写到代码化绘图5.1 三类绘图工具各有各的适用场景市面上的绘图工具大致分三类我按控制粒度从低到高排一下拖拽式工具鼠标拖拽节点所见即所得。上手快但精细控制难版本管理麻烦。文本描述式工具用代码或标记语言描述图工具自动渲染。适合需要版本管理、需要批量生成的场景。代码绘图库用编程语言直接画图控制粒度最细适合嵌入到自动化流程里。这三类没有绝对的好坏关键看场景。如果是临时给会议画一张图拖拽式最快如果是技术文档里的图需要跟着代码一起版本管理文本描述式更合适如果是自动化生成报表图代码绘图库是唯一选择。5.2 文本描述式绘图为什么我越来越偏爱它我这两年越来越偏爱文本描述式的绘图方式原因有三个可版本管理图的源文件是纯文本可以放进 Git每次修改都有记录能 diff、能回滚。可复用常用的图形片段可以抽成模板下次直接引用。一致性样式由统一的配置控制不会出现这张图蓝色、那张图绿色的混乱。以常见的文本绘图语法为例画一个简单的流程图大概是这样graph TD A[用户请求] -- B{是否登录} B --|是| C[查询订单] B --|否| D[跳转登录] C -- E[返回结果]这段描述渲染出来就是一张从上到下的流程图。改起来也方便想加一个节点就加一行不用重新拖拽布局。5.3 代码绘图库的适用边界代码绘图库比如用 Python 的绘图库直接生成图适合的场景比较特定需要批量生成、需要和数据处理 pipeline 集成。比如你有一个服务依赖关系的数据源想每天自动生成一张最新的架构图那用代码绘图库就是对的。但如果是手工维护的、变化不频繁的图用代码绘图库就有点杀鸡用牛刀了维护成本反而更高。我一般只在图的数据来源是动态的这种情况下才用代码绘图。5.4 工具选型的一个实用决策流程我把工具选型的决策过程整理成一个简单的流程你可以照着走这张图需要版本管理吗需要 → 排除纯拖拽式选文本描述式或代码绘图。图的数据是动态的吗是 → 选代码绘图库。图需要频繁手工调整吗是 → 文本描述式更灵活。只是临时画一张是 → 拖拽式最快。按这个流程走基本不会选错。6. 实操中踩过的坑与排查思路6.1 坑一图渲染出来和预期完全不一样这是用文本描述式工具时最常见的问题。你写了一段描述渲染出来发现节点位置、连线走向和你想象的完全不同。排查思路先检查语法有没有写错尤其是缩进和箭头符号。文本绘图工具对语法很敏感一个空格错了就可能导致整张图结构变化。如果语法没问题那就是布局引擎的自动决策和你的预期不一致。这时候不要硬刚而是调整描述的结构——比如把某个子图单独抽出来或者改变节点的声明顺序往往能引导布局引擎给出更合理的结果。6.2 坑二图太大渲染出来糊成一团节点一多自动布局就容易失控。我遇到过一次一张图有 40 多个节点渲染出来连线密密麻麻完全没法看。解决办法拆图。前面说过超过 15 个节点就该考虑拆。拆的时候按关注点拆每张图聚焦一个主题。如果实在不能拆那就用子图subgraph的方式把节点分组让布局引擎按组来排布会好很多。6.3 坑三中文字体显示异常用某些绘图工具时中文可能显示成方块或者字体很难看。这通常是字体配置的问题。解决办法在配置里显式指定一个支持中文的字体。如果是网页端渲染确保 CSS 里 font-family 包含了中文字体如果是本地渲染检查系统字体是否安装。我一般会指定一个无衬线中文字体 英文回退的组合保证中英文都好看。6.4 坑四改了图但忘了同步文档这是流程上的坑不是技术坑。图改了但引用这张图的文档没更新导致文档和图对不上。解决办法把图的源文件和文档放在同一个仓库里改图的时候顺手检查引用。如果工具支持尽量用引用而不是复制粘贴的方式在文档里嵌入图这样图一改文档自动更新。6.5 一个通用的排查心法遇到绘图问题我的通用排查顺序是先查语法再查结构最后查样式。语法错误最容易发现也最容易修结构问题需要调整描述方式样式问题最后处理因为样式不影响信息传达优先级最低。按这个顺序排查效率最高。7. 从能画到画得好几个提升图质量的习惯7.1 画之前先写一句话说明我现在的习惯是动手画图之前先用一句话写下这张图要说明什么。比如这张图要说明订单创建后库存和支付两个系统的协作流程。这一句话就是图的主题句画的过程中随时对照确保没有跑偏。这个习惯看起来简单但效果显著。很多图之所以乱就是因为画的人自己都没想清楚要表达什么边画边想最后画出一堆无关的东西。7.2 画完之后隔夜再看这是一个很土但很有效的办法画完图之后不要马上交付放一晚上第二天再看。隔了一夜你对图的作者视角会淡化更容易用读者视角发现问题。我很多次都是第二天一看发现某个连线多余、某个标注不清。如果时间不允许隔夜那就至少离开座位走一圈再回来看效果也有个七八成。7.3 让别人给你讲一遍终极检验方法把图给一个不了解背景的同事让他照着图给你讲一遍流程。如果他能讲对说明图合格如果他卡在某处那处就是图的信息断点需要补标注或调整结构。这个方法我强烈推荐。自己看自己的图永远觉得很清楚因为脑子里有背景知识。只有别人讲一遍才能暴露真正的可读性问题。7.4 建立自己的图形素材库画得多了你会发现很多图形片段是重复的网关、数据库、消息队列、用户图标……与其每次重画不如建一个自己的素材库把这些常用元素存起来下次直接引用。素材库不用很复杂一个文件夹放几个模板文件就行。关键是持续积累。我现在的素材库里有几十个常用片段画新图的时候能省掉一半以上的时间。8. 关于 diagram-design 这件事我最后想说的画图这件事工具永远在变但把复杂信息讲清楚这个核心目标不会变。我见过用最朴素的工具画出极清晰图的人也见过用最花哨的工具画出让人看不懂的图的人。差别不在工具在于画图的人有没有想清楚这张图给谁看、要传达什么。如果你刚开始接触 diagram-design我的建议是先别急着学工具先练用一句话说清一张图的能力。拿到需求先想清楚图形类型、主方向、分层分组这些想明白了用什么工具画都是水到渠成的事。至于工具选一个顺手的用熟它比换来换去强。文本描述式也好拖拽式也好能稳定产出清晰图的工具就是好工具。我自己是文本描述式和拖拽式混着用看场景切换没有执念。最后分享一个小技巧如果你觉得一张图差点意思但又说不出哪里不对试试把它缩小到 50% 看。缩小之后结构问题会放大配色问题会缩小你更容易判断到底是结构还是样式的问题。这个技巧我用了很多年屡试不爽。