1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次看到“diagram-design”这个标题很多人会以为它只是教你怎么画流程图、架构图或者线框图。但真正做过项目的人都知道图本身不是目的图是思考的投影。你画出来的每一根线、每一个箭头、每一个方框背后都对应着一个决策这个模块为什么独立这条数据为什么这样流这个状态为什么必须存在如果图没画清楚大概率是脑子没想清楚。diagram-design 这个项目核心就是围绕“如何用图来表达设计”这件事展开的。它不是一个单纯的绘图工具教程也不是某个软件的说明书而是一套从信息结构梳理、视觉语言定义、到最终图形输出的完整方法论。说得再直白一点它解决的是“脑子里有一团乱麻怎么把它变成别人一眼能看懂的图”这个问题。我见过太多团队在评审会上对着一张密密麻麻的架构图吵得不可开交最后发现大家理解的箭头方向都不一样。也见过不少开发者代码写得漂亮但让他画一张模块依赖图出来的东西像蜘蛛网自己都说不清哪条线是同步调用、哪条是异步消息。这些问题的根源都不在于不会用工具而在于没有一套设计图的思考框架。diagram-design 适合谁来参考如果你是技术负责人需要向非技术背景的同事解释系统结构如果你是产品经理想把业务流程画得让开发和设计都能看懂如果你是刚入行的开发者想通过画图来倒逼自己理解代码结构甚至你只是一个喜欢做笔记、想把知识整理成可视化图谱的学习者这套东西都能直接用上。它不挑工具用纸笔、用在线白板、用代码生成工具都行关键是背后的那套逻辑。接下来我会从整体设计思路、核心细节、实操过程、常见问题几个角度把 diagram-design 这套方法拆开来讲。每一部分都会配上我实际用过的参数、踩过的坑和总结出来的技巧尽量让你看完就能上手而不是停留在“知道了”的层面。2. 整体设计思路拆解为什么图要先想后画2.1 图的本质是信息压缩不是美术创作很多人一提到画图第一反应是“我审美不行”“我配色不好看”。这是一个非常大的误区。设计图的第一性原理是信息压缩而不是视觉美化。一张好的架构图应该让读者在 10 秒内抓住系统的核心模块和它们之间的关系一张好的流程图应该让读者在 30 秒内理解一个业务从开始到结束经过了哪些关键节点。我在实际项目中总结过一个判断标准如果你把图上的颜色全部去掉、把图标全部换成方块、把字体统一成最普通的样式读者依然能看懂这张图在说什么那这张图的信息结构就是合格的。反过来如果去掉颜色和图标之后图就变得无法理解那说明你在用视觉元素掩盖结构上的混乱。diagram-design 的整体思路就是先把“信息结构”这件事做扎实再去考虑视觉呈现。具体来说它把画图分成三个层次语义层这张图要表达什么概念有哪些实体实体之间是什么关系关系的方向和类型是什么结构层这些实体怎么分组哪些是同一层级哪些是包含关系信息的主次怎么安排视觉层用什么形状、颜色、线型、字号来区分不同的语义和结构大部分人的问题出在他们直接从语义层跳到了视觉层。脑子里刚有一个模糊的想法就打开工具开始拖方块拖到一半发现关系理不清又回头改结构改完结构发现颜色又不对了。来回折腾效率极低。正确的做法是先在纸上或者白板上把语义层和结构层想清楚再用工具去实现视觉层。我自己的习惯是任何一张重要的图先用铅笔在 A4 纸上画三遍草稿。第一遍只写文字和箭头不管形状第二遍调整分组和层级第三遍才确定用什么图形和颜色。这三遍草稿花的时间通常比直接在工具里改来改去要少得多。2.2 为什么选择“分层递进”而不是“一步到位”diagram-design 强调分层递进背后有一个很实际的考量人的工作记忆容量是有限的。心理学上有一个著名的“7±2 法则”说的是人一次能处理的信息块大约在 5 到 9 个之间。如果你在画图的时候同时要考虑模块划分、关系类型、颜色搭配、字体大小、对齐方式你的工作记忆瞬间就被占满了结果就是每个方面都做得马马虎虎。分层递进的好处是每一层只关注一个维度。在语义层你只需要问自己“这个系统里有哪些核心概念”在结构层你只需要问自己“这些概念怎么分组”在视觉层你只需要问自己“用什么视觉变量来区分它们”。每一层的问题都足够简单你的大脑可以专注处理。我试过在一个中等复杂度的微服务架构图上直接一步到位结果花了两个小时图还是乱糟糟的。后来改用分层递进的方法先花 15 分钟列出所有服务名称和调用关系再花 10 分钟做分组最后花 20 分钟在工具里实现总共 45 分钟就出了一张让团队都认可的图。这个效率差距是非常明显的。2.3 工具选型的核心逻辑图是给人看的不是给工具看的diagram-design 对工具的态度非常务实工具是手段不是目的。我见过有人为了画一张图先去学一个复杂的绘图软件学了三天还没开始画。这就本末倒置了。选择工具的核心逻辑只有三条表达力是否够用能不能画出你需要的形状、线型、分组框修改成本是否够低改一个模块名字、调整一个箭头方向需要几步操作协作是否方便别人能不能方便地查看、评论、甚至一起编辑基于这三条我把常用工具分成几类你可以根据自己的场景选工具类型代表形式适合场景修改成本协作便利度纸笔/白板实体白板、纸张早期构思、快速讨论低擦掉重画高面对面通用绘图工具在线白板类中等复杂度、需要协作中高代码生成工具文本描述生成图需要版本控制、频繁更新低改文本中需要懂语法专业建模工具特定领域建模软件大型系统、严格规范高低我个人的习惯是早期构思一律用纸笔中期协作一律用在线白板最终定稿如果图会频繁更新就用代码生成工具。这个组合用了好几年基本没遇到过什么大问题。注意不要在一开始就纠结工具。我见过一个团队光是选绘图工具就开了三次会图一张没画。先用手边最顺手的工具把第一版画出来比什么都重要。3. 核心细节解析与实操要点从概念到图形的关键转换3.1 实体识别怎么判断哪些东西该画成方块画图的第一步是确定图上有哪些“实体”。实体就是你要表达的核心概念通常用方块、圆形或者其他形状来表示。听起来很简单但实际操作中很多人会把不该画的东西画上去或者该画的东西漏掉。我总结了一个实体识别的三问法第一问这个东西有状态吗如果一个概念有自己的状态比如“订单”有待支付、已支付、已发货等状态那它大概率是一个实体。第二问这个东西有行为吗如果一个概念会主动做事情比如“支付服务”会处理支付请求那它也是一个实体。第三问这个东西会被其他实体引用吗如果一个概念会被多个其他概念提到比如“用户”会被订单、评论、日志都引用那它必须是一个独立实体。反过来如果一个东西既没有状态、也没有行为、也不会被引用那它可能只是一个属性不需要单独画成方块。比如“用户名”通常只是“用户”实体的一个属性不需要单独画一个方块。在实际操作中我建议你先用名词列表法把脑子里所有相关的名词都写下来然后逐个用三问法过滤。这个过程通常会产生 20 到 30 个候选名词过滤完之后剩下 8 到 12 个核心实体。这个数量区间是比较合理的太少说明抽象层次太高太多说明抽象层次太低。实操心得我习惯在实体识别阶段用不同颜色的便签纸。黄色写候选实体绿色写确定的实体红色写被排除的候选。这样一眼就能看出哪些是核心哪些是边缘。便签纸的好处是可以随时移动和重新分组比在软件里拖来拖去快得多。3.2 关系定义箭头不是随便画的实体确定之后下一步是定义实体之间的关系。这是最容易出问题的地方。我见过太多图箭头画得到处都是但没人说得清每个箭头到底代表什么。diagram-design 对关系的定义非常严格要求每一条线都必须回答三个问题方向是 A 到 B还是 B 到 A还是双向类型是调用、依赖、继承、包含、还是数据流强度是强依赖还是弱依赖是同步还是异步这三个问题不回答清楚线就不应该画上去。我自己的做法是在画线之前先用文字把关系写出来。比如“订单服务”调用“支付服务”的支付接口同步调用强依赖。“用户服务”依赖“用户数据库”读写操作强依赖。“日志服务”订阅“订单服务”的事件异步消息弱依赖。把这些关系用文字列清楚之后再转换成图形就不会出现“这条线到底什么意思”的问题。而且文字列表还有一个好处它可以作为图的图例或者注释帮助读者理解。关于线型的选择我有一套固定的规则实线箭头表示强依赖、同步调用、直接数据流。虚线箭头表示弱依赖、异步消息、间接影响。无箭头实线表示双向关系或者关联关系。带菱形的线表示包含关系菱形在包含方。带三角的线表示继承或实现关系三角在父类方。这套规则不是强制标准但一旦你在一个项目里固定下来就要在所有图中保持一致。一致性比“正确性”更重要因为读者是通过对比来理解图的。3.3 分组与层级怎么让图有“呼吸感”一张图如果所有方块都平铺在同一层读者会感到窒息。分组和层级是给图增加“呼吸感”的关键。分组就是把相关的实体放在一起层级就是让重要的实体更突出。diagram-design 推荐的分组方法有两种按功能分组把做同一类事情的实体放在一起。比如所有和“用户”相关的服务放在一个框里所有和“订单”相关的服务放在另一个框里。按层级分组把同一抽象层次的实体放在一起。比如所有“前端”放在最上层所有“后端服务”放在中间层所有“数据存储”放在最下层。这两种方法可以组合使用。我通常的做法是先按层级分大组再在每一层内部按功能分小组。这样出来的图既有纵向的层次感又有横向的功能划分。分组的视觉表达我建议用浅色背景框加圆角。背景框的颜色要足够浅不能抢了里面实体的风头。圆角比直角更柔和视觉上更容易被接受。背景框的标题放在左上角字号比实体字号小一号颜色用灰色不要用黑色。注意分组框不要嵌套超过三层。三层以上的嵌套读者会迷失在框里面。如果确实需要更复杂的层级考虑拆成多张图或者用编号来替代嵌套。3.4 视觉变量的分配颜色、形状、字号怎么定视觉变量是图的语言。diagram-design 把视觉变量分成四类形状、颜色、大小、位置。每一类都有明确的用途不能混用。形状用来区分实体的类型。比如方形表示服务圆形表示数据存储菱形表示决策点圆柱形表示数据库。颜色用来区分实体的分组或者状态。比如蓝色表示用户相关绿色表示订单相关红色表示异常状态。大小用来表示实体的重要程度或者规模。比如核心服务用大一点的方块辅助服务用小一点的。位置用来表示实体的层级或者流程顺序。比如上层放前端下层放后端从左到右表示时间顺序。这四类变量中颜色是最容易被滥用的。我见过一张图用了十几种颜色看起来像彩虹但完全不知道每种颜色代表什么。我的建议是一张图的颜色不要超过五种而且每种颜色都要有明确的语义。如果实在需要更多区分用形状或者编号来补充不要继续加颜色。字号方面我通常用三档大号图的标题或者核心模块名称。中号普通实体名称。小号注释、图例、分组框标题。三档足够了。不要用超过三档字号否则图会显得杂乱。4. 实操过程与核心环节实现从零画出一张合格的设计图4.1 准备阶段明确图的读者和目的在动手画之前必须先回答两个问题这张图给谁看看完之后要做什么这两个问题决定了图的详细程度和表达重点。如果图是给开发团队看的用于讨论技术方案那图可以详细一些包含具体的服务名称、接口名称、数据表名称。如果图是给非技术背景的同事看的用于汇报或者评审那图要抽象一些用业务语言而不是技术语言。我自己的习惯是在图的左上角或者右下角写一行小字“读者XXX目的XXX”。这行字不一定要最终保留但在画图过程中会时刻提醒自己不要跑偏。准备阶段的另一个重要工作是收集素材。把相关的文档、代码、聊天记录都翻一遍把关键信息摘出来。我通常会用一张 A4 纸左边写“已知信息”右边写“待确认信息”。画图的过程很大程度上就是不断把“待确认信息”变成“已知信息”的过程。4.2 草稿阶段三遍草稿法的具体操作前面提到了三遍草稿法这里展开讲一下具体怎么操作。第一遍草稿只写文字和箭头。拿一张白纸把所有实体名称用文字写下来然后用箭头连接它们。不要管形状、颜色、对齐。这一遍的目标是把关系理清楚。写完之后检查一遍有没有循环依赖有没有孤立的实体有没有关系方向反了的这一遍通常需要 10 到 15 分钟。第二遍草稿调整分组和层级。在第一遍的基础上用铅笔轻轻画一些框把相关的实体圈在一起。然后调整实体的位置让层级关系更明显。这一遍的目标是让结构清晰。画完之后检查一遍分组是否合理层级是否超过三层有没有哪个框特别空或者特别挤这一遍通常需要 10 到 15 分钟。第三遍草稿确定视觉方案。在第二遍的基础上用不同颜色的笔标注不同类型的实体用不同线型标注不同类型的关系。这一遍的目标是让视觉表达一致。画完之后检查一遍颜色是否超过五种线型是否一致字号是否有层次这一遍通常需要 5 到 10 分钟。三遍草稿加起来大约 30 到 40 分钟。这个时间投入是非常值得的因为它可以避免你在工具里反复修改节省的时间往往是草稿时间的几倍。4.3 工具实现以在线白板为例的完整流程草稿确定之后就可以在工具里实现了。这里以在线白板为例讲一下完整的操作流程。其他工具的操作逻辑类似只是具体按钮位置不同。第一步设置画布和网格。新建一个白板把画布尺寸设置为 A3 或者 16:9打开网格和对齐功能。网格间距建议设置为 20 像素这个间距在大多数屏幕上看起来比较舒服。对齐功能一定要打开否则手动对齐会非常痛苦。第二步放置分组框。根据第二遍草稿的分组先画出所有的背景框。背景框用浅灰色或者浅蓝色透明度设置为 20% 到 30%。框的标题写在左上角字号比实体小一号。这一步不要放实体先把框架搭好。第三步放置实体。根据第一遍草稿的实体列表逐个放置方块。方块的大小要统一建议宽度 120 像素、高度 60 像素。如果实体名称比较长可以适当加宽但不要加高。所有方块的对齐方式设置为“水平居中”和“垂直居中”。第四步连接关系。根据第一遍草稿的关系列表逐个画线。画线的时候注意线要连接到方块的边缘不要连接到中心。大多数工具都有“连接点”功能把线吸附到连接点上移动方块的时候线会自动跟随。第五步调整视觉变量。根据第三遍草稿的视觉方案给方块上色、给线设置线型、调整字号。这一步要克制不要临时起意加新的颜色或者形状。如果发现草稿有问题回到纸上改草稿不要在工具里直接改。第六步添加图例和注释。在图的空白处添加图例说明每种颜色、每种线型代表什么。如果有需要特别说明的地方用注释框标出来。图例和注释的字号要小颜色要淡不要抢主图的风头。整个工具实现过程熟练之后大约需要 30 到 60 分钟。如果超过这个时间说明草稿阶段没做好建议回到纸上重新画草稿。4.4 参数计算与选择以布局间距为例布局间距是影响图的可读性的关键参数但很多人是凭感觉设置的。这里给出一套可计算的方法。假设你的实体方块宽度是 W高度是 H那么同一分组内实体之间的水平间距建议为 W 的 0.3 到 0.5 倍。如果 W120间距就是 36 到 60 像素。同一分组内实体之间的垂直间距建议为 H 的 0.5 到 0.8 倍。如果 H60间距就是 30 到 48 像素。不同分组之间的间距建议为 W 的 0.8 到 1.2 倍。如果 W120间距就是 96 到 144 像素。分组框的内边距建议为 20 到 30 像素。这个值太小会让框显得拥挤太大又浪费空间。这些数值不是绝对的但可以作为起点。实际调整的时候遵循一个原则让图看起来“透气”但不“散架”。如果觉得太挤先加大分组间距如果觉得太散先减小同组内间距。实操心得我习惯在调整间距的时候把图缩小到 50% 查看。缩小之后如果还能看清分组和主要关系说明间距是合适的。如果缩小之后变成一团糊说明间距太小了。5. 常见问题与排查技巧实录那些年我踩过的坑5.1 图太乱怎么办从信息层找原因图太乱是最常见的问题。很多人第一反应是“换个工具”或者“调一下颜色”但这些都是治标不治本。图乱的根源几乎总是信息层的问题。我总结了一个排查顺序实体是不是太多了如果图上有超过 15 个实体大概率需要拆分。拆分的依据可以是功能模块、可以是业务流程阶段、可以是用户角色。关系是不是太杂了如果两个实体之间有超过三条线说明这两个实体之间的耦合太紧可能需要引入中间层。分组是不是不合理如果某个分组框里只有一两个实体或者某个分组框里挤了七八个实体说明分组逻辑有问题。层级是不是太深了如果嵌套超过三层读者会迷失。考虑用编号或者颜色来替代嵌套。按照这个顺序排查通常能在 10 分钟内找到问题所在。找到问题之后回到纸上重新画草稿不要在工具里硬改。5.2 别人看不懂怎么办换位思考的三个检查点你画的图别人看不懂通常是因为你默认了一些别人不知道的背景知识。diagram-design 建议在发布图之前做三个检查检查点一有没有未定义的缩写如果图上出现了“OMS”“WMS”这样的缩写而读者可能不知道它们的意思要么写全称要么在图例里说明。检查点二有没有隐含的假设比如你画了一条从 A 到 B 的箭头默认读者知道这是同步调用。如果读者可能误解为异步消息就要在线旁边标注“同步”。检查点三有没有缺少上下文图上的实体读者是否知道它们属于哪个系统、哪个团队、哪个环境如果不知道就要在分组框标题或者注释里说明。我自己的做法是把图发给一个完全不了解这个项目的同事让他用一句话说出这张图在讲什么。如果他说对了说明图是清楚的如果他说错了或者说不出来说明还有改进空间。5.3 图频繁变更怎么办用代码生成图来解耦如果你的图需要频繁更新比如每次迭代都要改那用传统绘图工具会非常痛苦。每次改都要重新拖方块、重新对齐、重新调颜色。这种情况下我强烈建议用代码生成图的方式。代码生成图的核心思想是用文本描述图的结构用工具把文本渲染成图。这样你只需要维护文本图会自动更新。常见的文本描述格式有 DOT、PlantUML、Mermaid 等。虽然这些格式的语法不同但核心逻辑是一样的先定义实体再定义关系最后定义视觉样式。以 DOT 为例一个简单的描述是这样的digraph G { rankdirLR; node [shapebox, stylefilled, fillcolorlightblue]; User - Order [label创建]; Order - Payment [label支付]; Payment - Order [label回调]; Order - Inventory [label扣减]; }这段文本渲染出来就是一张从左到右的流程图。改的时候只需要改文本比如把“创建”改成“提交”图会自动更新。而且文本可以放在版本控制里每次变更都有记录比二进制图片文件友好得多。注意代码生成图适合结构相对稳定的图。如果图的结构经常大改维护文本的成本可能比直接拖方块还高。我通常是在图的结构稳定之后才切换到代码生成的方式。5.4 常见问题速查表问题现象可能原因排查方法解决建议图太乱看不清关系实体太多或关系太杂数一下实体数量和连线数量拆分成多张图或引入中间层别人看不懂图缺少图例或上下文让不了解项目的人试读补充图例、注释、分组标题图频繁变更维护成本高用传统工具手动修改统计一下每周修改次数切换到代码生成图的方式颜色太多眼花缭乱视觉变量分配不合理数一下用了多少种颜色颜色控制在五种以内用形状补充分组框嵌套太深层级设计过于复杂数一下最大嵌套层数嵌套不超过三层用编号替代箭头方向混乱关系定义不清晰逐条检查箭头的语义先用文字列出关系再画图图打印出来看不清字号太小或对比度不够打印一份测试字号不小于 10pt颜色对比度要够6. 进阶技巧让图从“合格”变成“优秀”6.1 用“视觉动线”引导读者阅读一张优秀的图应该像一篇好文章一样有明确的阅读顺序。diagram-design 把这个叫做视觉动线。视觉动线就是读者的眼睛在图上移动的路径。最常见的视觉动线是从左到右、从上到下。你可以通过以下方式强化这条动线把起始实体放在左上角把终止实体放在右下角。用箭头方向强化从左到右的流动。用颜色渐变表示从早到晚或者从主到次。用大小变化表示从重到轻。我试过在一张流程图上把所有的箭头都改成从左到右然后把反馈回路画成从下往上的弧线。改完之后读者理解流程的时间缩短了一半。这就是视觉动线的力量。6.2 用“留白”代替“填满”新手画图总想把所有空白都填满。但留白是图的重要组成部分。留白给读者喘息的空间也给图本身增加高级感。我自己的留白规则是图的四周至少留出 10% 的空白。分组框之间至少留出 5% 的空白。实体之间至少留出一个实体宽度的 30% 作为空白。如果图的内容太多留不出空白那就说明需要拆图了。不要为了塞进一张图而牺牲留白。6.3 用“一致性”建立专业感一致性是专业图和非专业图的最大区别。一致性体现在形状一致同类型的实体用同一种形状。颜色一致同一种语义用同一种颜色。线型一致同一种关系用同一种线型。字号一致同一层级的文字用同一种字号。间距一致同一层级的间距用同一种数值。做到这五个一致图看起来就会很专业。我见过一些图内容其实很简单但因为一致性做得好看起来非常舒服。也见过一些图内容很复杂但因为一致性差看起来像草稿。实操心得我习惯在图的右下角放一个“样式说明”的小框列出本图使用的形状、颜色、线型及其含义。这样即使图被单独传播读者也能理解视觉元素的语义。7. 我个人的实操体会画了这么多年图我最大的体会是图的质量取决于你思考的质量。一张混乱的图背后一定是混乱的思考一张清晰的图背后一定是清晰的思考。diagram-design 这套方法本质上是在逼你把思考过程外化出来让你看到自己思维中的漏洞和跳跃。另一个体会是不要追求一次画好。我见过很多人画图的时候反复撤销、反复调整一张图花了两三个小时。其实第一版图只要把核心关系表达清楚就够了细节可以在后续迭代中完善。先完成再完美。最后分享一个小技巧如果你觉得一张图怎么画都不对试着把它讲给别人听。在讲的过程中你会发现自己卡在哪里也会发现哪些地方别人听不懂。讲完之后再回来改图通常会有豁然开朗的感觉。这个技巧我用了很多年几乎每次都管用。