上个月团队内部评审一张系统架构图画的人花了一周梳理模块关系却只换来了五分钟冷场。不是大家没话说而是所有人都在问同一个问题中间那一大片框到底谁依赖谁、谁在什么时候调用了谁图上的信息量很大但真正需要的那条链路被埋在几十个节点和密密麻麻的连线底下。那一刻我意识到diagram-design 这个事儿和写代码一样缺的不是素材是设计。我这些年画过的图少说也有几百张踩过无数坑之后总结出一条技术图翻车几乎都是因为画图的人把“表达”当成了“罗列”。所以这篇东西我不打算只讲工具按钮重点讲清楚一张图从需求到成品的完整思考过程包括骨架怎么定、样式怎么规范、怎么让团队其他人能持续维护。适合正在搭技术文档体系的人、需要频繁画架构图和流程图的开发以及想把“画图”从个人技能变成团队规范的同学。1. 一张图翻车的现场为什么多数技术图让人越看越懵先还原一下那次评审的现场。投屏上的架构图大概有五六十个矩形每个矩形都有名字所有连接线等宽等色线之间的夹角五花八门。最致命的是图的正中央有一块巨大的分组框里面套了十几个服务但没有任何说明告诉你这是“核心业务域”还是“历史遗留系统”。在场的人一个个眯着眼往前凑像在找茬游戏里找差异。这种翻车不是个例。问题从来不是“画得太满”而是画图的人没有在动手前想清楚这张图要回答什么问题信息堆积不等于表达清楚——每新增一个节点你其实都在增加读者的认知负担。地图就是一个很好的类比。你看城市地铁图它不会把所有公交线路都画上去只保留对“坐地铁”这个决策有用的信息。技术图也一样如果你的目标是表达下单主链路那定时任务、日志采集这类支撑系统就不该占据同样显眼的视觉位置。1.1 信息堆积不等于表达清楚我见过最典型的错误是把“系统中存在的所有东西”都画到一张图里。数据库、缓存、消息队列、定时任务、监控报警、配置中心、网关、第三方 SDK全部铺开然后用线连成一张大网。这看起来非常“完整”但读者根本不知道该从哪里看起。正确做法是反过来先确认这条图只讲一件核心事件然后把事件相关的角色分成“主演”和“群演”。如果一张图有多个同等重要的子流程那不是“融合成一张”而是“拆成多张”。每张图有且只有一条主链路其余的要么弱化到背景要么干脆别画。1.2 没有人会在图上读三遍好的技术图读者扫一眼就能说出核心链路。如果读者需要沿着某条线找半天才发现你画的其实是“异步通知”而不是“同步调用”那就说明线的语义不够明确。图不是悬疑小说不应该让读者花时间推理。我在评审里常做一个小测试把图投出来给所有人十秒钟然后盖住请他们复述这张图讲了什么。凡是说不出“用户请求经过网关进入订单服务再调用库存事件通过消息队列通知物流”这种一句话描述的图的设计大概率有问题——不是阅读理解能力差而是图本身没有在引导视线。1.3 先回答三个问题再落笔动笔之前我强迫自己先回答三个问题这张图的读者是谁读者拿着这张图要做什么判断什么信息对那个判断来说是必需的给开发同学看的图重点可以放在服务之间的调用关系和数据类型给决策者看的图重点应该放在系统边界、核心域和关键风险上。两种图的画法、配色、颗粒度完全不同。我见过有人给老板汇报时把每个服务的线程池参数都标上去那不是设计那是噪音。更常见的问题是把给开发看的详细架构图直接用做外部文档导致每个新加入项目的人都要花一晚上去猜哪些节点是“该关心的”、哪些只是“参考”。下面这张表是我自己用来定位图类型的简化判断图类型读者核心问题理想颗粒度系统架构图研发、架构评审系统边界与依赖服务/模块级别业务流程图产品、业务事件流转与决策步骤/判断节点部署拓扑图运维、SRE节点与网络关系主机/实例级别时序/协作图具体模块负责人消息顺序与角色协作方法/接口级别如果一张图同时想回答上述所有问题那它一定会失败。diagram-design 的第一步其实是明确“不给读者看什么”。2. 先想清楚再开画从需求倒推图的骨架很多人打开画图工具的第一件事是找模板、选配色、拖几个矩形这正好把顺序搞反了。骨架没定之前所有样式工作都是浪费。我习惯先把图形工具关掉用纸笔或者纯文本列一份“实体关系清单”然后把这张图的信息结构梳理出来。2.1 三种基础骨架绝大多数技术图最后都能归到三种基础骨架里层级骨架自上而下或自下而上的分层适合表达系统分层、权限体系、组织关系。流程骨架从左到右或从上到下的主流程适合表达请求链路、业务流程、状态流转。网络/矩阵骨架节点之间互相连接适合表达微服务调用关系、数据流转网络。选骨架不是凭审美而是看核心关系是什么。如果核心关系是“依赖方向”层级骨架会让依赖关系变得一目了然如果核心关系是“事件先后”流程骨架更合适。把矩阵结构的图强行画成自上而下的层级只会产生一堆回环和交叉线。这个选择甚至可以在画图前用一句话描述出来比如“我要表达的核心是请求从左边进从右边出中间只有一个核心处理区”。2.2 主链路、辅助链路与旁路的分层骨架明确之后接下来是给所有元素分角色。我按三级来分主链路读者看完图之后必须记住的路径放在视觉最中心的位置用粗线或实线突出。辅助链路主链路的支撑环节比如配置加载、缓存读取、日志写入放在主链路两侧用普通线宽。旁路/异常链路重试、降级、补偿、异常处理一般用虚线或淡色放在边缘位置。这么分层的好处是即便用户没仔细看每条线他的视线也会被天然引导到主链路上。比如画一个用户登录的流程主链路是“输入账号密码 - 认证服务 - 下发 Token”辅助链路是“读取用户状态 - 加载权限配置”旁路是“密码输错超过三次 - 锁定”。如果把三次锁定和主链路画成同样粗的实线并排读者立刻会被带偏。2.3 用“读图路径”自检画完第一版骨架后我会闭上眼模拟一遍读图路径我的视线会先落在哪里下一步往哪走会不会在中途被一个高亮的辅助节点拽走一个健康的读图路径通常不超过五组节点。比如“外部客户端 - 接入网关 - 订单服务 - 消息队列 - 物流服务”这就是很清楚的一条线。如果读图路径里出现了分支、回退、甚至跳过说明结构还不够直。你可以在图上用透明纸条模拟主链路上每两个相邻节点的位置如果它们之间被其他节点或连线挡住那就需要调整坐标。2.4 学会做减法骨架阶段最容易犯的错误是舍不得删。这里我给一条硬经验画布上主区域内节点超过二十个这张图就该考虑分组或者拆分。不是不能画二十个节点而是人的短时记忆一般只能同时处理四到七组信息。二十个节点如果不做视觉合并读者只能靠数数来理解。具体操作上能合并的合并多个只被同一个上游调用的内部模块可以折叠成一个分组框多个子步骤可以合并成一个“处理阶段”。减法不是为了少画而是为了让真正重要的那部分不被淹没。每删掉一个无关节点主链路的视觉权重都会提升一点。3. 把画布当成排版系统网格、对齐与留白有一个反直觉的事实画图工具越方便图反而越容易乱。因为拖拽太随意了大家很少关心节点坐标之间的逻辑关系。我后面开始把画布当成一个排版系统来对待像排报纸版面一样安排每个元素的位置效果立刻不一样。3.1 先设置画布和网格不要拿默认无限画布直接开画无限画布看着自由但它会毁掉比例感。没有边界时你很容易把节点越拖越散最后导出的图在一张 A4 上看文字小到得用放大镜。我的做法是画图前先定好画布尺寸和方向需要投屏或入文档的用 16:9 横版需要打印的用 A4 横版。然后打开网格对齐把吸附粒度设到 10 或 20 像素。网格是给眼睛一个“可预测的位置系统”。当所有节点的左边缘都对齐在同一垂直线上时读者会下意识觉得这张图“很整齐”反过来哪怕只有两个节点偏离了 5 像素读者也能察觉哪里不对虽然他说不出具体问题。3.2 对齐的三条基本规则经过大量对比我觉得值得作为硬性要求的有三条同一层级内的节点高度一致宽度尽量一致至少保证高度相同否则层次感会被打断。相邻节点之间的水平间距一致。我习惯统一用 20-40 像素的间距而不是随手拖。连接线优先走正交直角线箭头方向和多段线的每个拐点都保持清晰。曲里拐弯的贝塞尔曲线只在非常特殊的场景下才是加分项日常技术图里它只会制造视觉噪音。这三条规则的底层逻辑很简单读者的眼睛擅长做规律预测一旦建立了预判阅读速度就会快很多。正交线之所以好用是因为它的拐点固定是 90 度读者可以顺着折线方向平滑移动视线而任意角度斜线会打断方向感。3.3 留白不是浪费是分组工具不少画图的人恨不得把画布填满仿佛空白就是没干活。但留白在图表设计里和颜色一样重要。两个节点之间距离近读者会默认为“它们是一组”距离远则默认为“它们关系弱”。所以不要用“画得更挤”来省空间而要用间距来表达亲疏。另外大范围归属关系不要只靠颜色区分还要用容器分组框。颜色是二维信号在黑白打印、色弱环境下会失效容器分组则是结构性的谁在谁的框里一眼就明白。给分组框一个清晰的名字比如“核心交易域”“基础设施层”比让读者从一堆相似颜色的节点里猜归属要可靠得多。3.4 重心与构图平衡很多人没有意识到图画布上的“重心”会影响阅读体验。如果所有元素都挤在左上角右下角一大片空白读者视线就会失衡感觉这张图“偏了”。更合理的是让整个图的主体位于画布的视觉中心偏上一点下方或右侧留出给说明和图例的空间。对称不是必需项权重平衡才是。左右两个区域不需要完全等高但视觉重量不能明显倾斜。举个例子左边画了五个节点右边只画了一个小节点右边会显得特别空。这时可以把图例、注释、风险说明放到右侧既补充了内容又压住了重心。4. 颜色和连接线是第二语言样式规范怎么定骨架决定“有什么”样式决定“读者先看到什么”。很多团队没有样式规范完全靠画图人的当天心情决定颜色和线形。结果就是同一套系统在不同文档里长得像两个产品。diagram-design 做到后面必然要沉淀一套样式语言。4.1 颜色数量与语义必须克制一张技术图里高饱和颜色如果超过四种人的注意力就开始平均分配等于没有重点。我的经验是最多三种强调色加中性色。实际操作时先用中性色灰、白铺所有节点然后只给主链路上的核心节点和数据存储上色其余辅助节点保持浅灰。颜色的语义也最好固定下来并写进团队规范。举一套我常用的语义深蓝外部系统或边界系统。绿色当前系统核心服务。橙色异步消息或事件。红色异常、告警、失败路径仅当图里确实有这类节点时才用。灰色支撑性、辅助性、暂不关注的模块。这里有个容易被忽略的坑颜色不能单独承载信息。红绿色盲在人群中比例不低而且文档经常被黑白打印。所以不要让“红色节点”成为唯一区分异常的方式必须配合文字、图标或边框样式。4.2 连接线形就是语法线的样式像语法一样决定读者怎么理解节点间的关系。如果团队没有约定我可以给一套快速上手的规范实线同步调用/强关联。虚线异步调用/事件驱动/弱依赖。粗线主链路/关键路径。细线次要路径/可选调用。箭头指向数据的流向而不是控制流方向这一点要和画图的人提前对齐。还有一个经常被低估的点线不要穿过节点。宁可绕一条线也不要让线从某个节点上面压过去。被穿过的节点会显得“脏”而且容易被误认为和这条线有关系。推进线的更优路线时尽量从上、下、左、右的通道走避免斜插。4.3 字体、文字摆放与文本溢出框里的文字水平居中框外的标注用较小字号、斜体或灰色保持两级层次。不要把整段话塞进框里框内文字超过一行半就该考虑拆分节点或用更短的标签。字体方面中文用系统常见的无衬线体即可英文最好统一用无衬线体不要在图上混用多种字族。字号级差至少要肉眼可辨主节点标题用大一号辅助说明用小一号。最忌讳的是所有文字都同样大小读者无法快速分区。我过去吃过很多次文字溢出的亏。节点宽度不够文字自动换行后超出矩形边框导出图片后显得破烂。解决方法是设好最小节点宽度并按最长标签决定宽度。建议中文标签控制在 8-10 个字以内超过时考虑缩写或拆成两段。4.4 把样式规范沉淀成模板个人画的图终究会被团队接手。与其每次口头叮嘱“你颜色别用太花”不如直接做一套团队级模板把字体、配色、线型、网格、图例位置都固定下来。模板里甚至可以内置几个常用骨架比如“标准三层架构”“请求-异步流程”“部署拓扑”让新同学直接基于骨架改。这一项投入看起来是“额外工作”实际是省时间的长期投资。改模板一次后面每一张图都能少走一小时弯路。而且有模板之后不同文档之间的图风格可以保持一致读者不需要每张图都重新学习一套视觉语言。5. 实操复盘一张订单系统架构图的三轮迭代前面的规则都说完了我挑一个很常见的场景带你把整个流程走一遍。假设有一个模拟订单系统涉及用户端、接入网关、订单服务、库存服务、支付服务、消息队列、物流服务以及一个外部物流查询 SDK。目标是画一张图能讲清楚“下单后系统内部是怎么协作的”。5.1 第一轮只列清单不碰画布先列节点清单用户端 App接入网关订单服务库存服务支付服务消息队列物流服务数据库订单库、库存库、支付库写作一个分组外部物流 SDK再列关系用户端调用网关网关调用订单服务订单服务同步调库存扣减订单服务同步调支付创建单支付结果成功后订单服务发消息到消息队列物流服务消费消息后调用外部物流 SDK。这个阶段不画图只写文字。文字的好处是逼你把“谁依赖谁”说清楚而不是靠位置去暗示。对照着清单主链路已经浮出水面用户端 - 网关 - 订单服务 - 支付/库存 - 消息队列 - 物流服务。5.2 第二轮分组定骨架开始画布布置。先把图画成三层顶部接入层中间业务逻辑层底部基础依赖层。外部物流 SDK 单独放右侧边界数据库放底部消息队列放右侧稍偏下。主链路从左到右走用户端在最左网关次之订单服务居中消息队列偏右物流服务最右。库存和支付作为订单服务的两个同步子调用放在订单服务下方或两侧不要占用主链路的水平位置。这一轮我只关心结构不调颜色。目标是在视觉上形成一条笔直的从左到右的主通道。所有辅助节点都只放在主通道的上下两侧宁可不对称也绝不让辅助节点插到主通道中间。5.3 第三轮样式与标注主结构定了开始应用样式主链路节点填充浅绿色外部系统用深蓝消息队列用橙色数据库用灰色。库存服务和支付服务虽然也重要但它们是主链路的分支用白色底加边框避免抢走主链路的注意力。连线统一用正交线。同步调用用实线消息队列到物流服务用虚线表示异步消费。支付成功回调订单服务这一条也用虚线加注释“webhook”。在画布右上角放一个图例说明实线、虚线、各种颜色的含义。最后加一句图标题“订单提交流程关键链路2025-05 版”以及一行小字说明“灰色模块为支撑系统不在本次讨论范围”。这一步极其重要它替读者划定了图的边界避免他们追着每个灰色节点问。5.4 用一张最小 DSL 让图可版本化如果你和我一样不希望架构图只能靠截图存档建议把源文件存成基于文本的绘图描述用代码仓库管起来。下面是一个示意结构表达主链路关系[用户端] -- [接入网关] [接入网关] -- [订单服务] [订单服务] -- [库存服务] : 同步扣减 [订单服务] -- [支付服务] : 同步创建单 [支付服务] -- [订单服务] : 支付结果回调 [订单服务] -- [消息队列] : 下单成功事件 [消息队列] -- [物流服务] : 异步消费 [物流服务] -- [外部物流SDK]这种文本型源文件的优势是改动可以通过版本管理记录评审时能直接看 diff。不同的绘图工具各自有对应的文本语法你只要选一个团队统一的就好。我强烈建议不要把导出的 PNG 当作唯一存档三个月后没人找得到对应源文件这张图就“死”了。5.5 我自用的最终检查清单每次导出前我会照着这份清单过一遍主链路不经过任何辅助节点能一句话描述。颜色数量不超过四种强调色。所有线都是正交线没有穿节点的线。所有文字没有溢出框边界字号层级至少两级。图例齐全包含线型、颜色、箭头含义。右上角有标题、日期、版本。黑白打印后仍能靠灰度区分关键内容。这套清单看起来繁琐实际执行一次不到两分钟但能拦住九成以上的“看起来不舒服”。6. 让图活下来版本管理、评审流程与自动化校验一张图画完只是开始真正考验人的是它能不能在项目迭代里保持准确。很多架构图诞生那天就是绝版之后再没人更新。这不是团队不爱维护而是画图的人没有给“图”建立合适的工作流。6.1 图也要有源文件而且要用版本管理如果你花一小时调出一张无比精美的架构图结果只导出 PNG 发到群里那下一次修改就要重画一遍没人愿意重画所以图就永远停在旧版本。正确的做法是保存源文件并且把文本形式的绘图源文件纳入代码仓库随代码变更一起走。源文件进入仓库之后评审者可以看历史记录知道这张图最后是谁在什么时候改了什么。更重要的是新成员接手项目时可以通过图的变更历史理解系统的演进脉络这比任何文字描述都直观。6.2 每张图都要有自己的“元信息”图不是孤立的图片它应该自带上下文。我把这些信息称为“图的元信息”标题、日期、维护责任人、对应文档链接、图例说明。在画布右下角留出一小块固定区域放这些内容不显眼但必要。遇到过太多次这样的场景看图的人觉得某个模块“画得好像不对”但对着一张没有标题没有日期的截图完全不知道该去问谁、该在哪看最新版。加上维护责任人的名字至少给后续反馈留了一条路。6.3 评审改图先分类再动手评审会的现场改图是最容易失控的。几个人七嘴八舌画图的人一边改一边验证最后图没改好会议也跑题了。我的做法是评审时把意见分成两类结构类意见例如“这个服务不应该在订单服务之上”“异步链路画错了方向”。这类必须先记录会后再动。样式类意见例如“颜色太浅”“字体太小”。这类可以现场快速调整。结构类修改必须回到清单和骨架阶段重新过一遍而不是直接在成品图上挪节点。有一次评审会上有人提出“库存服务不应该从属于订单服务它是独立域”当场挪了一个节点结果一排连接线全部交叉后面花了半小时才理顺。这个教训说明结构改动牵一发动全身最好在源文件里基于文本快速调整再刷新渲染而不是拖拽。6.4 做一点自动化校验拦住低级错误如果你的图表源文件是文本格式那就能写脚本做校验。我维护了一套很简单的检查脚本规则包括是否存在没有任何连接线的孤立节点节点总数是否超过 20 个强调色数量是否超过 4 种是否存在文字宽度超出节点宽度的风险是否缺少图例或标题伪代码思路大致是for node in nodes: if not node.linked: report(孤立节点, node.id) if node.label_width node.width: report(文字溢出, node.id) if count_colors(nodes) 4: report(颜色超限, 强调色超过四种) if 说明 not in graph.blocks and 图例 not in graph.blocks: report(缺少图例或说明, graph.name)这层校验不追求判断“图好不好看”它只是拦住最基础的结构问题。好处很实际团队多人协作时每个人提交的图至少能保证不犯低级错误评审的重心就能放到真正的架构设计上而不是纠结点线颜色。7. 最后补几个我踩过的细节坑前面讲的是方法论这部分说点更接地气的都是我在实际项目里摔过跤、后来慢慢趟平的经验。7.1 文字溢出的隐蔽来源节点宽度明明够文字还是溢出大概率是输入了全角空格或者用了不同字体族。中文和英文混排时同一个标签在不同字体下的宽度差异很大。我的处理方式是所有节点文字强制使用同一种字体并且设置“不自动换行、超出则隐藏”之前先检查最长标签到底多长。宁可把框拉宽一点也不要让它变成个被撑破的气球。7.2 用“先灰后彩”控制颜色膨胀画图的人很容易在调色板里越陷越深。这里有个非常有效的土办法先给整张图全部用灰色然后按重要程度逐个把节点改成强调色。上到第四个强调色时如果还有节点想变色就说明这张图的重点太多要回去做减法了。这个办法从源头上防止彩虹图。7.3 不要为了对称牺牲阅读顺序人天生喜欢对称但技术图的阅读顺序远比对称重要。曾经为了左右对称把消息队列放到中间结果主链路被弯成了“U”型读者看完根本不知道事件是什么时候发的。后来我彻底放弃了“对称优先”的念头一律按时间或依赖顺序摆布哪怕右侧多出一块空白也不要为了填满而打断链路。7.4 配色永远要考虑黑白打印很多评审场景里投影仪是彩色的但大家打印出来复核时是黑白的。一个浅蓝一个浅绿在彩色屏幕上区分明显打印出来却几乎一样灰。选颜色时第一时间做一次灰度预览如果区别不明显就换亮度差异更大的颜色或者直接加大边框粗细、加图标来辅助区分。以上这些经验不是一次到位的而是画了几百张图、改了无数版之后才慢慢总结出来的。diagram-design 真正难的不是画图技巧而是每一次落笔之前都愿意多花十分钟想清楚“这张图到底要让谁看懂什么”。只要这个习惯养成你画的每一张图都会比上一张更耐看也更能扛住评审和时间的检验。