最近在梳理内部项目时拿到一个叫diagram-design的模块。乍看名字很直白不就是画图吗真正动手之后才发现这件事的难度不在于“画”而在于“设计”——如何让一张架构图、流程图或时序图在评审会上三秒钟就能被看懂在事后翻阅时不会让人皱眉。这篇文章我想从实际踩坑的角度把 diagram-design 这个主题拆开聊一聊它解决的到底是什么问题、图表的底层逻辑是什么、不同场景该选什么图型、以及从文字草图到最终成图的完整实操链路。适合后端工程师、架构师、技术文档维护者以及所有需要靠图来做沟通的人。1. 先看受众再谈画法1.1 一张图被反问往往不是画得丑做技术的人普遍有个误区图不好看是因为工具用得不够熟练或者配色不够高级。我以前也这么想直到有一次评审会上我用成品架构图讲方案台下某资深开发问了一句“这个模块和那个模块之间到底是同步调用还是异步消息”我低头看了三秒自己也反应不过来——因为我在图上堆了二十几个方框和十几条线但弱化了最关键的关系语义。那次之后我意识到diagram-design 的本质是信息设计不是美术设计。读者看图时第一反应是找“主路径”第二反应是找“关系和依赖”最后才轮到“细节和参数”。如果你把主路径淹没在装饰性元素里再漂亮的图也是失败的。所以画图之前要先回答几个问题读者是谁他想从这张图里得到什么他会在什么场景下看图——是在评审会上听你讲还是事后自己翻文档还是排查问题的时候定位依赖关系这三个场景对应的图面组织方式完全不同。评审会上需要用大字号、强对比、少分支文档里需要完整、准确、可检索排查问题时需要突出依赖方向和故障点。1.2 四类受众与对应的图面策略我做了几年技术文档和方案设计之后把看图的人粗略分成四类每一类对图的诉求差异很大。受众关注点图面策略核心开发模块接口、数据流、状态流转突出边界、命名规范连线必须标明方向与类型运维部署关系、依赖端口、容灾分层展示标注环境、协议、可用性要求产品经理功能边界、用户流程用泳道和阶段分组隐藏技术实现细节管理层方案合理性、风险、成本大颗粒度先看主干再提供下钻入口给核心开发看的图可以把圈层架构图直接画到类级别连线标明同步/异步、推/拉、单向/双向给管理层看的图顶层只留系统框和关键依赖具体模块折叠到第二层甚至第三层。同一套系统至少要准备两个抽象层级的图这是一个我强烈推荐的实操习惯。2. 图表的底层设计逻辑元素、关系、视觉层次2.1 元素是词汇形状和颜色自带语义所有图表都由元素构成。方框、圆角矩形、圆柱体、菱形、云朵……它们的形状本身就在传达语义。圆角矩形适合“普通处理模块”直角矩形更适合“外部系统或子系统”圆柱体是数据库云朵是外部环境菱形是判断分支。这些约定不是谁规定的审美标准而是读者已经形成的认知惯性。如果你觉得圆角矩形好看把数据库也画成圆角矩形那读者就要多花半秒去猜“这是个模块还是存储”信息就损耗了。颜色同理。颜色在图里承担的是“分层”和“告警”功能不是装饰功能。一个方框用红色读者会下意识认为它代表异常、风险或禁止用绿色则代表正常、放行。如果你只是为了好看把相同层级的模块涂成五颜六色那等于给读者设置了无意义的视觉噪音。我的建议是同一张图里的填充色不超过四种语义必须可解释。比如一种颜色表示“本服务”、一种表示“外部依赖”、一种表示“数据存储”、一种表示“风险/异常”剩下的交给灰白系。2.2 关系是语法连线方式决定信息准确度元素是名词连线是动词。两个方框之间画一条线读者会默认它们“有关系”但具体是什么关系取决于线的形态和箭头实线箭头强依赖、直接调用、数据流向。这是最常用、也最需要谨慎的线型。虚线箭头异步依赖、事件订阅、弱关联。不带箭头实线关联关系、配置关系、同属一个逻辑分组。粗线或双线主链路、核心路径、高吞吐通道。细线辅助链路、旁路逻辑。很多图看起来乱核心问题就是“关系语义不统一”。同一个系统里张三用虚线表示异步李四用虚线表示“可选依赖”图例又没有写清楚最后读图的人只能靠猜。这里有一个很小但很关键的实操点所有非标准线型必须在图例里说明。如果你用了三种虚线类型至少要在图脚或图内注释里写清每一种的含义。另一个容易忽略的是连接线的路由方式。正交线段适合架构图和流程图因为它符合阅读习惯、看起来干净斜线适合表达非规则的依赖关系但它会让版面显得凌乱。我现在的习惯是尽量用正交路由转折点控制在两个以内如果两个模块之间有多条关系线需要二次梳理——要么合并连线并标注多关系要么把重点关系单独成图。2.3 视觉层次就是排版网格、对齐与阅读顺序图的阅读顺序从左上到右下这是文字阅读习惯的自然延伸。设计图的时候你得先确定“读者眼睛的第一落点”在哪里。以架构图为例第一落点应该是整体边界和核心入口——网关、负载均衡、主服务。然后视线沿着主链路移动再延伸到外围依赖。实现这种引导靠三样东西对齐、间距、分组。对齐所有同层级的方框要水平或垂直对齐避免错位。错位会让读者觉得你在表达某种隐含关系但它只是排版没对齐。间距间距要有一致性。我常用的做法是给每个方框设一个统一的边距模块之间的间隙保持倍率关系。比如基础间距 16px模块间距是 32px分组间距是 64px这样视觉密度均匀稳定。分组多个模块属于同一个子系统时用大的容器框或背景色块把它们包起来容器命名写在左上角或顶部。分组能大幅降低认知负担因为读者不用自己数边界。这里引入一个概念认知负荷。图的信息量过大时读者的工作记忆会过载。三秒内无法锁定主干这张图就已经失败了一半。控制认知负荷最简单的方法就是分层呈现主干结构用实线粗框二级细节用细线或淡色第三级信息干脆不要放进主图放到附注或子图里。3. 图型选型什么场景用什么表达3.1 架构图系统级宏观地图架构图是 diagram-design 里最常见的类型它要回答的问题是“系统由什么组成怎么部署依赖什么外部资源。”架构图又细分多种风格无边界风格适合小系统矩形容器风格适合多子系统的中大型系统图层风格适合展示分层架构。画架构图最容易出错的地方是“试图把所有信息塞进一张图”。我见过一张图既有容器、又有 Pod 数量、又有 API 路径、又有数据库表名、还有机器数量最后密密麻麻像电路板。架构图应该是宏观地图先表达子系统边界和连接关系具体模块、接口路径、资源规格属于第二层甚至第三层信息可以拆成独立子图。命名方面架构图上的每个方框都应该是“名词性短语”比如“用户服务”“订单数据库”不要用“xxx 的模块”“逻辑处理”这类模糊表达。容器框内还可以标上技术栈缩写但需要统一放到底部注释或图例中不要直接堆在框内制造噪音。3.2 流程图过程与分支流程图用于描述业务的处理顺序和分支决策。画流程图的核心是逐一列出所有可能路径包括正常路径、异常路径、超时重试路径、取消路径。很多时候流程图难懂不是因为分支多而是因为作者只画了“幸运路径”读者一旦对不上现实场景就会疑惑。流程图中菱形判断框的使用要克制。一个判断框出来后对应路径必须明确标注“是/否”“成功/失败”并且两个分支都要有后续节点。如果判断分支超过四个考虑用状态机替代流程图或者用表格式的分支规则来简化图面。另一个实用技巧是泳道图。当流程跨越多个角色或多个系统时泳道图能清晰表达“谁负责什么”。每个泳道对应一个角色或系统流程线在各泳道之间穿梭。泳道的核心价值是让责任边界一目了然但泳道数量不超过六条超过六条可读性会急剧下降需要拆成子流程。3.3 时序图与协作图时间上的先后时序图适合描述跨系统的消息交互顺序尤其适合排查线上问题、讨论接口协议、设计异步事件链路。它的横轴是参与方纵轴是时间消息按时间顺序从上到下排列。时序图最大的好处是把“先后关系”变成空间位置阅读者不需要在脑子里排队。画时序图时要注意消息编号和异步语义。同步调用画实线箭头带返回虚线异步事件画实线箭头加“async”标注事件订阅可以用粗箭头或特殊线型标注。对于复杂的消息链路我习惯在每个消息旁边标上序号1、2、3…这样即使参与方多、线交叉读者也能按号码顺序追踪。时序图的一个常见反例是“线太多导致交叉”。参与方控制在七个以内超过七个应拆成多张子图或把不核心的参与方合并为一个“外部系统”泳道。消息文案要写动词短语比如“创建订单请求”“返回订单详情”不要写无意义的名字。3.4 数据关系图与用户旅程图这两类图的用途差异很大但都很容易被忽视。数据关系图ER 图解决的是“数据如何组织”的问题。实体、属性、关系、基数一对一、一对多、多对多是它的四个基本元素。画 ER 图时最容易犯的错误是把表结构直接搬上来所有字段全画出来连 created_at、updated_at 都不放过。ER 图应该表达核心业务实体和它们之间的关系字段细节留给字段字典或表结构文档。关系线两端的基数标注1、N、1..N必须显式画出否则没法判断是“一个订单对应多条记录”还是“一条记录对应多个订单”。用户旅程图则是从用户视角描述“用户为什么来、做什么、遇到什么问题”。它不属于传统技术图但在跨职能协作时非常重要。用户旅程图要画出用户的每一步操作、情绪起伏、系统触点、痛点机会点。它的价值在于把产品经理、设计师、开发拉到同一张画布前对齐“用户真实体验路径”。不同图型承担的使命差异很大选型错了后面的努力基本都白费。4. 实操链路从文本草图到规范成图4.1 第一步先写文字不要急着开画布很多人的作图流程是打开画布拉几个方框连几条线边画边想。这个流程最大的问题是结构没有想清楚就被视觉带偏画到一半发现布局不对又整体推翻浪费大量时间。我现在的流程第一步永远是用纯文本把结构写清楚。比如想画一个订单系统的架构图先写内容结构入口层客户端 App / Web / 开放平台 API 网关层API 网关鉴权、限流、路由 业务层用户服务 / 订单服务 / 支付服务 / 库存服务 数据层用户库主-从/ 订单库分片/ 缓存 外部依赖三方支付SDK / 消息推送平台 / 短信渠道 辅助链路监控系统 / 日志采集 / 告警通道第二步用箭头梳理关系客户端 -- API网关 API网关 -- 订单服务 订单服务 -- 支付服务 支付服务 -- 三方支付SDK 订单服务 -- 订单库 库存服务 -- 消息队列 -- 订单服务这种纯文本形式的好处是可以放在代码仓库里做版本管理可以 review可以快速调整结构。等到文字结构稳定了再进入画布环节。你会发现当结构清楚时画图只是翻译工作顺手就能完成。4.2 第二步用文本即图工具产出正式图选定图型之后我会优先考虑“文本即图”类的工具。它的核心价值不是省去拖拽时间而是把图变成“可读的代码”让设计过程可评审、可追踪、可 diff。这类工具的核心语法一般包含三部分节点定义、连线定义、样式属性。节点用中括号或圆括号表达连线用箭头符号表达分组容器用大括号包裹。样式方面可以指定填充色、边框色、线型和字体大小。关键参数的设定要遵循前文的原则颜色不超过四类字体统一间距用默认缩放或手动统一。有人会问既然有可视化拖拽工具为什么还要用文本即图我举一个真实场景某次做跨系统改造方案图在评审会上被要求调整一个模块的边界。如果使用拖拽工具我需要重新拉框、调整连线、挪动布局最少十五分钟文本方式下只需要移动一个节点的定义重新生成图十秒钟完成而且数据流关系完全跟着结构走不会出现“忘改连线的箭头的方向”这种低级错误。但文本即图也有局限。过于复杂的交互式架构图、非常注重视觉表现力的汇报图还是需要专业绘图工具手动调整。我的习惯是逻辑型图架构、流程、时序用文本即图汇报型图产品插图、技术品牌宣传用绘图工具精修。4.3 第三步统一样式与导出规范结构对了、工具选对了最后一步是样式规范。很多图看起来“做得不够专业”问题就出在样式不统一。下面是我想重点强调的几个通用规范配色主色不超过三种辅助色一种警告色一种。主色用于系统边界和核心模块辅助色用于外部依赖警告色用于标风险节点。背景色建议白色或极浅灰不要用深色背景除非你要印到深色 PPT 里。字体中文字体用无衬线字体比如系统默认英文和数字用等宽字体字体大小分三个级别容器标题 14~16px节点名称 12~14px注释说明 10~12px。同一张图内同级别文字必须同字号。线宽容器边框 1.5~2px节点边框 1~1.5px连接线 1~1.5px主链路可加粗至 2px。导出弹性布局图导出时注意留白四周至少 20px 边距位图导出建议 2 倍分辨率保证在 PPT 放大时不会糊尽量同时导出 SVG 版本方便后续修改。这些参数最好是团队内统一的而不是每次画图靠手感。4.4 文档与代码协同图也要进版本管理图不仅是沟通工具更是项目资产。我强烈建议把图纳入代码仓库跟文档和代码一起管理。这样有哪些实际好处第一图的变化可以历史追溯。某次方案调整改了什么连接关系打开记录就能看到不必跑到聊天记录里翻旧图。第二变更 review 更高效。同事提交了一个架构图改动评审人可以看到图中哪些节点、连线发生了变化而不是只看最终成品。第三图与代码同步演化。当某个服务的接口升级了对应的架构图也随之修改不会出现“文档是旧的、代码是新的”这种经典问题。具体落地上可以在仓库里建立一个 diagrams 目录图源文件、导出图片、图例说明都放一起README 里写清楚“文字描述改哪个文件、重新生成图的命令是什么、导出规范是什么”。这套机制一旦跑起来图的维护成本会大幅下降。5. 翻车现场与排查技巧作图时的常见问题速查5.1 六类高频翻车问题下面是我在大量 review 图中总结出的高频问题按严重程度排列问题现象根因解决方式关系方向混乱两个模块之间看见双向箭头但实际只有单向调用没有梳理调用关系就连线绘制前列出所有依赖清单分层错位数据库和服务放在同一个层级边界不清晰没有定义容器与分层先画容器再填充节点颜色过度装饰同一张图用了十几种彩色方块把颜色当装饰颜色数量控制在四种以内字体大小混乱标题、注释、节点名难分彼此没有统一字号规范按三层字号体系执行线形语义不统一同一类关系不同作者画出不同线型缺少图例和约定建立统一图例并附注解信息密度超标一张图表达了所有细节阅读成本极高试图“一次讲完”分层出子图主图保持精炼5.2 从“图难看”到“不知道哪里难看”的排查顺序有时候你知道图有问题但说不清问题在哪。我建议按下面的顺序排查信息结构层先检查图和文字说明是否一致。连线方向对不对节点是否都是必要信息有没有遗漏关键依赖信息结构错了后面怎么调样式都没用。视觉结构层再看分组和布局。同层级的模块是否对齐分组容器是否正确主路径是否占据了图面视觉中心如果主链路散落在图边角读者很难抓住重点。细节规范层最后看样式配色、字体、线型是否统一图例是否完整。样式问题最好解决但也最影响观感。这个排查顺序能帮你快速定位“问题出在哪一层”避免花大量时间调色却发现结构本身有问题。5.3 团队图规范落地怎么不招人烦规范再完整如果团队成员不遵守等于没有。我在几个团队里推行过 diagram-design 相关的图规范总结出三条落地经验第一小范围试点。不要一开始就要求全团队按规范执行先找一两个核心项目做试点把规范跑通产生几个高质量示例。第二模板先行。提供可直接复用的模板仓库包含语法文件、样式配置、导出脚本别人不用从零开始理解规范打开模板改内容就行。第三评审机制。技术评审里把图作为必审项评审人按规范逐项检查。开始时大家会觉得繁琐但坚持两三轮之后会形成肌肉记忆图的质量会明显上升。这三个经验是我觉得推行图规范最重要的三点。我个人在实际操作中最深的体会是diagram-design 真正难的不是工具或绘图技巧而是你能不能“先想清楚再动手”。如果连文字结构都没理清就去拖方框连线最终只会得到一张看起来像样、但经不起追问的图。反过来当你在文字层面把结构、关系、层次都梳理完毕绘图工具只是最后一公里的表达手段。建议下次拿到画图任务时先开一个文本文件写结构把受众、主链路、依赖关系都写明白再打开画布。这个过程坚持三个月你会发现自己画的图拿到任何评审会上都不怵。 
长河君 · 2026/10/19 11:12:43 · 阅读 1.2k diagram-design实战：架构图与流程图的设计逻辑与落地规范
最近在梳理内部项目时拿到一个叫diagram-design的模块。乍看名字很直白不就是画图吗真正动手之后才发现这件事的难度不在于“画”而在于“设计”——如何让一张架构图、流程图或时序图在评审会上三秒钟就能被看懂在事后翻阅时不会让人皱眉。这篇文章我想从实际踩坑的角度把 diagram-design 这个主题拆开聊一聊它解决的到底是什么问题、图表的底层逻辑是什么、不同场景该选什么图型、以及从文字草图到最终成图的完整实操链路。适合后端工程师、架构师、技术文档维护者以及所有需要靠图来做沟通的人。1. 先看受众再谈画法1.1 一张图被反问往往不是画得丑做技术的人普遍有个误区图不好看是因为工具用得不够熟练或者配色不够高级。我以前也这么想直到有一次评审会上我用成品架构图讲方案台下某资深开发问了一句“这个模块和那个模块之间到底是同步调用还是异步消息”我低头看了三秒自己也反应不过来——因为我在图上堆了二十几个方框和十几条线但弱化了最关键的关系语义。那次之后我意识到diagram-design 的本质是信息设计不是美术设计。读者看图时第一反应是找“主路径”第二反应是找“关系和依赖”最后才轮到“细节和参数”。如果你把主路径淹没在装饰性元素里再漂亮的图也是失败的。所以画图之前要先回答几个问题读者是谁他想从这张图里得到什么他会在什么场景下看图——是在评审会上听你讲还是事后自己翻文档还是排查问题的时候定位依赖关系这三个场景对应的图面组织方式完全不同。评审会上需要用大字号、强对比、少分支文档里需要完整、准确、可检索排查问题时需要突出依赖方向和故障点。1.2 四类受众与对应的图面策略我做了几年技术文档和方案设计之后把看图的人粗略分成四类每一类对图的诉求差异很大。受众关注点图面策略核心开发模块接口、数据流、状态流转突出边界、命名规范连线必须标明方向与类型运维部署关系、依赖端口、容灾分层展示标注环境、协议、可用性要求产品经理功能边界、用户流程用泳道和阶段分组隐藏技术实现细节管理层方案合理性、风险、成本大颗粒度先看主干再提供下钻入口给核心开发看的图可以把圈层架构图直接画到类级别连线标明同步/异步、推/拉、单向/双向给管理层看的图顶层只留系统框和关键依赖具体模块折叠到第二层甚至第三层。同一套系统至少要准备两个抽象层级的图这是一个我强烈推荐的实操习惯。2. 图表的底层设计逻辑元素、关系、视觉层次2.1 元素是词汇形状和颜色自带语义所有图表都由元素构成。方框、圆角矩形、圆柱体、菱形、云朵……它们的形状本身就在传达语义。圆角矩形适合“普通处理模块”直角矩形更适合“外部系统或子系统”圆柱体是数据库云朵是外部环境菱形是判断分支。这些约定不是谁规定的审美标准而是读者已经形成的认知惯性。如果你觉得圆角矩形好看把数据库也画成圆角矩形那读者就要多花半秒去猜“这是个模块还是存储”信息就损耗了。颜色同理。颜色在图里承担的是“分层”和“告警”功能不是装饰功能。一个方框用红色读者会下意识认为它代表异常、风险或禁止用绿色则代表正常、放行。如果你只是为了好看把相同层级的模块涂成五颜六色那等于给读者设置了无意义的视觉噪音。我的建议是同一张图里的填充色不超过四种语义必须可解释。比如一种颜色表示“本服务”、一种表示“外部依赖”、一种表示“数据存储”、一种表示“风险/异常”剩下的交给灰白系。2.2 关系是语法连线方式决定信息准确度元素是名词连线是动词。两个方框之间画一条线读者会默认它们“有关系”但具体是什么关系取决于线的形态和箭头实线箭头强依赖、直接调用、数据流向。这是最常用、也最需要谨慎的线型。虚线箭头异步依赖、事件订阅、弱关联。不带箭头实线关联关系、配置关系、同属一个逻辑分组。粗线或双线主链路、核心路径、高吞吐通道。细线辅助链路、旁路逻辑。很多图看起来乱核心问题就是“关系语义不统一”。同一个系统里张三用虚线表示异步李四用虚线表示“可选依赖”图例又没有写清楚最后读图的人只能靠猜。这里有一个很小但很关键的实操点所有非标准线型必须在图例里说明。如果你用了三种虚线类型至少要在图脚或图内注释里写清每一种的含义。另一个容易忽略的是连接线的路由方式。正交线段适合架构图和流程图因为它符合阅读习惯、看起来干净斜线适合表达非规则的依赖关系但它会让版面显得凌乱。我现在的习惯是尽量用正交路由转折点控制在两个以内如果两个模块之间有多条关系线需要二次梳理——要么合并连线并标注多关系要么把重点关系单独成图。2.3 视觉层次就是排版网格、对齐与阅读顺序图的阅读顺序从左上到右下这是文字阅读习惯的自然延伸。设计图的时候你得先确定“读者眼睛的第一落点”在哪里。以架构图为例第一落点应该是整体边界和核心入口——网关、负载均衡、主服务。然后视线沿着主链路移动再延伸到外围依赖。实现这种引导靠三样东西对齐、间距、分组。对齐所有同层级的方框要水平或垂直对齐避免错位。错位会让读者觉得你在表达某种隐含关系但它只是排版没对齐。间距间距要有一致性。我常用的做法是给每个方框设一个统一的边距模块之间的间隙保持倍率关系。比如基础间距 16px模块间距是 32px分组间距是 64px这样视觉密度均匀稳定。分组多个模块属于同一个子系统时用大的容器框或背景色块把它们包起来容器命名写在左上角或顶部。分组能大幅降低认知负担因为读者不用自己数边界。这里引入一个概念认知负荷。图的信息量过大时读者的工作记忆会过载。三秒内无法锁定主干这张图就已经失败了一半。控制认知负荷最简单的方法就是分层呈现主干结构用实线粗框二级细节用细线或淡色第三级信息干脆不要放进主图放到附注或子图里。3. 图型选型什么场景用什么表达3.1 架构图系统级宏观地图架构图是 diagram-design 里最常见的类型它要回答的问题是“系统由什么组成怎么部署依赖什么外部资源。”架构图又细分多种风格无边界风格适合小系统矩形容器风格适合多子系统的中大型系统图层风格适合展示分层架构。画架构图最容易出错的地方是“试图把所有信息塞进一张图”。我见过一张图既有容器、又有 Pod 数量、又有 API 路径、又有数据库表名、还有机器数量最后密密麻麻像电路板。架构图应该是宏观地图先表达子系统边界和连接关系具体模块、接口路径、资源规格属于第二层甚至第三层信息可以拆成独立子图。命名方面架构图上的每个方框都应该是“名词性短语”比如“用户服务”“订单数据库”不要用“xxx 的模块”“逻辑处理”这类模糊表达。容器框内还可以标上技术栈缩写但需要统一放到底部注释或图例中不要直接堆在框内制造噪音。3.2 流程图过程与分支流程图用于描述业务的处理顺序和分支决策。画流程图的核心是逐一列出所有可能路径包括正常路径、异常路径、超时重试路径、取消路径。很多时候流程图难懂不是因为分支多而是因为作者只画了“幸运路径”读者一旦对不上现实场景就会疑惑。流程图中菱形判断框的使用要克制。一个判断框出来后对应路径必须明确标注“是/否”“成功/失败”并且两个分支都要有后续节点。如果判断分支超过四个考虑用状态机替代流程图或者用表格式的分支规则来简化图面。另一个实用技巧是泳道图。当流程跨越多个角色或多个系统时泳道图能清晰表达“谁负责什么”。每个泳道对应一个角色或系统流程线在各泳道之间穿梭。泳道的核心价值是让责任边界一目了然但泳道数量不超过六条超过六条可读性会急剧下降需要拆成子流程。3.3 时序图与协作图时间上的先后时序图适合描述跨系统的消息交互顺序尤其适合排查线上问题、讨论接口协议、设计异步事件链路。它的横轴是参与方纵轴是时间消息按时间顺序从上到下排列。时序图最大的好处是把“先后关系”变成空间位置阅读者不需要在脑子里排队。画时序图时要注意消息编号和异步语义。同步调用画实线箭头带返回虚线异步事件画实线箭头加“async”标注事件订阅可以用粗箭头或特殊线型标注。对于复杂的消息链路我习惯在每个消息旁边标上序号1、2、3…这样即使参与方多、线交叉读者也能按号码顺序追踪。时序图的一个常见反例是“线太多导致交叉”。参与方控制在七个以内超过七个应拆成多张子图或把不核心的参与方合并为一个“外部系统”泳道。消息文案要写动词短语比如“创建订单请求”“返回订单详情”不要写无意义的名字。3.4 数据关系图与用户旅程图这两类图的用途差异很大但都很容易被忽视。数据关系图ER 图解决的是“数据如何组织”的问题。实体、属性、关系、基数一对一、一对多、多对多是它的四个基本元素。画 ER 图时最容易犯的错误是把表结构直接搬上来所有字段全画出来连 created_at、updated_at 都不放过。ER 图应该表达核心业务实体和它们之间的关系字段细节留给字段字典或表结构文档。关系线两端的基数标注1、N、1..N必须显式画出否则没法判断是“一个订单对应多条记录”还是“一条记录对应多个订单”。用户旅程图则是从用户视角描述“用户为什么来、做什么、遇到什么问题”。它不属于传统技术图但在跨职能协作时非常重要。用户旅程图要画出用户的每一步操作、情绪起伏、系统触点、痛点机会点。它的价值在于把产品经理、设计师、开发拉到同一张画布前对齐“用户真实体验路径”。不同图型承担的使命差异很大选型错了后面的努力基本都白费。4. 实操链路从文本草图到规范成图4.1 第一步先写文字不要急着开画布很多人的作图流程是打开画布拉几个方框连几条线边画边想。这个流程最大的问题是结构没有想清楚就被视觉带偏画到一半发现布局不对又整体推翻浪费大量时间。我现在的流程第一步永远是用纯文本把结构写清楚。比如想画一个订单系统的架构图先写内容结构入口层客户端 App / Web / 开放平台 API 网关层API 网关鉴权、限流、路由 业务层用户服务 / 订单服务 / 支付服务 / 库存服务 数据层用户库主-从/ 订单库分片/ 缓存 外部依赖三方支付SDK / 消息推送平台 / 短信渠道 辅助链路监控系统 / 日志采集 / 告警通道第二步用箭头梳理关系客户端 -- API网关 API网关 -- 订单服务 订单服务 -- 支付服务 支付服务 -- 三方支付SDK 订单服务 -- 订单库 库存服务 -- 消息队列 -- 订单服务这种纯文本形式的好处是可以放在代码仓库里做版本管理可以 review可以快速调整结构。等到文字结构稳定了再进入画布环节。你会发现当结构清楚时画图只是翻译工作顺手就能完成。4.2 第二步用文本即图工具产出正式图选定图型之后我会优先考虑“文本即图”类的工具。它的核心价值不是省去拖拽时间而是把图变成“可读的代码”让设计过程可评审、可追踪、可 diff。这类工具的核心语法一般包含三部分节点定义、连线定义、样式属性。节点用中括号或圆括号表达连线用箭头符号表达分组容器用大括号包裹。样式方面可以指定填充色、边框色、线型和字体大小。关键参数的设定要遵循前文的原则颜色不超过四类字体统一间距用默认缩放或手动统一。有人会问既然有可视化拖拽工具为什么还要用文本即图我举一个真实场景某次做跨系统改造方案图在评审会上被要求调整一个模块的边界。如果使用拖拽工具我需要重新拉框、调整连线、挪动布局最少十五分钟文本方式下只需要移动一个节点的定义重新生成图十秒钟完成而且数据流关系完全跟着结构走不会出现“忘改连线的箭头的方向”这种低级错误。但文本即图也有局限。过于复杂的交互式架构图、非常注重视觉表现力的汇报图还是需要专业绘图工具手动调整。我的习惯是逻辑型图架构、流程、时序用文本即图汇报型图产品插图、技术品牌宣传用绘图工具精修。4.3 第三步统一样式与导出规范结构对了、工具选对了最后一步是样式规范。很多图看起来“做得不够专业”问题就出在样式不统一。下面是我想重点强调的几个通用规范配色主色不超过三种辅助色一种警告色一种。主色用于系统边界和核心模块辅助色用于外部依赖警告色用于标风险节点。背景色建议白色或极浅灰不要用深色背景除非你要印到深色 PPT 里。字体中文字体用无衬线字体比如系统默认英文和数字用等宽字体字体大小分三个级别容器标题 14~16px节点名称 12~14px注释说明 10~12px。同一张图内同级别文字必须同字号。线宽容器边框 1.5~2px节点边框 1~1.5px连接线 1~1.5px主链路可加粗至 2px。导出弹性布局图导出时注意留白四周至少 20px 边距位图导出建议 2 倍分辨率保证在 PPT 放大时不会糊尽量同时导出 SVG 版本方便后续修改。这些参数最好是团队内统一的而不是每次画图靠手感。4.4 文档与代码协同图也要进版本管理图不仅是沟通工具更是项目资产。我强烈建议把图纳入代码仓库跟文档和代码一起管理。这样有哪些实际好处第一图的变化可以历史追溯。某次方案调整改了什么连接关系打开记录就能看到不必跑到聊天记录里翻旧图。第二变更 review 更高效。同事提交了一个架构图改动评审人可以看到图中哪些节点、连线发生了变化而不是只看最终成品。第三图与代码同步演化。当某个服务的接口升级了对应的架构图也随之修改不会出现“文档是旧的、代码是新的”这种经典问题。具体落地上可以在仓库里建立一个 diagrams 目录图源文件、导出图片、图例说明都放一起README 里写清楚“文字描述改哪个文件、重新生成图的命令是什么、导出规范是什么”。这套机制一旦跑起来图的维护成本会大幅下降。5. 翻车现场与排查技巧作图时的常见问题速查5.1 六类高频翻车问题下面是我在大量 review 图中总结出的高频问题按严重程度排列问题现象根因解决方式关系方向混乱两个模块之间看见双向箭头但实际只有单向调用没有梳理调用关系就连线绘制前列出所有依赖清单分层错位数据库和服务放在同一个层级边界不清晰没有定义容器与分层先画容器再填充节点颜色过度装饰同一张图用了十几种彩色方块把颜色当装饰颜色数量控制在四种以内字体大小混乱标题、注释、节点名难分彼此没有统一字号规范按三层字号体系执行线形语义不统一同一类关系不同作者画出不同线型缺少图例和约定建立统一图例并附注解信息密度超标一张图表达了所有细节阅读成本极高试图“一次讲完”分层出子图主图保持精炼5.2 从“图难看”到“不知道哪里难看”的排查顺序有时候你知道图有问题但说不清问题在哪。我建议按下面的顺序排查信息结构层先检查图和文字说明是否一致。连线方向对不对节点是否都是必要信息有没有遗漏关键依赖信息结构错了后面怎么调样式都没用。视觉结构层再看分组和布局。同层级的模块是否对齐分组容器是否正确主路径是否占据了图面视觉中心如果主链路散落在图边角读者很难抓住重点。细节规范层最后看样式配色、字体、线型是否统一图例是否完整。样式问题最好解决但也最影响观感。这个排查顺序能帮你快速定位“问题出在哪一层”避免花大量时间调色却发现结构本身有问题。5.3 团队图规范落地怎么不招人烦规范再完整如果团队成员不遵守等于没有。我在几个团队里推行过 diagram-design 相关的图规范总结出三条落地经验第一小范围试点。不要一开始就要求全团队按规范执行先找一两个核心项目做试点把规范跑通产生几个高质量示例。第二模板先行。提供可直接复用的模板仓库包含语法文件、样式配置、导出脚本别人不用从零开始理解规范打开模板改内容就行。第三评审机制。技术评审里把图作为必审项评审人按规范逐项检查。开始时大家会觉得繁琐但坚持两三轮之后会形成肌肉记忆图的质量会明显上升。这三个经验是我觉得推行图规范最重要的三点。我个人在实际操作中最深的体会是diagram-design 真正难的不是工具或绘图技巧而是你能不能“先想清楚再动手”。如果连文字结构都没理清就去拖方框连线最终只会得到一张看起来像样、但经不起追问的图。反过来当你在文字层面把结构、关系、层次都梳理完毕绘图工具只是最后一公里的表达手段。建议下次拿到画图任务时先开一个文本文件写结构把受众、主链路、依赖关系都写明白再打开画布。这个过程坚持三个月你会发现自己画的图拿到任何评审会上都不怵。