1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次听到 “diagram-design” 这个词很多人会以为它只是“画图工具”的另一个说法。但真正在项目里摸爬滚打过的人都知道图这件事从来不是“画出来”那么简单。它背后牵扯的是信息结构、视觉语法、协作流程、版本管理以及最终能不能让看图的人在三秒内抓住重点。我见过太多团队技术方案写得扎实一到画架构图就变成“方框加箭头谁看谁懵”也见过不少独立开发者功能做得漂亮README 里的流程图却让人直接关掉页面。diagram-design 要解决的正是这个从“能看”到“好懂”之间的鸿沟。简单说diagram-design 是一套围绕“图表设计”展开的方法论加工具链实践。它不局限于某一种图形语言而是把流程图、架构图、时序图、状态图、思维导图、甚至简单的数据关系图都纳入同一个设计思维框架里。它的核心主张是图不是文档的装饰图是信息的压缩包。一张好的图应该像一段精心重构的代码——没有冗余分支没有歧义路径每个节点都有存在的理由每条连线都承载明确语义。这套东西适合谁如果你是需要频繁输出技术方案、系统设计、流程说明的工程师它帮你把“画图”从体力活变成设计活如果你是产品经理或项目协调人它让你用图对齐认知减少会议里的“我以为”如果你是写博客、做教程的内容创作者它让你的示意图不再是从模板库里随便拖出来的“通用素材”而是有辨识度、有逻辑层次的信息载体。哪怕你只是偶尔需要画一张图来说明问题理解 diagram-design 的思路也能让你少走很多弯路。我最初接触这个方向是因为一个内部工具的重构项目。当时团队有五个人每个人画的架构图风格都不一样有人用圆角矩形有人用直角有人把数据库画成圆柱有人画成方块箭头方向更是随心所欲。结果就是每次评审会前十分钟都在争论“这个箭头到底代表数据流还是控制流”。后来我们花了两周时间把 diagram-design 的基本原则落地成一套内部规范配合几个轻量工具情况才彻底改观。这篇文章就是把这套从踩坑里长出来的经验完整拆给你看。2. 核心设计原则为什么你的图总是“差点意思”2.1 信息层级先于视觉美化很多人画图的第一步是打开工具、选模板、拖图形。diagram-design 的思路恰恰相反先别碰工具先拿纸笔或者纯文本把信息层级理清楚。什么叫信息层级就是这张图里哪些是核心实体哪些是辅助说明哪些是边界条件哪些是可选路径。我习惯用一个很笨但很有效的方法把图里要出现的东西全部写成一句话列表然后逐条问自己——“如果删掉它图还成立吗”如果答案是“成立”那它就不该出现在主图里最多放进注释或附录。这个原则背后的逻辑是人眼在阅读图表时注意力资源极其有限。认知心理学里有个粗略的估计人在一次扫视中能稳定处理的视觉元素大约在 7 到 12 个之间。超过这个数量大脑就会自动降级处理变成“大概扫一眼”的模式。所以一张架构图里如果有 30 个节点不管画得多漂亮读者大概率只会记住其中三五个。diagram-design 的做法是把主图控制在 9 个节点以内超出部分用“分组框”或“子图引用”的方式折叠起来。这不是偷懒这是对读者注意力的尊重。具体操作上我通常会把信息分成三层第一层是“必须一眼看到”的核心实体比如用户、网关、核心服务、主数据库第二层是“需要时能找到”的支撑组件比如缓存、消息队列、监控代理第三层是“只在特定场景下关心”的细节比如某个服务的内部模块划分。主图只画第一层第二层用浅色或虚线框表示第三层直接省略用文字说明代替。这样出来的图信息密度适中读者不会迷路。注意不要为了“看起来完整”而把所有东西都塞进一张图。图的完整性和可读性往往是矛盾的diagram-design 的选择是优先保证可读性。2.2 视觉语法的一致性比创意更重要第二原则是视觉语法的一致性。什么叫视觉语法就是同样的形状、颜色、线型在整张图甚至整个项目里始终代表同样的含义。比如圆角矩形永远代表“服务”直角矩形永远代表“外部系统”圆柱体永远代表“存储”虚线箭头永远代表“异步消息”实线箭头永远代表“同步调用”。这套规则一旦定下来就不要轻易打破。我见过一个反面案例某项目的架构图里作者用蓝色表示“前端”用绿色表示“后端”结果在另一张图里蓝色又变成了“数据库”绿色变成了“缓存”。读者如果连续看这两张图认知负担会急剧上升。diagram-design 强调颜色和形状不是装饰它们是语义符号。符号的意义必须稳定否则图就失去了作为“通用语言”的价值。那怎么定这套语法我的经验是从项目最核心的三到五个概念出发。比如一个典型的 Web 服务项目核心概念可能是用户、网关、业务服务、数据存储、外部依赖。那就给这五类各分配一个固定的形状和颜色。用户用圆形或人形图标网关用六边形或粗边框矩形业务服务用圆角矩形数据存储用圆柱体外部依赖用虚线框加直角矩形。颜色上主流程用同一色系的不同深浅辅助组件用灰色系警告或异常路径用橙色或红色。这套规则写进项目 Wiki新来的同学画图前先看一遍能省掉大量返工。2.3 连线是图的灵魂不是附属品第三个原则也是最多人忽略的连线本身携带的信息量往往比节点还大。一条箭头从 A 指向 B它至少隐含了四层信息方向谁调用谁、类型同步还是异步、协议HTTP、gRPC、消息队列、以及条件是否经过认证、是否加密。很多图只画一条光秃秃的线读者只能靠猜。diagram-design 的做法是把连线当作“一等公民”来设计。具体来说我会在连线旁边标注关键信息但不会写成长句。比如“HTTP/JSON”比“通过 HTTP 协议传输 JSON 格式数据”更合适“async”比“异步消息”更简洁。如果连线类型多就用线型区分实线代表同步请求虚线代表异步消息点线代表定时任务带空心三角的箭头代表继承或实现关系。颜色上主流程用深色异常流程用红色可选流程用灰色。这样读者扫一眼连线就能大致判断系统的交互模式。还有一个细节尽量避免连线交叉。如果两张图里连线交叉严重说明信息层级没理清或者节点布局需要调整。我通常会用“分层布局”来减少交叉把调用方放在上层被调用方放在下层数据存储放在最下层外部依赖放在两侧。这样连线自然从上往下走交叉概率大大降低。如果实在避不开就用“跳线”符号一条小弧线跨过另一条线但跳线数量不要超过三条否则图会显得很乱。3. 工具选型从纯文本到可视化怎么选不踩坑3.1 文本驱动工具适合版本管理和协作diagram-design 在工具选型上的核心建议是优先考虑文本驱动或代码驱动的方案。为什么因为图一旦变成二进制文件版本管理就废了。你没法用 Git diff 看出一张 PNG 图改了什么也没法在代码评审里逐行讨论图的变更。文本驱动工具把图定义成纯文本比如 Mermaid、PlantUML、Graphviz、D2 等这样图就和代码一样可以 diff、可以 review、可以回滚。我自己的项目里架构图和时序图基本都用文本驱动工具来画。好处很明显改一个节点名字只需要改一行文本调整布局改几个参数就行多人协作时合并冲突虽然有点烦但至少能看懂冲突在哪。坏处也有复杂布局的控制力不如可视化工具尤其是需要精确对齐、自定义图标、复杂嵌套的场景文本工具会显得力不从心。所以我的策略是“主图文本化配图可视化”——核心架构图、流程图、时序图用文本工具宣传图、概念示意图、需要精细排版的图用可视化工具。提示如果你团队里有人不习惯写代码可以先用文本工具生成初稿再导入可视化工具微调。这样既保留了版本管理的优势又兼顾了视觉调整的灵活性。3.2 可视化工具什么时候该用什么时候该躲可视化工具比如 Figma、Excalidraw、draw.io、Whimsical 等优势在于所见即所得拖拽方便适合快速探索和精细排版。但它们的坑也很明显第一文件格式不透明版本管理困难第二容易陷入“美化陷阱”花大量时间调颜色、调间距却忽略了信息结构第三协作时容易出现“各自为政”每个人用自己的风格最后拼在一起像缝合怪。diagram-design 的建议是可视化工具只用在两个场景一是早期探索阶段需要快速试错看看哪种布局更合理二是最终输出阶段需要精细调整视觉细节比如对齐、间距、字体、颜色。中间的信息结构设计和语义定义尽量在文本层面完成。这样既能享受可视化的便利又不会被工具绑架。我个人的工作流是这样的先用纯文本列出节点和连线确定信息层级然后用文本驱动工具生成初稿检查逻辑是否通顺最后如果需要对外发布再导入可视化工具做视觉微调。整个过程里文本始终是“唯一真相源”可视化工具只是渲染器。这样即使换了工具图的核心内容也不会丢。3.3 工具选型对照表工具类型代表工具适合场景不适合场景版本管理友好度文本驱动Mermaid、PlantUML、D2架构图、时序图、流程图精细排版、复杂图标高可视化Figma、Excalidraw、draw.io概念图、宣传图、快速探索频繁变更、多人协作低混合文本生成 可视化微调对外发布、精细调整快速迭代中这张表不是绝对的但可以作为选型的起点。核心判断标准是这张图会不会频繁变更会不会多人协作如果答案是“会”优先文本驱动如果答案是“不会但需要好看”可视化工具更合适。4. 实操全流程从零画出一张“能打”的架构图4.1 第一步信息收集与层级划分假设我们要画一个“短链接服务”的架构图。这个服务的基本功能是接收长链接生成短码存储映射关系用户访问短码时重定向到长链接。听起来简单但涉及的东西不少API 网关、生成服务、存储、缓存、重定向服务、统计模块、限流组件。第一步不是画图而是列清单。我会把所有可能出现的组件写下来然后按重要性分层核心层API 网关、生成服务、重定向服务、主数据库支撑层缓存、消息队列、限流组件辅助层统计模块、监控代理、日志收集核心层必须出现在主图里支撑层用浅色或虚线框表示辅助层直接省略用文字说明。这样主图节点控制在 7 个左右读者一眼能看完。注意分层不是固定的要根据读者是谁来调整。如果读者是运维同学监控和日志可能就要提到支撑层甚至核心层如果读者是产品经理统计模块可能更重要。diagram-design 强调“以读者为中心”而不是“以系统为中心”。4.2 第二步定义视觉语法接下来定义这套图的视觉语法。我习惯用以下规则圆角矩形业务服务生成服务、重定向服务直角矩形外部系统或网关API 网关圆柱体数据存储主数据库、缓存虚线框支撑组件消息队列、限流组件实线箭头同步调用虚线箭头异步消息点线箭头定时任务或批量操作颜色上核心层用深蓝色系支撑层用浅灰色系异常路径用橙色。字体统一用无衬线字体字号不小于 12px节点内文字不超过两行。这套语法定下来后整张图的风格就统一了。即使后面加新节点只要按规则来就不会显得突兀。4.3 第三步布局与连线布局是画图里最考验经验的部分。我的原则是“从上到下从左到右主流程居中辅助流程靠边”。具体到短链接服务最上层用户圆形图标第二层API 网关直角矩形第三层生成服务、重定向服务圆角矩形左右并排第四层缓存、主数据库圆柱体左右并排第五层消息队列、限流组件虚线框放在两侧连线方面用户到网关用实线箭头标注“HTTPS”网关到生成服务用实线箭头标注“POST /shorten”网关到重定向服务用实线箭头标注“GET /{code}”生成服务到缓存和数据库用实线箭头标注“写入”重定向服务到缓存用实线箭头标注“读取”到数据库用虚线箭头标注“回源”生成服务到消息队列用虚线箭头标注“异步统计”。这样画出来主流程清晰辅助流程不抢眼读者顺着箭头走一遍就能理解系统的基本交互。4.4 第四步评审与迭代图画出初稿后不要急着发布。diagram-design 强调“图是改出来的不是画出来的”。我会把初稿发给两到三个不同角色的同事看一个开发、一个产品、一个运维。问他们三个问题第一你能在三秒内说出这个系统是干什么的吗第二有没有哪条连线你看不懂第三如果让你删掉一个节点你会删哪个根据反馈迭代。通常第一轮会暴露出一些问题比如某个节点位置太偏容易被忽略某条连线标注太模糊产生歧义某个支撑组件其实没必要出现。改完第二轮图基本就稳了。提示评审时尽量用“陌生人视角”。如果找一个完全不了解这个项目的人来看他能看懂说明图合格了如果他看不懂说明信息层级或视觉语法还有问题。5. 常见问题与排查技巧实录5.1 图太复杂读者看不懂怎么办这是最常见的问题。解决方案不是“简化图”而是“拆分图”。一张图只讲一件事。如果系统有多个交互场景就画多张图一张讲核心请求流程一张讲异步统计流程一张讲限流降级流程。每张图都遵循同样的视觉语法读者看第一张时学习规则看后面几张时就能快速理解。另一个技巧是“渐进式披露”。主图只画核心层然后用一个“展开”符号或注释指向一张更详细的子图。这样读者可以先看全局再按需深入。很多工具支持“子图引用”或“折叠分组”用起来很方便。5.2 连线交叉严重怎么调整布局连线交叉通常是因为节点布局不合理。我的排查顺序是第一检查是否把调用方和被调用方放在了同一层如果是改成上下层第二检查是否有节点可以合并或省略减少节点数量第三检查是否可以用“分组框”把相关节点包在一起减少跨组连线第四如果还是交叉考虑换布局方向比如从左到右改成从上到下。如果实在避不开就用“跳线”符号但跳线数量控制在三条以内。超过三条说明图的结构需要重新设计而不是靠跳线来救。5.3 团队风格不统一怎么推行规范推行 diagram-design 规范最有效的方式不是写文档而是“做样板”。先自己按规范画两三张图在团队里传阅让大家看到效果。然后组织一次简短的分享讲清楚三条核心规则信息分层、视觉语法一致、连线标注清晰。最后把规范写进项目 Wiki新图评审时按规范检查。不要试图一次推行所有规则。先推最核心的三条等大家习惯了再补充细节。我见过一些团队规范写了二十页结果没人看。diagram-design 的思路是“最小可行规范”先跑起来再迭代。5.4 常见问题速查表问题现象可能原因排查思路解决技巧读者看不懂图信息层级不清问陌生人能否三秒说出图的主旨拆分图主图只留核心层连线交叉严重节点布局不合理检查调用方是否同层改上下层布局合并节点风格不统一缺少视觉语法检查形状颜色是否语义一致定三到五条核心规则做样板图太复杂节点过多数主图节点是否超过 9 个折叠支撑层省略辅助层连线歧义标注不清晰问读者能否说出连线含义用线型区分同步异步标注协议6. 进阶技巧让图从“合格”到“出彩”6.1 用“视觉权重”引导阅读顺序视觉权重是指图中不同元素的“抢眼程度”。diagram-design 的高级技巧之一就是通过调整视觉权重引导读者的阅读顺序。具体手段包括大小核心节点稍大、颜色核心层用深色辅助层用浅色、位置主流程居中辅助流程靠边、边框核心节点用粗边框辅助节点用细边框或无边框。我通常会把最重要的节点放大 10% 到 20%颜色加深一档放在视觉中心。这样读者第一眼就会看到它然后顺着连线往下看。辅助节点则缩小、变浅、靠边起到“背景信息”的作用。这样整张图有主有次读起来不累。6.2 用“注释层”承载细节主图容量有限但细节不能丢。diagram-design 的做法是加一个“注释层”。注释层可以是图下方的文字说明也可以是图旁边的编号列表。主图里每个节点或连线旁边标一个数字注释层里对应解释。这样主图保持简洁细节又能查到。注释层的写法也有讲究。不要写成长篇大论每条注释控制在一两句话。比如“生成服务负责将长链接转换为短码使用 Base62 编码冲突时重试三次”。这样读者需要时能查到不需要时也不会被干扰。6.3 用“对比图”展示演进过程如果项目有版本演进或者有多种方案对比diagram-design 建议用“对比图”来展示。比如左边画旧架构右边画新架构中间用箭头连接标注“重构”。或者上下排列上面是方案 A下面是方案 B用同样的视觉语法方便读者对比差异。对比图的关键是“控制变量”除了要对比的部分其他部分尽量保持一致。比如节点位置、颜色、连线风格都相同只有被对比的组件不同。这样读者的注意力会自然集中在差异上而不是被无关细节干扰。6.4 用“图例”降低认知门槛如果图里用了多种形状、颜色、线型一定要加图例。图例放在图的角落不要太大但要清晰。图例的作用是“一次性教会读者规则”之后读者就能自主解读图里的符号。没有图例的图读者需要边看边猜认知负担会大很多。图例的写法每个符号配一个简短说明比如“圆角矩形 业务服务”“虚线箭头 异步消息”。不要写“圆角矩形代表业务服务业务服务是指……”图例要简洁详细解释放在注释层或正文里。7. 我踩过的坑与实操心得第一个坑是“过度设计”。早期我画图时总想把每个细节都画出来结果图越画越大最后连自己都看不懂。后来我强迫自己遵守“主图不超过 9 个节点”的规则情况才好转。现在我的习惯是先画一张“极简版”只保留最核心的五个节点然后根据读者反馈决定是否加细节。大多数情况下极简版就够用了。第二个坑是“工具依赖”。有段时间我迷上了某款可视化工具所有图都用它画。结果项目迁移时图导不出来只能重画。从那以后我坚持“文本优先”核心图都用文本驱动工具定义可视化工具只做最终渲染。这样即使换工具图的内容也不会丢。第三个坑是“忽略读者”。我曾经画过一张自认为很漂亮的架构图结果评审时有人问“这个箭头是什么意思”我才发现忘了标注。diagram-design 的核心是“以读者为中心”不是“以画图者为中心”。每次画完图我都会找一个不了解项目的人来看问他三个问题这是什么系统主流程是什么有没有看不懂的地方这三个问题能帮我发现大部分问题。最后一个心得是图不是越漂亮越好而是越“省脑”越好。读者看图的目的是快速理解信息不是欣赏艺术。所以克制使用颜色克制使用图标克制使用特效。把精力放在信息层级、视觉语法、连线标注上这些才是图的“骨架”。骨架立住了图就稳了。提示如果你只能记住一件事记住这个——画图之前先列清单画完之后找陌生人看。这两步能解决 80% 的问题。 
长河君 · 2026/10/15 7:34:57 · 阅读 1.2k diagram-design：从草图到系统，图表设计方法论与工具链实践
1. 从一张草图到一套系统diagram-design 到底在解决什么问题第一次听到 “diagram-design” 这个词很多人会以为它只是“画图工具”的另一个说法。但真正在项目里摸爬滚打过的人都知道图这件事从来不是“画出来”那么简单。它背后牵扯的是信息结构、视觉语法、协作流程、版本管理以及最终能不能让看图的人在三秒内抓住重点。我见过太多团队技术方案写得扎实一到画架构图就变成“方框加箭头谁看谁懵”也见过不少独立开发者功能做得漂亮README 里的流程图却让人直接关掉页面。diagram-design 要解决的正是这个从“能看”到“好懂”之间的鸿沟。简单说diagram-design 是一套围绕“图表设计”展开的方法论加工具链实践。它不局限于某一种图形语言而是把流程图、架构图、时序图、状态图、思维导图、甚至简单的数据关系图都纳入同一个设计思维框架里。它的核心主张是图不是文档的装饰图是信息的压缩包。一张好的图应该像一段精心重构的代码——没有冗余分支没有歧义路径每个节点都有存在的理由每条连线都承载明确语义。这套东西适合谁如果你是需要频繁输出技术方案、系统设计、流程说明的工程师它帮你把“画图”从体力活变成设计活如果你是产品经理或项目协调人它让你用图对齐认知减少会议里的“我以为”如果你是写博客、做教程的内容创作者它让你的示意图不再是从模板库里随便拖出来的“通用素材”而是有辨识度、有逻辑层次的信息载体。哪怕你只是偶尔需要画一张图来说明问题理解 diagram-design 的思路也能让你少走很多弯路。我最初接触这个方向是因为一个内部工具的重构项目。当时团队有五个人每个人画的架构图风格都不一样有人用圆角矩形有人用直角有人把数据库画成圆柱有人画成方块箭头方向更是随心所欲。结果就是每次评审会前十分钟都在争论“这个箭头到底代表数据流还是控制流”。后来我们花了两周时间把 diagram-design 的基本原则落地成一套内部规范配合几个轻量工具情况才彻底改观。这篇文章就是把这套从踩坑里长出来的经验完整拆给你看。2. 核心设计原则为什么你的图总是“差点意思”2.1 信息层级先于视觉美化很多人画图的第一步是打开工具、选模板、拖图形。diagram-design 的思路恰恰相反先别碰工具先拿纸笔或者纯文本把信息层级理清楚。什么叫信息层级就是这张图里哪些是核心实体哪些是辅助说明哪些是边界条件哪些是可选路径。我习惯用一个很笨但很有效的方法把图里要出现的东西全部写成一句话列表然后逐条问自己——“如果删掉它图还成立吗”如果答案是“成立”那它就不该出现在主图里最多放进注释或附录。这个原则背后的逻辑是人眼在阅读图表时注意力资源极其有限。认知心理学里有个粗略的估计人在一次扫视中能稳定处理的视觉元素大约在 7 到 12 个之间。超过这个数量大脑就会自动降级处理变成“大概扫一眼”的模式。所以一张架构图里如果有 30 个节点不管画得多漂亮读者大概率只会记住其中三五个。diagram-design 的做法是把主图控制在 9 个节点以内超出部分用“分组框”或“子图引用”的方式折叠起来。这不是偷懒这是对读者注意力的尊重。具体操作上我通常会把信息分成三层第一层是“必须一眼看到”的核心实体比如用户、网关、核心服务、主数据库第二层是“需要时能找到”的支撑组件比如缓存、消息队列、监控代理第三层是“只在特定场景下关心”的细节比如某个服务的内部模块划分。主图只画第一层第二层用浅色或虚线框表示第三层直接省略用文字说明代替。这样出来的图信息密度适中读者不会迷路。注意不要为了“看起来完整”而把所有东西都塞进一张图。图的完整性和可读性往往是矛盾的diagram-design 的选择是优先保证可读性。2.2 视觉语法的一致性比创意更重要第二原则是视觉语法的一致性。什么叫视觉语法就是同样的形状、颜色、线型在整张图甚至整个项目里始终代表同样的含义。比如圆角矩形永远代表“服务”直角矩形永远代表“外部系统”圆柱体永远代表“存储”虚线箭头永远代表“异步消息”实线箭头永远代表“同步调用”。这套规则一旦定下来就不要轻易打破。我见过一个反面案例某项目的架构图里作者用蓝色表示“前端”用绿色表示“后端”结果在另一张图里蓝色又变成了“数据库”绿色变成了“缓存”。读者如果连续看这两张图认知负担会急剧上升。diagram-design 强调颜色和形状不是装饰它们是语义符号。符号的意义必须稳定否则图就失去了作为“通用语言”的价值。那怎么定这套语法我的经验是从项目最核心的三到五个概念出发。比如一个典型的 Web 服务项目核心概念可能是用户、网关、业务服务、数据存储、外部依赖。那就给这五类各分配一个固定的形状和颜色。用户用圆形或人形图标网关用六边形或粗边框矩形业务服务用圆角矩形数据存储用圆柱体外部依赖用虚线框加直角矩形。颜色上主流程用同一色系的不同深浅辅助组件用灰色系警告或异常路径用橙色或红色。这套规则写进项目 Wiki新来的同学画图前先看一遍能省掉大量返工。2.3 连线是图的灵魂不是附属品第三个原则也是最多人忽略的连线本身携带的信息量往往比节点还大。一条箭头从 A 指向 B它至少隐含了四层信息方向谁调用谁、类型同步还是异步、协议HTTP、gRPC、消息队列、以及条件是否经过认证、是否加密。很多图只画一条光秃秃的线读者只能靠猜。diagram-design 的做法是把连线当作“一等公民”来设计。具体来说我会在连线旁边标注关键信息但不会写成长句。比如“HTTP/JSON”比“通过 HTTP 协议传输 JSON 格式数据”更合适“async”比“异步消息”更简洁。如果连线类型多就用线型区分实线代表同步请求虚线代表异步消息点线代表定时任务带空心三角的箭头代表继承或实现关系。颜色上主流程用深色异常流程用红色可选流程用灰色。这样读者扫一眼连线就能大致判断系统的交互模式。还有一个细节尽量避免连线交叉。如果两张图里连线交叉严重说明信息层级没理清或者节点布局需要调整。我通常会用“分层布局”来减少交叉把调用方放在上层被调用方放在下层数据存储放在最下层外部依赖放在两侧。这样连线自然从上往下走交叉概率大大降低。如果实在避不开就用“跳线”符号一条小弧线跨过另一条线但跳线数量不要超过三条否则图会显得很乱。3. 工具选型从纯文本到可视化怎么选不踩坑3.1 文本驱动工具适合版本管理和协作diagram-design 在工具选型上的核心建议是优先考虑文本驱动或代码驱动的方案。为什么因为图一旦变成二进制文件版本管理就废了。你没法用 Git diff 看出一张 PNG 图改了什么也没法在代码评审里逐行讨论图的变更。文本驱动工具把图定义成纯文本比如 Mermaid、PlantUML、Graphviz、D2 等这样图就和代码一样可以 diff、可以 review、可以回滚。我自己的项目里架构图和时序图基本都用文本驱动工具来画。好处很明显改一个节点名字只需要改一行文本调整布局改几个参数就行多人协作时合并冲突虽然有点烦但至少能看懂冲突在哪。坏处也有复杂布局的控制力不如可视化工具尤其是需要精确对齐、自定义图标、复杂嵌套的场景文本工具会显得力不从心。所以我的策略是“主图文本化配图可视化”——核心架构图、流程图、时序图用文本工具宣传图、概念示意图、需要精细排版的图用可视化工具。提示如果你团队里有人不习惯写代码可以先用文本工具生成初稿再导入可视化工具微调。这样既保留了版本管理的优势又兼顾了视觉调整的灵活性。3.2 可视化工具什么时候该用什么时候该躲可视化工具比如 Figma、Excalidraw、draw.io、Whimsical 等优势在于所见即所得拖拽方便适合快速探索和精细排版。但它们的坑也很明显第一文件格式不透明版本管理困难第二容易陷入“美化陷阱”花大量时间调颜色、调间距却忽略了信息结构第三协作时容易出现“各自为政”每个人用自己的风格最后拼在一起像缝合怪。diagram-design 的建议是可视化工具只用在两个场景一是早期探索阶段需要快速试错看看哪种布局更合理二是最终输出阶段需要精细调整视觉细节比如对齐、间距、字体、颜色。中间的信息结构设计和语义定义尽量在文本层面完成。这样既能享受可视化的便利又不会被工具绑架。我个人的工作流是这样的先用纯文本列出节点和连线确定信息层级然后用文本驱动工具生成初稿检查逻辑是否通顺最后如果需要对外发布再导入可视化工具做视觉微调。整个过程里文本始终是“唯一真相源”可视化工具只是渲染器。这样即使换了工具图的核心内容也不会丢。3.3 工具选型对照表工具类型代表工具适合场景不适合场景版本管理友好度文本驱动Mermaid、PlantUML、D2架构图、时序图、流程图精细排版、复杂图标高可视化Figma、Excalidraw、draw.io概念图、宣传图、快速探索频繁变更、多人协作低混合文本生成 可视化微调对外发布、精细调整快速迭代中这张表不是绝对的但可以作为选型的起点。核心判断标准是这张图会不会频繁变更会不会多人协作如果答案是“会”优先文本驱动如果答案是“不会但需要好看”可视化工具更合适。4. 实操全流程从零画出一张“能打”的架构图4.1 第一步信息收集与层级划分假设我们要画一个“短链接服务”的架构图。这个服务的基本功能是接收长链接生成短码存储映射关系用户访问短码时重定向到长链接。听起来简单但涉及的东西不少API 网关、生成服务、存储、缓存、重定向服务、统计模块、限流组件。第一步不是画图而是列清单。我会把所有可能出现的组件写下来然后按重要性分层核心层API 网关、生成服务、重定向服务、主数据库支撑层缓存、消息队列、限流组件辅助层统计模块、监控代理、日志收集核心层必须出现在主图里支撑层用浅色或虚线框表示辅助层直接省略用文字说明。这样主图节点控制在 7 个左右读者一眼能看完。注意分层不是固定的要根据读者是谁来调整。如果读者是运维同学监控和日志可能就要提到支撑层甚至核心层如果读者是产品经理统计模块可能更重要。diagram-design 强调“以读者为中心”而不是“以系统为中心”。4.2 第二步定义视觉语法接下来定义这套图的视觉语法。我习惯用以下规则圆角矩形业务服务生成服务、重定向服务直角矩形外部系统或网关API 网关圆柱体数据存储主数据库、缓存虚线框支撑组件消息队列、限流组件实线箭头同步调用虚线箭头异步消息点线箭头定时任务或批量操作颜色上核心层用深蓝色系支撑层用浅灰色系异常路径用橙色。字体统一用无衬线字体字号不小于 12px节点内文字不超过两行。这套语法定下来后整张图的风格就统一了。即使后面加新节点只要按规则来就不会显得突兀。4.3 第三步布局与连线布局是画图里最考验经验的部分。我的原则是“从上到下从左到右主流程居中辅助流程靠边”。具体到短链接服务最上层用户圆形图标第二层API 网关直角矩形第三层生成服务、重定向服务圆角矩形左右并排第四层缓存、主数据库圆柱体左右并排第五层消息队列、限流组件虚线框放在两侧连线方面用户到网关用实线箭头标注“HTTPS”网关到生成服务用实线箭头标注“POST /shorten”网关到重定向服务用实线箭头标注“GET /{code}”生成服务到缓存和数据库用实线箭头标注“写入”重定向服务到缓存用实线箭头标注“读取”到数据库用虚线箭头标注“回源”生成服务到消息队列用虚线箭头标注“异步统计”。这样画出来主流程清晰辅助流程不抢眼读者顺着箭头走一遍就能理解系统的基本交互。4.4 第四步评审与迭代图画出初稿后不要急着发布。diagram-design 强调“图是改出来的不是画出来的”。我会把初稿发给两到三个不同角色的同事看一个开发、一个产品、一个运维。问他们三个问题第一你能在三秒内说出这个系统是干什么的吗第二有没有哪条连线你看不懂第三如果让你删掉一个节点你会删哪个根据反馈迭代。通常第一轮会暴露出一些问题比如某个节点位置太偏容易被忽略某条连线标注太模糊产生歧义某个支撑组件其实没必要出现。改完第二轮图基本就稳了。提示评审时尽量用“陌生人视角”。如果找一个完全不了解这个项目的人来看他能看懂说明图合格了如果他看不懂说明信息层级或视觉语法还有问题。5. 常见问题与排查技巧实录5.1 图太复杂读者看不懂怎么办这是最常见的问题。解决方案不是“简化图”而是“拆分图”。一张图只讲一件事。如果系统有多个交互场景就画多张图一张讲核心请求流程一张讲异步统计流程一张讲限流降级流程。每张图都遵循同样的视觉语法读者看第一张时学习规则看后面几张时就能快速理解。另一个技巧是“渐进式披露”。主图只画核心层然后用一个“展开”符号或注释指向一张更详细的子图。这样读者可以先看全局再按需深入。很多工具支持“子图引用”或“折叠分组”用起来很方便。5.2 连线交叉严重怎么调整布局连线交叉通常是因为节点布局不合理。我的排查顺序是第一检查是否把调用方和被调用方放在了同一层如果是改成上下层第二检查是否有节点可以合并或省略减少节点数量第三检查是否可以用“分组框”把相关节点包在一起减少跨组连线第四如果还是交叉考虑换布局方向比如从左到右改成从上到下。如果实在避不开就用“跳线”符号但跳线数量控制在三条以内。超过三条说明图的结构需要重新设计而不是靠跳线来救。5.3 团队风格不统一怎么推行规范推行 diagram-design 规范最有效的方式不是写文档而是“做样板”。先自己按规范画两三张图在团队里传阅让大家看到效果。然后组织一次简短的分享讲清楚三条核心规则信息分层、视觉语法一致、连线标注清晰。最后把规范写进项目 Wiki新图评审时按规范检查。不要试图一次推行所有规则。先推最核心的三条等大家习惯了再补充细节。我见过一些团队规范写了二十页结果没人看。diagram-design 的思路是“最小可行规范”先跑起来再迭代。5.4 常见问题速查表问题现象可能原因排查思路解决技巧读者看不懂图信息层级不清问陌生人能否三秒说出图的主旨拆分图主图只留核心层连线交叉严重节点布局不合理检查调用方是否同层改上下层布局合并节点风格不统一缺少视觉语法检查形状颜色是否语义一致定三到五条核心规则做样板图太复杂节点过多数主图节点是否超过 9 个折叠支撑层省略辅助层连线歧义标注不清晰问读者能否说出连线含义用线型区分同步异步标注协议6. 进阶技巧让图从“合格”到“出彩”6.1 用“视觉权重”引导阅读顺序视觉权重是指图中不同元素的“抢眼程度”。diagram-design 的高级技巧之一就是通过调整视觉权重引导读者的阅读顺序。具体手段包括大小核心节点稍大、颜色核心层用深色辅助层用浅色、位置主流程居中辅助流程靠边、边框核心节点用粗边框辅助节点用细边框或无边框。我通常会把最重要的节点放大 10% 到 20%颜色加深一档放在视觉中心。这样读者第一眼就会看到它然后顺着连线往下看。辅助节点则缩小、变浅、靠边起到“背景信息”的作用。这样整张图有主有次读起来不累。6.2 用“注释层”承载细节主图容量有限但细节不能丢。diagram-design 的做法是加一个“注释层”。注释层可以是图下方的文字说明也可以是图旁边的编号列表。主图里每个节点或连线旁边标一个数字注释层里对应解释。这样主图保持简洁细节又能查到。注释层的写法也有讲究。不要写成长篇大论每条注释控制在一两句话。比如“生成服务负责将长链接转换为短码使用 Base62 编码冲突时重试三次”。这样读者需要时能查到不需要时也不会被干扰。6.3 用“对比图”展示演进过程如果项目有版本演进或者有多种方案对比diagram-design 建议用“对比图”来展示。比如左边画旧架构右边画新架构中间用箭头连接标注“重构”。或者上下排列上面是方案 A下面是方案 B用同样的视觉语法方便读者对比差异。对比图的关键是“控制变量”除了要对比的部分其他部分尽量保持一致。比如节点位置、颜色、连线风格都相同只有被对比的组件不同。这样读者的注意力会自然集中在差异上而不是被无关细节干扰。6.4 用“图例”降低认知门槛如果图里用了多种形状、颜色、线型一定要加图例。图例放在图的角落不要太大但要清晰。图例的作用是“一次性教会读者规则”之后读者就能自主解读图里的符号。没有图例的图读者需要边看边猜认知负担会大很多。图例的写法每个符号配一个简短说明比如“圆角矩形 业务服务”“虚线箭头 异步消息”。不要写“圆角矩形代表业务服务业务服务是指……”图例要简洁详细解释放在注释层或正文里。7. 我踩过的坑与实操心得第一个坑是“过度设计”。早期我画图时总想把每个细节都画出来结果图越画越大最后连自己都看不懂。后来我强迫自己遵守“主图不超过 9 个节点”的规则情况才好转。现在我的习惯是先画一张“极简版”只保留最核心的五个节点然后根据读者反馈决定是否加细节。大多数情况下极简版就够用了。第二个坑是“工具依赖”。有段时间我迷上了某款可视化工具所有图都用它画。结果项目迁移时图导不出来只能重画。从那以后我坚持“文本优先”核心图都用文本驱动工具定义可视化工具只做最终渲染。这样即使换工具图的内容也不会丢。第三个坑是“忽略读者”。我曾经画过一张自认为很漂亮的架构图结果评审时有人问“这个箭头是什么意思”我才发现忘了标注。diagram-design 的核心是“以读者为中心”不是“以画图者为中心”。每次画完图我都会找一个不了解项目的人来看问他三个问题这是什么系统主流程是什么有没有看不懂的地方这三个问题能帮我发现大部分问题。最后一个心得是图不是越漂亮越好而是越“省脑”越好。读者看图的目的是快速理解信息不是欣赏艺术。所以克制使用颜色克制使用图标克制使用特效。把精力放在信息层级、视觉语法、连线标注上这些才是图的“骨架”。骨架立住了图就稳了。提示如果你只能记住一件事记住这个——画图之前先列清单画完之后找陌生人看。这两步能解决 80% 的问题。