你有没有在评审会上被一张乱糟糟的架构图带偏过节点五花八门箭头横七竖八颜色全凭心情最后所有人都在猜图例而不是聊方案。我最早接触 diagram-design 这个概念就是因为一次这样的评审会给我上了一课。后来我干脆把画图当成一个正经项目来做从工具选型、配色规范到组件库沉淀一步步整理出一套可复用的设计方法。这篇文章会把这套方法的完整思路、实操流程和踩过的坑一次性讲清楚。它适合经常画系统架构图、流程图、时序图的人也适合团队里需要统一图表风格的文档负责人。没有太高门槛只要你有过“这张图到底怎么画才清楚”的纠结就能用上。技术文档里的图天然承担着沟通架构决策的重任。一张表达混乱的图轻则让评审会上争论半小时重则让新同学理解错系统边界埋下设计隐患。与其每次都靠临时发挥不如把画图本身也当成一个需要设计、规范、评审的工程。这就是 diagram-design 这套方法诞生的原因。1. 项目缘起给“画图”建立一套可以复用的秩序1.1 一次评审会让“能看懂”变得不够用那次评审会我印象很深。新同事画了一张架构图看得出非常用功每个框都有渐变阴影配色至少用了八种信息也很完整。但所有人都看得很吃力。有人问蓝色框和绿色框的区别有人问虚线箭头和实线箭头分别代表什么还有人拿着放大镜找图例。原本计划二十分钟结束的技术评审最后变成了“看图猜意思”大赛真正应该讨论的接口设计问题根本没展开。这件事让我明白一个道理图的本质是信息压缩。作者在脑子里完成了一次复杂的抽象然后把结果画在图上。但如果读者没有拿到作者的解码规则压缩得越狠误解就越大。尤其是架构图作者脑海里装着完整的上下文画的时候觉得自己表达得很清楚可读者是第一次看到这张图他们没有作者的背景知识必须依靠图里的视觉线索来重建理解。一旦视觉线索内部矛盾误解就不可避免。从那之后我开始琢磨能不能像对待代码规范一样对待图代码有命名规范、目录规范、提交规范图为什么不能有节点规范、配色规范、连线规范这个念头就是 diagram-design 这个项目最初的起点。1.2 diagram-design 拆解出来到底是什么diagram-design 听起来像是个设计岗位其实是一套方法论。在我看来它至少包含四层内容内容建模这张图到底要表达什么哪些信息是核心哪些是干扰项。先做信息减法再做视觉加法而不是把头脑里所有东西都堆上去。结构分层图里的节点按什么逻辑分组层与层之间是调用关系、依赖关系还是数据流动关系没有分层的图就是一张大杂烩。视觉编码用形状、颜色、线型、文字来编码信息让读者依靠直觉就能解析而不是反复查看图例。组件复用把常用节点、连接线、角标、图例沉淀成可复用组件避免每张图从零开始拼凑也能保证团队图的风格统一。用写代码来类比就很好懂内容建模相当于需求分析结构分层相当于架构设计视觉编码相当于代码书写时的命名与格式化组件复用相当于抽公共库和设计模式。画图从来不是美术创作它和写代码一样需要规范、需要评审、需要重构。1.3 我给自己定的三个落地目标空谈方法论没有意义我在项目启动时给自己定了三条硬指标后来也成了我衡量每一张图的标尺第一一张图拿到手里不需要任何口头解释五秒钟内能看出主流程是从哪到哪。第二同一个项目内所有图风格统一组件复用率达到百分之八十以上不能出现这一张圆角矩形、下一张直角矩形的割裂感。第三一个不熟悉这套规范的新同事照着模板能在二十分钟内产出一张能用的图而不是坐在电脑前对着空白画布发呆。每次画完图我都会问自己三个问题读者第一眼看到哪里第二眼看到哪里这张图需要口头解释吗如果回答不清晰说明这张图还没有达标得返工。2. 工具选型解析代码驱动还是鼠标驱动别急着站队2.1 代码驱动型工具的取舍diagram-design 这套体系里工具只是载体真正重要的是思维。但选不对工具再好的思维也会被拖垮。代码驱动型工具里我实际用过并且比较有发言权的有三个Mermaid、PlantUML 和 Graphviz。很多人在这三者之间反复横跳其实它们性格差异很明显。维度MermaidPlantUMLGraphviz学习成本较低语法接近自然语言中等需要记不少关键词较高涉及布局算法概念上手速度快适合在 Markdown 里顺手写中等慢适合专业复杂图输出类型流程图、时序图、状态图、类图等时序图、用例图、活动图、部署图等有向/无向图、树图、依赖关系图排版美观度够用默认样式偏朴素偏工程风布局控制力强但定制曲线陡典型场景技术文档、Markdown 博客、README软件工程设计图、架构文档组件依赖、关系网络、大规模节点我的建议很直白如果只在写文档的时候顺带画一张图优先考虑 Mermaid如果经常画时序图、部署图PlantUML 更顺如果要处理几百个上千个节点的依赖关系Graphviz 才是正解硬用 Mermaid 会把浏览器卡到怀疑人生。有人可能会问这三个都是文本工具为什么不直接用绘图软件我的理由是文本文件可以进代码仓库做版本管理。今天定义的调用关系三个月后有人改了某个接口我直接 diff 出图的变更这是任何可视化工具都给不了的追溯能力。2.2 可视化编辑工具怎么补位文本工具并不是万能的至少在我经历的项目里有两个场景它搞不定。一是前期头脑风暴阶段所有人大脑飞速运转需要快速拖拽、随手写备注这时候没人有空打字敲语法。二是某些需要精细排版的对外材料比如给客户讲方案时图上每个框的位置、每个字的大小都要可控文本工具的自动布局很难做到完全满意。这两个场景我一般求助于可视化工具Excalidraw适合白板协作手绘风让审阅者不自觉地降低心理防线头脑风暴时体验很好还支持多人协同。draw.io适合最终归档支持本地文件、云盘和 Git 仓库也能导入 XML 定义导出的图和文档能比较稳定地匹配。Figma如果团队本身就有设计同学把架构图放进 Figma 和 UI 稿一起评审也很常见缺点是学习成本不低小团队不一定必要。可视化工具的使用边界我心里一直有一根线它负责探索文本工具负责固化。头脑风暴时的潦草草图一旦方向确定就尽快用文本工具沉淀成规范图避免大家在各种图层和格式里迷失。2.3 我的最终组合与判断标准我目前比较稳定的组合是项目文档里全部用 Mermaid 生成图比较正式的架构评审图用 draw.io 手推精修探索期用 Excalidraw 快速白板。三个工具互不冲突切换也很自然。判断工具是否合适我只看三条第一能不能和文档工作流无缝衔接。写 Markdown 时顺手出一张图比专门开一个软件省太多时间。第二能不能做版本管理。图的源文件必须是文本或者可用文本表示这样才能参与团队 Code Review。第三导出格式够不够用。SVG、PNG、PDF 这几个基本导出选项必须具备否则后期写周报、做 PPT 会很痛苦。工具永远是配角判断标准才是主角。与其纠结哪个工具最好不如先想清楚我的图最终要用在哪、谁来维护。想明白这两点选工具基本不会踩大坑。3. 图表设计的核心规范让每一张图都有“秩序感”3.1 先分清图画类型再谈设计很多图之所以乱是因为作者一开始就没想清楚自己要画的是哪种图。架构图画着画着加了流程节点流程图里又出现一堆部署节点类型混在一起视觉语言自然也会混乱。我在项目里把常见技术图分成五类图类型核心问题视觉重点架构图系统的层次与模块边界分组、层次、容器边界流程图事情发生的先后顺序节点顺序、判断分支时序图对象之间的消息交互顺序生命线、消息箭头部署/拓扑图组件落在哪些运行环境节点位置、网络关系ER/类图实体或类的静态关系实体框、关系连线画架构图核心是讲清楚谁在里面、谁在外面、谁依赖谁画流程图核心是先做什么、后做什么、条件如何分流。类型清晰之后再用统一的形状、连线、配色去表达图才不会跑偏。3.2 版式、流向与层级的基本规则版式决定了读者读图的第一路径。我在 diagram-design 规范里强制自己遵守几条规则几乎适用于所有图主阅读方向固定。架构图从左到右表达调用方向流程图从上到下表达时间顺序。除非特殊说明绝不出现混乱的斜向或自下而上的主流向。重要节点放大强调辅助节点弱化收敛。想让读者关注 API 网关就把网关框画大一点、颜色深一点数据库虽然重要但在讲调用链的场景里不必抢戏。分组用容器表达。接入层、业务层、数据层都用框或者泳道圈起来。没有容器节点一旦超过十个图就会散成一盘棋。连线必须表达语义。实线代表同步调用虚线代表异步通知或者配置依赖箭头方向严格指向被调用方。同一张图里线型含义绝对不能出现前后不一致。布局上我也总结了一个很朴素的判断标准如果一张图里出现了三条以上的交叉连线说明布局需要重做不是加交叉点标注就完事。交叉线是阅读理解的最大杀手读者一不小心就走错路径。3.3 配色与组件规范一套可复用的色板我见过太多技术图死于配色背景浅蓝、主框深蓝、副框紫色、强调黄色单看每个颜色都没问题放在一起就变成彩虹图。色彩在架构图里应该承担信息编码任务而不是装饰任务。我给自己定了一套很克制的配色方案用途色值示例使用说明主容器背景#F7F9FC分组容器底色中性百搭核心服务#2563EB主链条上的服务节点中继/辅助组件#64748B网关、代理、消息队列等中间件外部依赖#FFFFFF 边框 #CBD5E1第三方系统用浅色弱化数据存储#0F766E数据库、缓存等存储组件强调色#F59E0B只用于本次重点说明的组件危险/异常#DC2626故障点、警告信息慎用这套色板的逻辑只有一个让颜色承担分类功能。看一眼颜色就知道节点属于哪一类而不是猜。另外要避开完全依赖红绿区分的配色设计灰度打印和色弱环境下这种配色会直接失效。形状也需要规范。矩形代表服务或组件圆角矩形代表外部系统或子模块菱形代表判断圆柱代表存储。这条规则写进团队文档之后我们再也没出现过“这个菱形难道是数据库”的疑问。3.4 让规范真正落地的检查清单规范写得再好不落地就是废纸。每次提交图之前我会过一遍检查清单简单但有效[ ] 主流程从左到右或从上到下没有斜向混乱[ ] 所有节点有统一形状定义不存在形状混用[ ] 颜色全部来自规范色板没有临时取色[ ] 实线/虚线语义全图一致并且图里有图例说明[ ] 字体统一字号层级清晰小字至少保证放大后能看清[ ] 图有标题、日期、版本号方便后续追溯[ ] 节点数量控制在视线可及范围内超了就拆图这套检查清单后来直接做成了 Markdown 模板每次画完图复制一份打勾成本很低但效果显著至少那些低级的“颜色混乱”“箭头无说明”问题基本绝迹了。4. 实操过程从需求到成图的六步法4.1 草图先行先画关系再画框我踩过最大的坑就是打开工具就直接画框。画完第一个框开始纠结颜色画完第二个框开始调整对齐结果画到一半发现核心关系没想清楚整张图推倒重来。现在我坚持草图先行。用一种最土但最有效的方式拿一张白纸或者打开白板先写核心业务对象用箭头把关系连起来完全不考虑美观。这个阶段的目的是确认图上要讲的事。比如在画某个订单服务的架构图时我第一步只画了「前端」到「网关」到「订单服务」到「数据库」再往旁边写了个「物流系统」。整个过程五分钟但足够把核心链路锁定。草图阶段还有一个关键动作标记哪些环节是这次说明的重点。比如这次想强调订单创建走异步通知就在草图上给「消息队列」画个圈。这样后续做视觉编码时才知道哪些节点需要重点突出哪些只需弱化存在。4.2 确定边界与分层草图定了整体关系后接着要解决的是边界问题。一张图不可能囊括所有细节必须明确三层边界系统边界哪些组件是本系统的哪些是外部依赖。外部系统要用弱化色避免喧宾夺主。分层边界通常我会按接入层、业务层、数据层去归纳每一层用一个容器包起来。容器本身也是信息读者不需要细看每个组件只看三个层就知道大概结构。叙述边界这张图里不展开的模块要么不打进去要么打进去但明确标注“详见另一张图”。最怕的是画到一半舍不得删除某个无关模块结果越画越重。分层完成之后图的大骨架基本就出来了。你会发现后续的设计工作都是在往骨架里填组件、凑视觉编码而不是对着空白画布现想。4.3 用代码声明一张架构图一个可直接参考的示例在正式文档中我偏好把复杂的架构图用声明式文本表达出来。下面这个结构是实际项目里我用过的示例说明了各组件之间的调用关系# 订单业务架构图声明示例 客户端 App/Web - 接入网关: HTTP/JSON 接入网关 - 订单服务: 创建订单 订单服务 - MySQL: 写入订单数据 订单服务 - 消息队列: 发送订单事件 消息队列 - 库存服务: 异步扣减库存 库存服务 - 外部物流系统: 创建配送单这段声明看着简单其实已经把三层结构隐含在字里行间最上面是接入层中间是业务层下面偏支撑层。把它转成正式图时只需要套上工具的语法写进文档即可。我更推荐这种方式而不是在绘图软件里手拉框因为文本可读、可 diff、可再加工。很多团队的架构图之所以最后变成一次性图画就是因为源文件只停留在某个人的电脑里根本没法维护。如果你所在团队现在还没有形成规范的图源文件管理我的建议是至少从文本形式的声明开始。有这份文本两个月后图里的关系还能复盘只有一张导出的 PNG三个月后连你自己都说不清当时为什么这么连。4.4 导出、裁剪与嵌入文档的细节处理图画完不等于事情结束导出环节同样能毁掉一张图。我最常见的问题有两个一是导出 PNG 分辨率不够放进 PPT 里一拉就糊二是导出时周围空白留得太多嵌入 Markdown 后图小得看不清。几个实际操作经验首选导出 SVG 格式。矢量图在任何放大倍数下都清晰技术文档和 PPT 都适用浏览器也都能直接渲染。必须用 PNG 时导出分辨率至少选择 2 倍图最好 3 倍。尤其是深色背景的图低分辨率下文字边缘会很毛躁。控制宽度。嵌入文档前检查一下图片的实际显示宽度一般不要超过正文内容宽度的 90%太宽会把排版撑裂。给图配标题和编号比如“图 4-3 订单创建链路”。图注放在图下方引用文字里直接说“见图 4-3”比“如下图所示”专业得多。这些细节看起来琐碎却是决定读者体验的关键。我见过不少内容很好的架构图就是因为导出分辨率太低在文档里变成一团模糊色块最终沦落到没人看的地步。4.5 把组件沉淀成模板库拒绝重复劳动diagram-design 做到后面最有价值的部分是组件库和模板库。一个团队如果每次画图都从空白画布开始等于每张图都在第三次写同样的代码却没有抽公共函数。我在项目里维护了一个 templates 目录结构大概是这样的templates/ ├── architecture/ # 架构图模板 ├── flow/ # 流程图模板 ├── sequence/ # 时序图模板 ├── components/ # 公共组件网关、MQ、数据库等 └── styles/ # 色板、字体、线型定义每次画新图时先看模板库里有没有可以复用的结构先复制再改而不是从零开始。公共组件里的网关、消息队列、数据库等节点形状、颜色、图标都是统一的谁来画都长一样团队图的风格自然就统一起来了。这个习惯坚持下来之后画图的时间大概能省掉三分之一而且团队内部因为“这张图的框怎么和上次不一样”产生的讨论也彻底消失了。5. 常见问题与排查技巧实录5.1 节点太多时怎么防止“蜘蛛网”效应如果你画的图最终变成了一个巨大的蜘蛛网问题不是你的布线技术不好而是信息量超出了一张图能承载的极限。人短时工作记忆大概能同时处理大约七个信息块超过这个数量就很容易迷失。图也遵循同样的规律一张图里的核心节点最好控制在七到十五个之间。我的拆图策略是先画一张总览图只显示最上层分组比如接入层、业务层、数据层不展开具体内部节点。再针对每个重点模块画详细图比如订单服务内部依赖图单独一张部署拓扑图单独一张。如果必须在一张图里表达很多内容就用容器把节点分组让读者先看大结构想深入了解再走进容器内部。有一次我画一个二十多个服务的大架构第一版图密密麻麻铺了一整屏我自己看着都犯晕。后来狠心拆成一张总览加三张子图评审时大家反而快速理解了各模块边界讨论效率高了很多。敢于拆图是 diagram-design 里很难但很值钱的决策。5.2 中文显示与字体排版问题中文是技术绘图里的经典坑。很多声明式工具默认字体对中文支持不好导出的图里经常出现豆腐块或者乱码。我的处理方式是尽量使用对中文友好的字体比如思源黑体、Noto Sans CJK SC避免用那些偏西文的默认字体。统一给正文节点设置中文字体变量全图只使用一种字体标题可以加粗但不要混用多种字体。导出前务必预览检查一遍所有中文文本尤其注意那些引用外部图标或字体库的场景避免字体加载失败导致渲染偏差。字体问题不是技术难题但一旦出现就很影响观感。我建议把“导出一张 PNG 放大 200% 检查文字边缘”作为交图前的固定动作十秒成本能挡住大部分质量问题。5.3 团队协作时怎么维护版本与风格统一个人画图画得再规范团队协作起来还是容易翻车。最大的问题是每个人都坚持自己的审美。我在实践里发现维护统一性不需要靠说服只需要靠流程约束。流程上可以做三件事把图的源文件放进同一套代码仓库和代码一样走评审流程。图的评审和代码评审一起做改图只改源文件不直接改导出的 PNG。命名规范统一。比如模块图统一用“模块名_图类型_版本号”的格式时间一长目录里不会再出现“新建文档”“最终版2”这类灾难性文件名。指定一位图规范维护者不需要是领导只需要是愿意花时间检查图例、配色、命名的人。每个项目迭代时把统一性检查作为发布前的一步。我特别想强调源文件入库这件事。很多团队把图存在聊天记录里、共享盘里最后版本错乱得一塌糊涂。图一旦入库和代码同生命周期这张图是谁画的、为什么这么画、什么时候改的全部有迹可循这是团队协作里价值最高的一项投入。5.4 一些隐藏在细节里的避坑经验最后分享几个散装经验都是实际踩过坑之后才总结出来的图例不是可选项是必选项。就算全图只有一种线型也要在图角落写一行“实线调用虚线异步”。看图的人默认不会对你的符号体系有预设图例是双方达成共识的锚点。别让装饰性元素喧宾夺主。阴影、渐变、高光确实好看但技术图的核心是信息传达。装饰控制在最低限度否则读者会被视觉噪声带走注意力。画完之后倒着读一遍。从终点节点反向沿着箭头走向起点如果每一步都说得通说明逻辑链基本成立如果某条路径断了那一定有问题。保存源图文件时顺手记录配套说明哪怕只有一句“本图画于某需求评审前”三个月后再看也能快速还原上下文。没有配套说明的图就是一张像素画。这些经验谈不上高深但每一条都能实打实地减少“图看不懂”的扯皮时间。尤其是倒着读图这个动作我几乎每次都能发现自己在正向画图时忽略的语义断裂。说实话diagram-design 学到后面最让我受益的不是某个工具用得多熟练而是它逼着我养成了先理清逻辑再动手的习惯。画图如此写代码、写文档也一样任何输出都要先回答“读者是谁、要传达什么、怎么他才不误解”这三个问题。如果你现在也正在被一张说不清的图困扰我的建议很简单先别打开任何工具拿一张白纸把关系和边界画出来再谈颜色和排版。这个动作做完你会发现所谓的 diagram-design其实就是给复杂信息建立秩序的过程。