技术图表设计实战：从工具选型到交付检查的完整指南

1. 评审会上翻车之后图表设计真正要解决的是一眼看懂今年年初的一次架构评审我拿着一张自己画了两小时的系统部署图上台。图里画了十几个服务节点、五六条消息队列、三条虚线表示的异步链路还贴心地给每个服务框加了内部依赖的小字。讲完前两页技术总监打断我你直接说这张图想让我先看哪里我愣住了。那一瞬间我意识到我画的不是图是一张信息堆放区。后来我把这个教训总结成一句话diagram-design 的核心不是把东西画出来而是让看的人用最短的时间找到他需要的信息。很多人包括当时的我画图时会不自觉地站在表达者视角——我懂这个系统所以我觉得每个细节都很重要。但看图的人往往是带着问题来的这个流程哪里会失败新服务部署在哪个网段订单状态机有哪些合法迁移如果图不能快速回答这些问题那它和一段没人读的文档没有区别。真正让我转变的是一次小小的实验。我把同样一个订单超时关单流程分别用把所有异常处理画在一张图里和只画主流程 单独一页异常分支两种方式给两位新同事看问他们30 秒后描述这个流程。前一位同事只说出好像有很多判断后一位同事直接说出了超时之后先发消息再关单关单失败会有补偿。同一个系统两种图信息传递效率完全不同。从那时候起我开始把 diagram-design 当作一门需要刻意练习的技艺而不是一个随手就能完成的操作。这篇内容不是软件操作教程也不是某个具体工具的说明书。我想分享的是一整套我自己磨合了两年、在真实项目里反复验证过的图表设计工作流从工具选型、各类高频图表的画法拆解到颜色命名规范、交付前的检查项。适合所有需要画图表达想法的人——后端工程师、前端工程师、产品经理、架构师、技术作者甚至做汇报材料时总被领导说看不清重点的职场人。如果你也经历过画图两小时讲解十分钟提问没人懂的尴尬这篇文章应该能帮到你。2. 先选型再动手图表工具与表达方式怎么匹配2.1 主流工具的定位差异不是谁更强是谁更匹配很多人在工具选择上容易走极端要么一直在用最熟悉的那一个不管场景合不合适要么每隔半年换一次新工具导致团队协作成本居高不下。我用过的工具不算少这里先给一个基于我自身经验的选型参考工具最佳使用场景上手成本协作方式我踩过的坑Excalidraw快速画草图、接口梳理、头脑风暴极低在线实时协作手写字体风格偏随意复杂架构图会显得不够严谨diagrams.netdraw.io技术架构图、网络拓扑、UML低本地文件 Git 管理默认形状库很乱需要花时间自定义模板Figma产品原型图、用户流程图、UI 组件类图中等在线协作最强画逻辑图时容易忍不住去抠像素浪费时间PlantUML代码生成的 UML、时序图低写文本适合文档嵌入复杂的布局控制很痛苦样式定制有局限MermaidMarkdown 内嵌的流程图、时序图、状态图极低天然适合代码库复杂分支会散成一团布局不可控OmniGrafflemacOS 上高保真架构图、复杂版式中等本地为主贵而且 Windows 同事打不开源文件不过这上面只是偏向不是规定。我自己目前的主力组合是快速讨论用 Excalidraw入库文档用 Mermaid 或 PlantUML架构方案评审用 draw.io涉及产品交互用 Figma。每个工具我都给它安排了一个明确的角色这样在选择时就不用纠结了。2.2 按场景选工具的底层逻辑维护成本决定一切选工具的时候很多人的第一直觉是哪个画出来更好看但实际项目里更应该问的是这张图的生命周期有多长如果它是一次性讨论用的两分钟后就要扔掉那用 Excalidraw 快速涂改完全没问题。可如果它是系统设计文档的一部分要在接下来一两年里持续被维护那么能不能方便地更新、能不能被 diff、能不能让新同事快速改就成了决定性因素。举例来说我们有一个内部服务治理项目的架构图最初是用白板工具画的画完很漂亮但三个月后服务从 12 个变成了 19 个还拆分出了两个新网关那张图就没人敢动了——因为原图作者离职其他人不知道怎么在复杂画布里找到对应模块。后来我们把架构图迁到了 draw.io并且用 Git 管理源文件每次变更都走 MRMerge Request评审图里的每个变更都和代码变更绑定在一起。这个迁移动作看似只是换了个工具实际上是把图从一次性展品变成了活文档。我的建议是先问这张图要被改几次再选工具。要改很多次的图优先选文本化、可版本化的方案Mermaid、PlantUML、draw.io 源文件只是为了让讨论更清晰的图用画起来最快的方案就行没必要在工具上消耗心力。2.3 建立属于自己的组件库工具之外效率翻倍的关键不管用哪个工具我都很建议花两个下午时间按自己团队的业务特点搭一套组件库。什么意思呢比如我的团队经常画订单相关的流程我会在 draw.io 里固定一组形状黄色的系统外部依赖框、蓝色的内部服务框、绿色的数据库/存储框、橙色的人工操作框。下次画图时直接从自己的图库里拖不需要每次重新选颜色、调字号。在 Excalidraw 里也一样。这个工具默认的图形虽然少但支持把常用组合保存为库。我把消息队列定时任务外部 API 网关缓存这些常见的元素都做成了库文件画图速度至少快了三分之一。很多画图慢的人慢的不是思考而是在反复调整同一个形状的格式上。组建一次组件库后面所有图都受益。3. 四类高频图表的实战拆解从画框到讲清逻辑3.1 业务流程图先写步骤清单再画分支业务流程是大家画得最多也画得最容易乱的图。最常见的坑是一张图画了主流程、异常流程、补偿流程、定时任务兜底流程看起来非常全面实际上阅读者根本分不清哪条线是主干。我现在画流程图的顺序和大多数人不太一样我先在文字里把步骤一条条写出来全部确认之后才开画。比如画一个用户申请退款的流程我会先列用户提交退款申请系统校验订单状态是否已完成、是否已超过退款时限如果校验失败返回原因并结束如果校验通过调支付网关发起原路退款支付网关返回成功 / 失败成功则更新订单状态为已退款失败则进入人工审核队列文字确认后画图就只剩排版了。这样做还有一个额外的好处先写文字清单时很容易发现自己漏了某个分支。比如退款失败之后需不需要通知用户人工审核结果怎么回到主流程这些在文字阶段就暴露出来的问题比画到一半再改要省力得多。画的时候我还会遵守一条三色原则正常路径用一种颜色异常分支用一种颜色定时/异步补偿用一种颜色。并且默认把主流程画成自上而下的直线异常分支放在右侧。这样读者第一眼看到的是那条垂直主线不会被旁路带偏。3.2 系统架构图分层思维与边界表达系统架构图是 diagram-design 里最容易被画得像拓扑图的类型。很多人把服务名往画布上一摆线上连上线就宣布这是架构图。但一张合格的架构图核心是三个问题系统分几层每一层的边界在哪层与层之间怎么通信我的画法是水平分层 垂直泳道的混合结构。水平方向把基础设施层、应用层、网关层、客户端层从上到下或从下到上展开每一层用一个大的背景色块包起来。垂直方向则用泳道区分不同业务域比如订单域、支付域、用户域这样既能看出整体层次也能看出每个业务域内有哪些服务。关于边界的表达我特别想提醒一点能用层表达关系就不要用线表达关系。两个服务之间的具体依赖是容易过时的信息今天 A 调 B下周可能就加了一个 C。如果每一条调用关系都要画成线图会越改越密最后变成一团意大利面。更稳妥的方式是在分层图中只表达这一层允许调用下一层的规则具体到服务间的调用细节用一张独立的时序图去表达。3.3 时序图谁和谁在什么时刻说了什么时序图是我觉得最反直觉的一种图。它的核心元素是纵向的时间轴但大多数新手画时序图时想的是系统怎么工作而不是对象之间按什么顺序发了什么消息。画时序图之前我会先确定三件事参与者有哪几个每条消息的触发条件是什么每条消息是同步还是异步参与者不是类的数量而是能独立收发消息的角色。比如一个创建订单的时序图参与者至少是客户端、订单服务、库存服务、支付服务、消息队列。如果把订单服务内部的数据库操作也当成一个参与者图会迅速变得臃肿。有一个我经常提醒自己的小技巧消息的命名要像软件工程里的方法名一样规范动词开头说清楚在干什么。比如创建订单请求和POST /api/orders这两种写法里我倾向于后者因为它更精确——前者既不知道是接口还是内部方法也不知道是同步还是异步。给消息命名时稍微多想一下看图的人就能少猜很多。异步消息的表示也值得注意。很多人用虚线箭头画所有异步调用但没有标明回调或消息队列的 topic。我建议在虚线箭头上直接标注队列名或事件名例如emit: OrderCreatedEvent这样阅读者不需要再翻代码就能知道消息走的是什么通道。3.4 ER 图 / 领域模型图字段不是重点关系才是画 ER 图实体关系图和领域模型图时最容易犯的错是把表结构直接平移画出来。一个订单表有 30 个字段画图时全列出来读者盯着字段列表反而看不出订单和用户、订单和商品之间的关系。我的做法是实体框里只保留三个要素——实体名、关键标识、与当前讨论强相关的 2~3 个字段。剩下的字段要么省去要么放在附录。图的价值是呈现关系不是呈现表结构。关系线是 ER 图真正的主角。我会用**韦氏线crows foot notation**表示一对多、多对多而不是简单地画一条线然后在旁边写一小段文字。人眼对图形的感知速度远快于文字如果一对多关系还要靠读注释才能理解那这张图就不够好。另外关系的动词最好也标在线上如提交包含属于这会让图的语义清楚很多尤其是多个实体关系相似的时候。4. 把设计规范固定下来颜色、布局、命名与版式4.1 颜色语义化让颜色替文字说话在图表设计里颜色最大的价值是形成条件反射。看到蓝色就知道是内部服务看到红色就知道是异常/告警路径看到灰色就知道是暂时不展开的辅助信息。一旦建立起这种约定看图的人就不用每次去读框里的文字了。但颜色用不好也会帮倒忙。常见的错误有几种一是颜色种类太多一张图超过 6 种颜色读者会开始怀疑这个颜色是不是有特殊含义注意力会被分散二是部分颜色相近比如深蓝和深绿在投影仪上几乎无法区分三是只依赖颜色传达信息不考虑色盲读者。我现在的规范是主色不超过 4 种 中性色灰白黑不限。主色分别对应核心服务、外部依赖、数据存储、人工流程。色盲友好的角度我会避免红绿搭配而是用红蓝搭配并在重要节点同时加形状或线型作为第二通道。比如异常路径不仅用红色还配上X形标记或者虚线边框。4.2 三分构图与视觉动线引导读者按你的顺序看画布不是无限大的白纸它有边界、有视觉重心、有阅读顺序。很多图之所以看不出重点不是因为信息不够而是排版没有动线读者的视线像无头苍蝇一样四处跳跃。我的排版手法借鉴了平面设计里的三分法把画布想象成九宫格重要内容放在左上和中上区域次要内容放在右侧和底部。中文阅读习惯是从左到右、从上到下所以主流程的起点应该放在左上角然后顺着一个大致的方向铺开而不是画成从正中间开始向四面发散的结构。另外每一张图都应该有且只有一个视觉锚点就是那个最核心的节点或流程。这个锚点要么在左上角要么在正中央并且尺寸可以比其他节点略大一圈。其他节点再重要也不能抢它的视觉权重。做到这一点之后图会立刻显得有主次。4.3 命名与编号体系一张图就是一份索引当图表数量多起来之后布局、颜色和经验会影响看图效率的瓶颈反而会变成命名。如果你的团队所有图都叫架构图流程图或未命名文件那维护和引用就是一场灾难。我会坚持一套简单的命名规范前缀-模块/业务域-图类型-版本。例如ARCH-订单中心-部署架构-v2、FLOW-退款异常-活动图-v1。图片内涉及可被引用的节点比如服务、接口、数据表则使用统一的编号例如订单服务SVC-ORD-001订单表TBL-ORD-001。有了编号之后不论是文档引用还是口头沟通都只需要说编号不需要含糊地就是那个右边中间的框。这套命名体系一开始有点麻烦但项目规模变大之后收益非常明显。因为图已经变成了团队沟通的索引而不再是一个孤立的展示品。5. 实测中反复踩过的坑交付前的检查项清单5.1 信息重叠与跨层连线图越大越难维护的根因画图时有一个非常普遍的心理总觉得这张图少画了点什么于是不断往里面加信息。加到最后图变大了信息完整了但也不再有人愿意看了。这就是我为期半年最深刻的教训一张图的有效信息量是有限的超过了阈值阅读者就会放弃理解。我现在的原则是一图一主题。如果一张图需要表达的内容超过 7 个核心节点或 5 个主要分支我就会认真考虑把它拆成多张图。拆分的维度可以是按流程阶段拆前端流程 / 后端流程 / 异常补偿、按抽象层次拆整体架构 / 模块细节 / 关键时序、按角色拆买家视角 / 卖家视角 / 运营视角。跨层连线的处理也一样。画架构图时最忌讳的是为了表达某个特殊情况直接从最底层拉一条线连到最顶层。这会让读者觉得系统没有边界到处都有隐式依赖。正确的做法是如果确实存在跨层调用单独画一张小图来说明这个特例而不是在总图上拉一条破坏整体视觉的长线。5.2 文件的版本管理图源文件比导出图更重要很多人交付图表时只给一张 PNG却把源文件留在自己电脑里。一旦图需要更新其他人只能照着图片重新画一张这本质上是在浪费整个团队的时间。我们现在所有进入正式文档的图都必须同时提交源文件和导出文件。源文件放在 Git 仓库里和代码一起走评审。Mermaid 和 PlantUML 这类文本化工具天然支持 diff用 Git 管理起来非常舒服draw.io 和 Figma 这类可视化工具则通过.drawio.xml或法律依赖文件.fig保存Git 也能版本化只是 diff 可读性稍差一些。你可能觉得这只是团队流程问题和图表设计本身没关系。但我的亲身体会正相反版本管理直接决定了你会用多大心力去保证图的质量。如果你的图源文件永远不会被第二次打开那你肯定不会花心思去把它画得易维护只有当你知道这张图会持续被 review、被修改你才会主动去优化布局、命名和层次。工具和流程会反向塑造人的习惯这是一件很奇妙的事。5.3 交付前必查的 7 个问题每次发布前过一遍在把图发给别人或贴进文档之前我会强制自己过一遍下面这份检查清单。它不复杂但每次都能拦下至少一个问题这张图的主题是什么如果只能说这是 XX 系统架构图而说不出一句我想让读者重点注意什么那这张图大概率还需要拆或改。主流程/主结构是否在视觉上是第一眼注意到的让一个第一次看图的人花 5 秒描述他看到了什么如果他的描述和你想要传达的重点不一致就是排版有问题。有没有纯装饰性的内容有些渐变、阴影、剪贴画元素除了好看没有任何信息价值反而会增加视觉噪音。文字能不能被清晰识别字体小于 12px 的文本在不同分辨率屏幕或打印出来后基本不可读。放大图片后所有文字仍然清晰这是底线。同一个含义是否只用同一种表达比如蓝色框一会儿代表服务一会儿又代表外部系统读者一定会混乱。全局统一术语和颜色语义。跨引用是否一致图里提到的服务名、接口名、队列名和代码里是否一致如果不一致读者会直接对着图踩坑。是否有边界说明这张图画到哪个范围为止不含哪些内容给图加一个简短的说明文字或图例能避免很多这图怎么缺了 XX的质疑。这条检查清单现在已经成为我们团队评审设计文档时的标准流程。如果你觉得每次画完图自查太麻烦也可以降低频率只在进入正式评审或对外发布前过一遍。但相信我检查出来的问题远比花掉的五分钟值钱。我自己现在画图的心态已经从赶紧把脑子里的想法倒出来变成了让读到这张图的人真正省时间。这个转变花了我将近两年的时间中间画废过几十张图踩过无数个上面提到的坑。如果你刚开始认真对待 diagram-design不用急着追求一步到位。先把工具选顺手把主色和命名规范定下来再按清单过几轮你的图就会开始变得不一样。