有一次评审会上同事打开一张系统架构图我看了十秒钟就放弃了几十个矩形框挤成一团箭头从右下角绕到左上角不同颜色混在一起图例还漏画了消息队列。评审现场冷场了好一会儿最后主持人说要不我们直接打开代码仓库看吧。这不是画图水平的问题是 diagram-design 出了问题。我在研发和技术文档这块摸爬滚打了多年越来越觉得diagram-design 不只是美术工种也不只是 UML 复习课而是一套“用图形快速对齐认知”的工程方法。这篇文章想聊的不是某个绘图软件的操作技巧而是我在真实项目里沉淀下来的一套 diagram 设计方法从场景选型、布局策略、连线语义到工具链与评审维护。适合经常要画系统架构图、业务流程图、时序图和数据库关系图的开发者、架构师、技术负责人参考。1. diagram-design 不是画图是替读者做决策1.1 为什么“能看懂”比“画得好看”重要很多人以为 diagram-design 的核心是“美观”于是把大量时间花在选配色、调对齐、找图标上。这些当然有价值但只要读者看三遍还是不知道系统怎么流转这张图本质上就是无效资产。我见过不少视觉效果很好、实际上没人能复述核心链路的图原因很简单作图的人默认读者和自己一样熟悉内部结构省略了太多前置信息。在研发语境里diagram 唯一的存在理由是“降低认知成本”。一张好图能让人在三十秒内回答三个问题这个系统有哪些部件数据或调用从哪里来、到哪里去哪里是核心路径如果一个读者需要逐个对照代码注释才能看懂图就没有起到中介作用画它只是在自欺欺人。打个比方地图的价值不在配色多好而在你能否快速找到“现在在哪”和“要去哪”。diagram-design 也是同样逻辑节点就是地标连线就是道路图例就是图例说明。如果一张地图把高速公路和乡间小路画成一样的线型导航体验一定糟糕透顶架构图也是同理。1.2 一张图只能回答一个核心问题我在评审时经常问一个问题“这张图要说服谁做什么决定”同样一个订单系统画给产品看和画给新员工看内容可以截然不同。前者需要明确业务状态流和超时节点后者更需要环境依赖、接口边界和部署拓扑。把多个目的硬塞进一张图结果往往是每个目的都没达到。所以动手之前先写一句话定义图的目标例如“这张图用来解释交易主链路在高峰期的超时降级路径”。这句话看起来很基础但它决定了后续所有的取舍节点要不要展开、依赖要不要画全、异常分支要不要上色、文字能不能当注释。没有它图就会变成信息的堆砌而不是决策的辅助。这也是我在项目里反复强调的“一图一问”原则。如果画着画着发现需要引入第二条主链路我通常不会把它们画在同一张图里而是拆成两张图并互相引用。想表达降级就专注于降级想表达部署拓扑就专注部署拓扑。混在一起只会让读者不知道该从哪个维度进入。2. 从场景倒推图型流程图、架构图、时序图该选谁2.1 用问题的类型决定视图类型选图表类型是 diagram-design 的第一道分岔口。我习惯用一个相对简单的判断方法读者是想理解“顺序”还是理解“结构”还是理解“交互”。下面这张表是我自己总结的基本覆盖了研发日常九成以上的场景。读者想知道什么推荐视图常见误区事情按什么步骤发生、哪些条件下会终止流程图flowchart把所有异常分支全画进去主线被淹没系统由哪些模块构成、模块层级和依赖关系架构分层图 / C4 container 图把不同层级的组件放在同一平面一次请求经过哪些参与方、消息在时间轴上的先后时序图把结构关系和行为关系混在一张图数据实体有哪些、实体之间关系是什么ER 图字段列得太多关系反而不清晰这三类不能混着画。最常见的问题是有人想画架构图结果把异步回调的时序细节也画进同一张图里导致一张图同时承担结构表达和时间表达读者不知道先看哪条维度。遇到这种情况我会建议他拆开架构图表达格局时序图表达过程中间用接口名互相引用。2.2 抽象层级要匹配读者的技术背景同一套系统画给一线开发看可以把某个网关的限流算法画成带参数的名词框画给管理层看就应该把网关收敛成“接入层”一个节点不需要展开。这个“选哪一层展开”的判断才是 diagram-design 里真正考验经验的部分。我习惯画之前先写两笔目标读者对系统的熟悉程度以及他们要作出的决策颗粒度。如果读者只关心“系统是否支撑万级并发”图中就不该出现二十个微服务名字如果读者是要排查超时问题那就必须把线程池和依赖服务画出来。否则图看起来“信息很全”实际使用价值极低。抽象层级还要考虑维护成本。每次展开一个节点就多了一个需要持续维护的信息点。我会问自己这个展开的信息源是否稳定、是否有文档可查、是否有专人负责更新。如果三个条件里有一个不满足我宁可先不展开等需要时再补。少而准的信息远胜多而错的信息。3. 从零搭一张不脏的系统图布局、分层和连线3.1 先定主链再补分支布局的优先级画图最忌讳从头开始一边想一边放框。我现在的做法是先把主链路上的五到八个关键节点写下来通常是“入口 - 网关 - 核心服务 - 数据存储 - 出口通知”把这些节点当成图的骨架先把它们按主方向排好再围绕主链补分支。主方向一般选自上而下或者自左向右这两种方向最符合阅读习惯。混用方向不是不行但一定要有明确理由比如“回退路径为了避开某组节点所以折返”否则很容易造成视觉灾难。我见过一张图里既有上下走向、又有左右走向、还有斜向穿越读者视线被拽得满天飞根本没有重点。布置完主链后我会把分支节点逐个挂上去。这里有个关键判断分支是“必须出现”还是“补充说明”。如果分支只是次要接口我会把它压缩成一行注释放在图底部而不是拖一条长线横跨整个版面。控制分支数量是图能不能保持清爽的分水岭。3.2 容器边界与分层别把所有框放在同一层很多架构图不好读是因为所有组件全挤在一个平面上看起来像一张菜单。diagram-design 里很关键的一步是给节点分组哪些属于接入层哪些属于业务层哪些属于基础设施。分组可以用大框、泳道、或者不同的底色区域来表示目的就是让读者先建立“层”的认知再进入“点”的细节。我自己画系统图时规定一个原则每个区域内部只放同一层级的组件跨区域连线必须说明依赖方向。比如“前端服务”区域里不能混入“缓存集群”的节点哪怕它们部署在同一台机器上。否则读者很难判断某个节点到底属于服务还是中间件理解成本立刻翻倍。分层也不是越细越好。我曾经见过把一张架构图分成十二层、每层两个节点的极端案例效果和没分层几乎没有区别。层级的数量应该控制在读者能一眼记下的范围四到六层是比较舒服的区间。超过这个数我会开始考虑是不是画得太碎需要合并概念层。3.3 连线的语义箭头、颜色和交叉控制连线是图里最容易翻车的地方。箭头方向混乱读者会分不清是“调用”还是“返回”颜色用得多读者会以为每个颜色都有含义但实际上只是作图者随机选的。我的建议是一张图里最多出现三到四种连线语义且每种都要稳定复用。线型语义使用场景实线箭头同步调用服务 A 调用服务 B 的 HTTP 接口虚线箭头异步/事件发布消息到消息队列或回调通知粗线主链路核心请求路径读者应最先关注灰色细线旁路巡检、日志、管理类低频依赖颜色同理一张图主体颜色不超过四种每种颜色都要在图例中写清楚不要用颜色做装饰。我见过有人把每个微服务用不同颜色表示最终效果像跑马灯读者根本记不住对应关系。颜色应该是“分层/分区”的辅助而不是信息主体。连线交叉无法完全避免但可以通过调整节点顺序减少。如果一条线要跨过整张图才能连到目标大概率是这个节点的位置摆错了。真实项目里常见做法是允许“断线续接”一条跨区域的连线上标注接口名或消息主题名就能避免满图拉线。这样既保留跨模块依赖的信息又不会牺牲整体可读性。4. 工具链选型文本即代码和图形编辑器怎么互补4.1 为什么我偏向文本化图源我接触过三类工具图形编辑器拖拽即所得、白板类更适合自由讨论、文本即代码用 DSL 描述图结构再渲染成图。现在团队里正式文档我基本都走文本化图源。原因很直接可 diff、可 review、可追溯。一张架构图如果能用 DSL 表达就可以像代码一样进版本库改动可以在代码评审里看到而不是在图片上靠肉眼对比。这对多人协作特别重要A 同学加了一个组件B 同学能清楚地看到改动发生在哪条链路上不会出现“图上已经改了、代码里没有”的错位情况。当然白板类工具在前期讨论阶段依然有用。需求还在变化、连线还在争辩的时候白板的自由度是最高的。我的习惯是讨论用白板定稿用文本图中间用截图作为过程记录。这个转换动作看似麻烦但能强制团队把“想法”沉淀成“图纸”。4.2 协作中的版本管理与审阅闭环文本化图源带来的另一个好处是可以把图纳入审阅流程。我们团队的约定是图形文件禁止直接放在共享网盘里作为最终文档必须有对应的文本源文件放在仓库里生成的 PNG 或 SVG 只是构建产物。审阅流程大致是改 DSL - 生成预览 - 在合并请求里附上改动说明 - 评审人看图确认 - 合并并更新文档站点。看起来多了一步但长期省下来的共识成本非常明显。以前图形文件各改各的最后根本不知道哪版是对的现在图源和历史记录都在谁改的、为什么改一查便知。这个流程还有个意外收获新人更容易上手维护了。面对一张图如果只有一个图片文件新人想改只能从零重画如果有一份 DSL 源文件他能顺着已有结构做小改动心理门槛低很多。diagram-design 要实操好工具链的“可修改性”和“可追踪性”比画出来那一刻的效果更重要。4.3 一个可落地的 diagram-as-code 目录规范规范并不复杂核心是把“图”当“代码”管理。我们仓库里通常放一个docs/diagrams目录每个图一个子目录里面包含三样东西图源文件、生成的图像、README 说明。README 里写明这张图解决什么问题、读者是谁、最近一次更新时间以及关联文档链接。目录结构大概长这样docs/ diagrams/ trade-core-flow-mainpath/ source.dsl preview.png README.md trade-deploy-topology/ source.dsl preview.png README.md文件名也要有命名约束不要叫“最终版”“新新最终版”这类没有信息量的名字。我建议按“系统名-图类型-用途”来命名例如trade-core-flow-mainpath一看就能猜到内容范围。这样归档、检索、复用才有基础。5. 四个真实踩坑案例与排查链路5.1 案例一层级混乱导致架构图被误读一次跨团队评审对方展示的服务拓扑里把网关、业务服务、数据库和缓存节点全部放在同一层只靠不同底色区分而且没有图例。评审中我追问“这个缓存到底是业务服务自带的还是平台统一的”对方自己也绕了半天。这个场景说明缺少分组边界时读者只能靠猜。排查链路其实是通用的先让读者复述“你从图里读到的部署关系”再对照“真实部署关系”找出分歧点最后回到图上补分组和线型。不能试图靠和读者反复口头解释来弥补图的缺陷图自己说不清的地方永远是 bug得改图而不是改口才。那次评审结束后我们把图重新组织成“接入层 / 业务层 / 数据层”三块缓存并进数据层网关收进接入层所有跨层依赖统一画成实线箭头加接口名。重画之后同样的读者只需要十秒就能说清每个组件的位置误读自然消失。5.2 案例二自动布局把关键链路挤成了毛线团有一段时间我用自动布局节点一多就乱主链被挤到图片边缘长长的跨区域连线和完全无关的分支纠缠在一起。后来我接受了一个事实自动布局只适合草稿和探索正式文档必须手动控制节点顺序和方向。拿文本类绘图工具举例我用显式约束把主链路节点逐个固定到期望的相对位置分支节点再围绕主链展开。必要时把无关子图放进独立容器强制它们不干扰主路径。这个过程会花一点时间但换来的是读者读取图的成本大幅下降。有同事问我为什么不能接受“有点乱但省时间”的图。我的回答是省的是作图者的时间烧的是所有读者未来的时间。文档是复用资产不是一次性交付物省在作图上的每一分钟都会在评审、答疑、排障时十倍还回来。5.3 案例三省略图例后新成员连续问了三周有一张数据同步图我一直觉得“虚线表示异步、点线表示失败重试”是不言自明的。结果新成员入职后连续问了三周“这里为什么用虚线是网络虚拟连接吗”。我才意识到图例不是给专家看的而是给所有第一次看到这张图的人看的。从那之后我强制要求所有正式图必须带图例并且图例和正文放在同一屏不能放在文档附录里。这个小改动让新人的提问数量肉眼可见地变少了。后来我把这条写进团队的文档规范凡是提交到文档站点的图评审时第一眼先看图例是否完整。图例本身也有设计要求术语要和代码注释对应不要出现图上写“MQ”、代码里叫“msg_bus”这类割裂。命名统一这件事越早做越省心。diagram-design 画到最后拼的是命名的一致性和上下文连贯性而不是能不能找到更漂亮的图标。5.4 案例四图比代码老文档反而成了误导源最隐蔽的坑是图长期没人维护系统早就改了图还停留在旧结构结果新人照着图去排查问题白白浪费半天。我后来规定任何架构图的 README 里必须写上“验证标记”每次代码评审中如果涉及该图描述的系统变动提交者必须同步修改图源文件否则合并请求不能通过。这一步看起来严格实际上是在用流程保护图的时效性。图一旦和代码绑定起来维护责任就从“文档负责人”变成了“改代码的人”更不容易过期。如果确实没有精力更新我宁可把图标成“草稿/已废弃”也不让它和正式图混在一起。排查这个坑的一条经验是当有人拿着图来问你“这里为什么这样”而你却要翻代码才能回答时说明图已经过时了。正确的做法是当场同步图纸问得多了维护频率自然上来了。6. 让 diagram 成为团队的长期资产评审、演进与归档6.1 图也需要评审清单评审图的时候我通常对照一张清单核心问题是否明确、主链是否一眼可见、分组是否帮助理解、连线语义是否一致、图例是否完整、抽象层级是否符合读者、是否有过期风险。这个清单不复杂但每次都能筛出问题。检查项通过标准目标明确能一句话说出这张图要回答什么问题主链可见一眼能找到核心路径不被分支淹没分组合理同层组件在同一容器内跨层标注方向连线一致线型和颜色语义全图统一有图例层级适当展开程度与读者背景匹配时效可靠README 有更新时间和代码关联可查评审的时候还有个技巧不要只让懂系统的人看也要让“半个外行”看。外行能看懂才是真好懂。专家往往能自动脑补图上缺失的信息掩盖 diagram 本身的设计缺陷。6.2 把决策写进图里架构记录与图源绑定光有图不够图背后“为什么这么画、为什么这么设计”的决策记录也同样重要。我们在docs/decisions里放轻量的架构决策记录每条和对应的图相互引用。比如某个模块为何采用最终一致性而不是强一致在图上只体现“异步消息”而原因写进决策记录。读者既能看图知道现状又能追溯决策。一条决策记录不需要很长写清三件事就够了背景是什么、备选方案有哪些、为什么选择当前方案。然后写上“关联图trade-core-flow-mainpath”这类链接。这样图不再是孤立的图片而是决策链路上的一环。这个做法的价值在于几个月后再看同一张图既知道系统长什么样也知道为什么长成这样。否则很容易出现“新架构师看旧图不理解历史选择直接推翻重来”的浪费。diagram-design 的最高目标不是画出当下正确而是留下可持续演进的理解基线。6.3 归档与检索垃圾图比没有图更危险最后一点也是我强烈想说的没有图大家知道缺文档有一堆过时、矛盾、误导的图大家反而对文档失去信任。如果没精力维护一张图就不要创建它。归档时宁可标注“草稿/已废弃”也不能让它混在正式目录里。检索也是一门学问。图多了之后我会在每个图的 README 里加标签比如“支付”“高可用”“数据同步”。搜索时按标签和文件名双路径找基本不会迷路。至于那些临时画的、只在某次会议用过的脑图要么转化为正式图要么直接删除不留中间态。我见过最混乱的情况是 docs 目录里堆了几百张图片没人知道哪张代表当前系统也没人敢删。后来花了两个迭代清理先按图源化、再按目录规范重排、最后把无法溯源的全部移到 archive 区。清理完之后团队对文档的信任感恢复了新人上手速度也快了不少。最后再分享一个我自己用了很久的小习惯每次画完一张核心图我会找一位完全不熟悉该系统的人让他只看图、不看文档然后向我复述系统的主链路。他能在一分钟内说清楚“从哪里进来、经过什么、到哪里去”这张图才算合格只要他卡住问题几乎都出在图而不是人身上。这个测试成本极低但比任何评审都诚实。diagram-design 说到底就是一次次把复杂的系统决策翻译成别人能快速理解的图形语言这个功夫值得每个做技术的朋友认真打磨。