最近在评审某跨平台系统架构时又看到一张让我头疼的部署图十几个服务方块堆在一起箭头纵横交错颜色至少用了八种图例却只字未提。提问环节大家确认的不是业务逻辑而是“这个箭头到底是调用还是依赖”。画图的人一脸委屈我明明画得很认真。问题恰恰出在这里——他把时间花在了“画”上而没有花在“设计”上。diagram-design 这件事往小了说是画图排版往大了说是信息结构设计。同样一张架构图、流程图或 ER 图设计过的版本和随手涂的版本信息传达效率能差一个数量级。这篇文章不聊某个具体工具的高级技巧而是想把我这些年做技术方案配图、写设计文档、搞团队评审时沉淀下来的方法整理出来怎么选图种、怎么定版式、怎么用颜色和文字、怎么把手绘图变成可维护的工程资产。适合做架构、写文档、带项目的开发者也包括被“画图”这件事折磨过的产品和测试同学。1. 为什么“画图”这件小事值得认真当作一门设计来做很多人觉得画图是技术方案里最不值一提的环节“思路对了就行”。但我在实际评审中反复遇到的情况是思路对不等于别人能看懂而看不懂的思路在讨论中就会被默认成“不对”。一张合格的图本质是一份契约契约写不清楚后续所有基于它的讨论都会失真。1.1 一幅好图等于省掉十场会议我统计过自己在两个项目里的沟通成本。某系统早期没有系统性地设计架构图每次有新成员加入就要拉一次散会逐块口头解释模块关系一次半小时起。后来花了半天时间把分层架构图、核心链路时序图、数据模型 ER 图各整理一版新成员上手速度明显加快很多问题自己看图就能解决。这不是玄学。人类处理视觉信息的速度远快于处理文字一张结构正确的图天然具备“并行解释”的能力。它能同时展示整体结构和局部细节让读者按自己的节奏消化。而文字说明是线性的读的人必须从头到尾看完才知道全貌。所以一幅好图省掉的其实是“重复解释”的时间这在跨团队协作时尤其值钱。1.2 大多数人画图的通病只“画”不“设计”什么叫只画不设计我总结为三个典型症状。第一没有明确“这张图给谁看”。给老板看的架构图和给开发看的部署图信息密度与抽象层级应该是完全不同的。给老板的核心是“系统边界、投入规模、风险点”给开发的核心是“模块划分、接口关系、部署依赖”。很多人一张图走天下结果谁都看不懂。第二没有视觉层级。所有方块等宽等高所有箭头同色同粗细信息没有主次。读者不知道先看哪里也不知道哪些是主干、哪些是支线。第三图种混用。把部署拓扑、调用关系和业务流程塞进同一张图里。读者满脑子都是问号这个方块是物理机还是逻辑服务这条线表示数据流还是控制流真正把 diagram-design 当设计做的人会先想清楚以上三件事再动手选工具。这一步做扎实了后面的一切都是执行问题。2. 先选对图种再看怎么画常见技术图的适用边界设计一张图的第一步不是打开画布而是回答一个问题我要表达的对象本质上属于哪种信息结构不同结构天然适合不同的图种强行互相代用往往事倍功半。2.1 架构图让系统结构一目了然的第一个工具架构图用于表达“系统由哪些部分组成彼此什么关系”是技术方案里出现频率最高的图。但很多人把架构图画成了“所有东西的叠加态”。我个人的习惯是架构图至少拆成三个视角。系统上下文图只画本系统、外部依赖和关键交互用于对齐边界。容器/模块图画系统内部的主要模块或服务以及它们之间的调用关系。部署图画各组件与实际运行环境物理机、容器、云资源的对应关系。这三者对应不同读者、不同阶段的决策。把三者混在一张图里是让我最头疼的坏习惯。比如有人把“Nginx 网关”和“用户认证模块”并排画在一起前者是部署层面的组件后者是逻辑层面的模块根本没有可比性。提示一个简单判断标准——如果图中存在“逻辑模块”和“物理节点”两类元素且没有通过不同容器或分层明确隔开这张图大概率会被误读。2.2 流程图与状态图逻辑梳理才是重点流程图画的是“一件事的处理路径”重点在于分支条件和异常路径。我用流程图时最关注三个检查点。一是单入口单出口。除了并行分支理想的主流程应当有一个明确的起点和一个明确的终点。出现多个散乱出口往往意味着处理逻辑本身没有收敛。二是分支条件必须完整。在某个判断节点上只画了“是”的分支而漏掉“否”是流程图最常见的残缺。漏掉的否分支通常就是线上出 bug 的地方。三是异常路径和主路径分开绘制或者用完全不同的线型标识。我见过不少流程图把异常处理直接画在主链路旁边结果看的人以为那也是正常路径。状态图则用于表达一个对象在其生命周期里的状态变化比如订单从创建、支付、发货到完成。画状态图的关键是先定义状态机的要素状态、事件、动作和迁移条件。这里经常出现的问题是状态与动作混淆——把“调用支付接口”当成一个状态实际上它是一个触发状态迁移的事件动作不是状态本身。2.3 时序图与 ER 图精确表达交互和数据关系时序图回答的是“在某个用例下各参与方按什么顺序做了什么”。它的核心约束是时间维度——垂直方向代表时间推进消息按从上到下的顺序排列。画时序图最容易犯的错误是顺序错乱消息在图上乱飞读者无法按阅读顺序还原调用链。解决方法是先写出参与方清单再列出消息序列最后才落笔排版。ER 图画的是数据实体及其关系重点是基数关系。一对多、多对多是数据建模的核心信息也是评审时最容易产生分歧的地方。我见过太多 ER 图只在两个实体之间画一条线不标基数等于啥也没说。必须用 1、* 或者 crows foot 符号明确标注。表格式的图种选择参考如下图种核心表达典型读者常见错误系统上下文图系统边界与外部交互产品、管理层把内部模块画进来容器/模块图内部模块与依赖开发、架构与非软件元素混排部署图组件与环境对应运维、开发缺少环境边界流程图处理路径与分支业务、开发漏画异常分支状态图生命周期变化开发、测试状态与动作混淆时序图消息顺序开发、测试消息排列顺序错乱ER 图实体与基数关系数据库、后端不标基数、不标主外键注意以上是按“主表达”划分的维度不反对图种嵌套比如在模块图里嵌入一张带时序的交互子图。但嵌套必须明确主次不能所有信息平铺、互相争抢注意力。3. 让读者一眼看懂的核心设计原则选对图种之后真正“设计”的部分才刚开始。设计不等于美化而是一系列有目的的取舍目的是让读者在最短时间内提取到最关键的信息。3.1 版式分层先有骨骼再有血肉我画图的固定顺序是先画骨骼——确定主体结构怎么排列再填充细节。具体来说分四步。第一步确定主方向。绝大多数人习惯从左到右阅读所以主流程尽量从左往右走分层结构则优先从上往下。方向定了整图的阅读顺序就有了。第二步做分组和留白。逻辑上属于同一层或者同一个域的元素用容器包起来或者通过留白隔开。物理上相近的元素读者会下意识认为是逻辑上相关的元素。分组不清的图阅读时会产生很多错误联想。第三步突出主干。对于核心链路通过更粗的线条、更大的区块或更深的颜色让它从背景中跳出来。边缘内容退到底层。没有主次就相当于什么都没说。第四步控制交叉。连线避免跨过大块图元尽量走外围或者用总线方式把多条线汇聚。这个目标是让视觉不被打断保持阅读的连续感。3.2 配色与一致性不是美术问题是信息问题配色在技术图里不是为了好看是为了编码信息。我使用的策略是颜色承载“层”或“类别”的语义并保持全局一致。比如在部署图里约定“绿色系外部依赖蓝色系自研服务灰色系基础设施”。这个约定在整个项目的所有文档里必须保持一致包括 PPT、接口文档、wiki 配图。这才叫颜色编码。如果每个文档各用各的配色颜色反而会变成噪音。另外不能只依赖颜色区分信息。总有人是色弱或打黑白打印版。所以重要信息必须有第二编码维度加边框、换线型、加文字标注。我在带团队时立过一条规矩如果去掉颜色后图的信息不完整说明这张图不合格。3.3 文字规范命名、缩写和注释的统一约定图里的文字虽然少却是信息传达的最关键载体。我有几条强制规范。一是节点用名词短语连线用动词短语。比如节点叫“订单服务”连线叫“创建订单”。反过来节点上写“创建订单”连线上写“订单服务”读者需要反复翻译。二是同一个对象在全项目中只有一个名字。不能在这个文档里叫“订单模块”在那个文档里叫“Order Service”在代码里又变成order-service。推荐在图里统一使用团队代码仓库中的模块名保证图与代码可互相索引。三是缩写必须给出图例或注释。首屏不解释用了“MB”表示消息总线就要在旁边图例注明。这是我在评审中反复强调的一点缩写不解释等于强迫读者记住一套无意义的符号体系。提示一条实用经验——把颜色图例、线型图例和缩写表固定放在图的右下角或左上角形成模板习惯。这样读图的人一旦遇到不确定的符号目光会自然去找图例而不是靠猜。4. 工具选型代码驱动还是拖拽画布聊完方法论说说工具。市面上的图工具大致分两类一类是拖拽画布型比如 Draw.io、某设计协作工具另一类是代码驱动型用文本描述图结构比如 PlantUML、Mermaid 这类标记语言。我自己两类都在用但使用场景完全不同。4.1 两派工具的适用场景对比拖拽画布的优势是即时、自由、视觉顺手适合头脑风暴、现场评审、快速白板。它的劣势是版本管理弱、难以 diff、多人协作容易互相覆盖。我见过团队用画布工具维护架构图改着改着出现了三份内容不同的 copy没人说得清哪份是权威版本。代码驱动的优势是图即代码天然支持文本 diff、版本仓库协作和自动化生成。劣势是有学习成本排版调整比较费劲复杂图调布局需要反复编译预览。维度拖拽画布型代码驱动型上手速度快即改即得需要学习标记语法版本管理差二进制文件难 diff好文本可直接 diff团队协作实时协作方便但易冲突基于仓库评审流程严谨自动化弱难联动文档强可嵌入 CI / 文档流水线复杂排版灵活手动可调自动化布局精细调整费劲典型场景方案讨论、临时沟通长期维护的权威架构文档4.2 我用 diagram-as-code 的实践我们现在把长期维护的架构图、ER 图全部迁移到代码驱动方案。对应的文件放在文档仓库里和项目代码一起走评审流程。改动一个模块依赖就是一次普通的 MRreviewer 能在 diff 里看到具体是哪个依赖关系变了而不是在一张图片里“好像哪里变了”。一个简单的例子用类 PlantUML 语法描述模块关系可能长这样startuml package 业务层 { [订单服务] [支付服务] } package 基础层 { [用户中心] [消息队列] } 订单服务 -- 消息队列 : 发送事件 支付服务 -- 用户中心 : 校验身份 支付服务 -- 订单服务 : 更新状态 enduml这段文本表达的内容和一张手绘架构图完全等价但好处是可 diff、可搜索、可生成而且源文件就是注释文档新成员看代码时能直接看到系统结构。4.3 团队协作中的版本管理问题代码驱动不等于万事大吉实践中最容易踩的坑是“一个人改了图没有同步说明”。因为图的源文件本质是代码必须遵循代码协作的规范每个图文件顶部写清楚“本图对应的系统版本/负责人”每次改动在 MR 描述里说明变更原因。我把这些和代码评审合在一起减少“图文档游离在体系之外”的情况。另一条经验是“一图一文件一文件一主题”。很多人习惯把系统的全套图塞进一个文本文件几屏几屏往下拉结果 diff 时根本分不清改了什么。我现在要求每个图独立文件命名时带上主题例如order-service-module.puml让文件名首先承担索引功能。5. 从需求到成品一张合格图的完整产出流程很多人的画图流程是“打开工具、凭感觉摆放、导出图片”。我的流程是工程化的分五步走。这套流程我用了很长时间稳定可靠。5.1 澄清读者和目的动手之前先回答两个问题这张图给谁看看完之后要支持什么判断如果是给管理层看系统建设进度那部署细节全部隐藏只留系统边界和关键依赖如果是给新入职的研发看那要保留服务列表和核心调用关系但可以让颜色和细节更丰富。我把这个阶段叫做“定义图的契约”。契约没定义清楚后面画得再漂亮也是自我满足。5.2 信息收集与结构化在画布之外先把图上需要的所有元素列出来。我会用一个简单的清单文本整理比如这样参与方用户端、网关、订单服务、支付服务、消息队列、外部支付平台 主链路用户端 - 网关 - 订单服务 - 支付服务 - 外部支付平台 依赖方订单服务依赖消息队列支付服务依赖用户中心 分组业务层订单、支付基础层用户中心、消息队列外部支付平台把这个清单整理清楚图就已经完成了一大半。大多数人画图慢不是排版慢而是没有先做结构化。结构化完成之后图上画什么、不画什么、边界在哪里一清二楚。5.3 绘制、评审、迭代结构化完成后再落到画布或代码里这时候我才会考虑布局、配色和文字细节。第一版草稿出来后我会做一件事桌面测试。找一位对项目不了解的同事只给图不给说明看他在 30 秒内能不能复述出图的核心信息。如果他能说出“订单服务调用支付服务中间经过网关并且依赖消息队列”这张图就合格了。如果他说的是“这里有很多方块和箭头我没太看懂”那就得回去改版式或减信息。迭代两三轮之后图才真正具备“可发布”的状态。提示30 秒原则是我自己定的一把尺子。技术图是给别人看的不是给自己看的。自己看每一张都清晰只有陌生的读者能在 30 秒内抓到重点才算画对了。6. 那些年踩过的坑常见错误与修正方法方法讲了不少但真正让人成长的是踩坑经历。我挑几个最有代表性的坑连同修正方法一起整理出来。6.1 信息过载与“一张图走天下”早期给某项目画架构图时为了显得全面我把服务列表、数据库表、消息队列、定时任务、甚至是缓存 key 的设计都放进了同一张图。结果评审时没人讨论架构全在问“这几个参数为什么画上去”。这就是典型的信息过载。修正方法是拆分视图总览图只留系统边界、主要模块和核心链路每个模块的细节用单独的图表达或者直接指向代码文档。我后来给自己定了一条规则如果一张图里超过 15 个主节点就必须拆分。“一张图走天下”不是能力是偷懒。6.2 时序不对与边界不清画时序图时我发现团队里很容易出现消息顺序凭“感觉”乱排的情况。后来我把消息序列先以纯文本形式写出来按序号排列好再翻译成时序图。这个步骤有效避免了“画图时才想流程”带来的顺序错乱。边界不清则是另一种高频问题。比如系统上下文图把内部模块画了出来导致外部读者误认为这是系统全景。修正手段是在图上用显眼的分区容器标明内外容器边界就是信任边界这条线画得越明确误读越少。6.3 图与代码脱节最后一个大坑是图和代码脱节。画完架构图、写完代码之后图就成了挂在 wiki 上的“展品”三个月后代码改了七八轮图还停留在最初版。废弃的图比没有图更有害因为它会引导新人走到错误的方向上。我目前的处理方式是把图形源文件放进文档仓库与代码一起走 MR 流程任何代码变更影响结构必须在同一次变更里更新图。在 CI 里加一步构建任务把代码驱动图形生成并发布到内部文档站点图形一旦不能编译就会告警。对无法自动检查的拖拽图至少在文档里标注维护人和“最后更新日期”超过半年未更新的图默认视为废弃。这个机制不能保证图永远新鲜但至少让“图过期”这件事从不会在代码评审时被主动提起变为每次变更都会被顺带确认的例行动作。我在实际使用中形成的个人体会是diagram-design 的功夫有大约一半花在动手之前。搞清楚读者、目的和信息边界比调三个像素重要得多。另一个很实用的小技巧是给自己建一个图例模板库——统一的颜色语义、线型规则和缩写表直接复用时间长了整个团队的图都会长成一个风格沟通成本会肉眼可见地降下来。画图这件事不追求惊艳追求的是不让读者产生误解能把复杂讲清楚本身就是一种体面。