diagram-design 这个标题我第一次看到的时候脑子里闪过的是一堆画了一半的架构图框是歪的线是弯的颜色五彩斑斓丢进文档里两年没人更新。做过技术文档的人都懂画图这件事门槛低到人人都会做好却难倒一群人。后来我在几次大项目里反复折腾图表才慢慢发现它不是一个“把节点摆好看”的技能而是信息组织、逻辑梳理、视觉表达三件事的集合。这篇内容我想把这一套沉淀下来的方法、工具和踩坑经验完整写出来给所有需要画系统架构图、业务流程图、数据流转图的开发者参考。1. 图表设计到底在解决什么问题1.1 一张烂图是怎么毁掉一次技术评审的有一次内部评审某个同事贴了一张流程图十几个节点挤在一页里箭头横七竖八有的线绕了大半个屏幕才到终点。评审主持人问了一句“主流程是哪条”现场沉默了几秒然后三个人同时指向三个不同的方向。最后大家花了二十分钟对着图猜逻辑原本该讨论的技术取舍根本没时间聊。这不是个例。我在很多团队里见过同样的现象图画了文档也写了但图没有承担起“让读者快速理解”的职责反而成了信息噪音。原因也很简单大多数人是按“我能画出什么”来画图而不是按“读者需要先看到什么”来画图。节点是想到一个加一个位置是随便拖一拖颜色是心情好就标一个。等节点超过十个线超过十五条这张图就基本失去了被阅读的价值。图表设计的本质是替读者提前完成一次认知整理。读图的人和看代码不一样代码可以一行行扫图是瞬间被整体感知的。如果整体感知到的第一印象是“乱”后面再多的注释都救不回来。1.2 好图的底层逻辑规划读者的视线路径人看一张图视线不是均匀分布的。根据我自己观察和跟设计师同学聊下来的经验大部分人的扫图路径大概是这样的先看整体边界识别出大概有几块区域然后找入口和出口也就是流程从哪里开始、到哪里结束接着沿最粗或最明显的一条线往下走遇到分支和汇聚点会停下来思考一下。只有需要深究时才回到细节小字。所以一张好图的设计过程其实是在规划一条视线路径。你想让读者先看哪里就先在哪里建立视觉锚点你想让读者沿着主干走就让主干上的线条和节点比分支更醒目你不想让读者在中途迷路就要保证每一个分叉都有明确的去向和回法。这个思路落实到具体评判标准上我个人会看四件事是否有单一的主导流向。可以是自左向右也可以是自上而下但必须一眼能看出主干。同层节点的数量是否失控。单个分组内超过五六个同级节点阅读负担会明显上升。分组是否清晰。空间上的留白比边框线更有用先靠位置聚出组再靠标题说明组。颜色是否在传达信息而不是装饰。配色一多读者默认每个颜色都有含义最后发现只是好看信任感就没了。这一套标准我后面画每一张图时都会对照检查。2. 工具选型没有最好的工具只有最合适的表达载体2.1 四类图表工具的适用场景聊到 diagram-design工具是绕不开的话题。市面上的图表工具很多但归类之后其实只有四类分别对应不同的场景。第一类是手绘感工具典型代表是各类白板工具和手绘风格画板。它们的优点是自带一种“草图感”让观看者默认内容还没有定稿可以随便讨论和修改。这种工具适合架构评审的初期、头脑风暴或者想快速传达一个想法时使用。缺点是线条粗细、对齐、字体都非常随意正式文档放多了会显得不专业。第二类是拖拽式结构化工具比如 draw.io 这一类开源绘图软件。它们有丰富的图形库支持对齐、网格、图层画出来的图比较规范。这类工具最大的好处是上手快对非技术同学也很友好产品经理、后端、前端都能用。缺点是当图变大以后手动布局的维护成本很高每次加一个节点都要手动调半天。第三类是代码化定义工具比如 Mermaid、PlantUML、Graphviz 这一系列。图的结构通过文本描述然后由工具自动渲染成图。这套东西对开发团队特别有价值因为它把图变成了代码可以走 Git 版本管理可以做 diff可以跟着代码仓库一起被 review。缺点是自动布局有时候很“智障”某些复杂结构线会交叉需要写额外配置甚至手动指定位置。第四类是设计工具里的绘图能力比如专业设计软件里的流程图部分。常见用于对外发布的架构图、官网概念图、售前方案。这类图追求的是视觉精致但维护成本也最高一般不会直接承载技术变更只作为“对外门面”存在。我在实际项目里的选择是比较明确的文档里的技术图首选代码化定义因为图和代码同步维护是最可持续的评审和沟通阶段用手绘感工具保持轻快对外展示再花时间用设计工具打磨。2.2 代码化定义图表的工程优势很多团队迟迟不愿意用代码化工具理由是“画出来的图不好看”“布局不受控制”。这个理由我能理解但大部分是初期没有深入使用造成的误解。代码化工具真正的优势不在于布局多漂亮而在于它改变了图的维护方式。想象一个场景某个组件从三个实例扩到了五个如果是拖拽式工具你得打开画布复制两个方块手动拉线还得小心翼翼不要碰歪别的节点。如果是代码化你只需要在文本定义里多加两行重新渲染完事。如果图里的角色命名要改拖拽式你得一个个双击修改代码化只需要全局替换。更重要的是代码化定义让图能真正进入评审流程。我在的团队里很多图的变更都是跟着代码合并请求一起走的评审人看到的不再是一张图的前后对比截图而是结构定义里具体哪条连线变了、哪个节点被删了。这种“可 diff 的图”才是工程化的图它不再是一次性的产物而是活着的文档。当然我不建议所有人无脑代码化。如果你的团队里画图最多的是不懂技术的运营同学那拖拽式工具才是对的。工具选型永远跟着团队结构走这是最核心的一条原则。2.3 我常用的一组工具矩阵结合不同场景我目前比较稳定的搭配是这样的场景工具类型选择理由注意点日常技术文档架构图代码化可版本化、可复用复杂布局需要手动补偿评审现场动态讨论白板/手绘图轻量、随意、易修改结束后需有人整理成正式图跨职能沟通产品/设计/开发拖拽结构化工具共同语言门槛低要提前约定模板规范对外宣传/方案展示设计工具精修视觉冲击力强维护成本高不适合频繁变更代码注释内嵌调用链路轻量代码化片段跟着代码走绝不失同步只适合小范围链路展示这个矩阵不是固定的但至少保证我在面对任何制图需求时不需要重新想一遍用什么工具直接按场景套就行省下不少决策时间。3. 一套可以落地的图表设计流程3.1 动手前先回答三个问题很多图画不好不是因为技巧不够而是因为动笔太早了。我见过太多人打开画布就开始拖节点画到一半才发现信息不够或者受众根本不是同一批人。为了避免这种返工我给自己定了一个规矩任何一张正式图动笔之前先回答三个问题。第一个问题这张图给谁看给后端同事看的技术架构图不需要解释基本组件是什么给业务方看的流程图就不能出现一堆技术术语。同样的系统给不同受众画的图可以是完全不同的两张图。第二个问题在哪里看是投到评审会议室的大屏上还是嵌在文档里被人用手机翻大屏上可以接受小而密的图手机上看就必须控制节点数量把关键路径放大。第三个问题看完之后要做什么决策如果是一张扩容方案图读者要决策的是加哪个节点那这个节点就必须是最醒目的如果是一张告警链路图读者要定位故障那路径的起点就应该是“故障入口”而不是“用户请求”。这三个问题的答案会直接决定这张图的内容边界、布局方向和视觉层次。所以我现在每张图都会先写一小段话类似于“这张图给谁看、解决什么问题”然后才打开工具。如果这段话说不清楚图就不用画。3.2 从信息收集到主链路梳理画图的第一步不是布局而是列清单。我会把所有可能出现在图里的信息先一股脑写下来不管是核心节点还是边角料先保证没有遗漏。比如画一个消息推送架构图我会先列App 客户端、桌面端、Web 端、网关、路由服务、消息队列、推送服务、用户画像、数据存储、离线消息、在线状态……先列出来再开始做减法。减法是画图里最难的环节哪些信息是读者真正需要的哪些只是为了凑完整性。我有一条经验如果一个节点对“看完图之后做决策”没有帮助它就是噪音。列完清单之后第二步是找主链路。主链路是这张图最想表达的那条路径其他一切都是围绕它的分支。比如“用户发起消息 → 网关接收 → 路由选择 → 存储归档 → 推送到目标端”就是主链路。先把这条链路上的节点按顺序排好哪怕只有一条直线也要先明确主干。不要急着画分支。分支应该在建好主干之后一个一个往上挂。每挂一个分支都要重新检查一下主干是否还清晰。如果挂到最后主干被分支淹没了说明这张图该拆成两张。3.3 布局、配色与标注的细节规范到了具体布局这一步我有几个一直在用的硬性习惯。对齐是第一位的。所有同一层的节点纵向坐标或横向坐标必须严格对齐不能差几个像素。人对齐整的东西天然会降低认知负担这是无意识的。手拖节点很难做到精确对齐所以只要工具支持对齐辅助线就一定要用。分组靠空间而不是靠边框。有人喜欢用一个大方框把所有相关节点框起来这没问题但比边框更有效的是留白。组与组之间的间隔要明显大于组内节点之间的间隔读者第一眼就能靠“距离感”识别出区块。如果留白效果已经清楚了边框就可以去掉图会更干净。配色控制在三到四种。我常用的做法是一种颜色给主链路节点一种颜色给依赖/外部系统一种颜色给存储层再用一种中性色给普通辅助节点。重点只用一种颜色突出不要这里红那里蓝到处标。配色不是装饰是分区工具一旦颜色多了读者会自动认为每种颜色都有独立含义最后解读不了就干脆不看了。标注字要短。箭头上或者节点里的文字能用四个字绝不用一句话。图上文字太多读者的大部分精力会消耗在阅读上而不是理解结构上。更长的说明应该放进正文图只承担定位作用。3.4 导出、发布与后续维护图画完之后很多人直接截图往文档里一贴就完事了这一步坑最大。静态图片问题很多放大就糊、不能全局搜索、修改后要重新截图替换、和代码仓库对不上。我现在导出一般遵守三条原则。第一能导出矢量格式就不要导出位图保证放大不糊第二导出时给周边留一点边距不要把内容顶到画布边缘第三如果是代码化工具定义出来的图尽量直接在文档里引用渲染结果而不是贴截图这样每次渲染都会拿到最新版。后续维护是最容易被忽略的。一张图三个月没人改基本就已经失真了。要减少失真最好的办法是把制图和改图嵌入到日常工作流里而不是“文档出了问题再想起来修图”。代码化定义天然适合这件事因为它就活在仓库里代码改了顺手把图的定义也改了。4. 实操记录给某跨平台消息同步系统画一张架构图4.1 需求与信息清单接下来我用一个具体的虚构项目来演示整套流程。项目背景很常见某个跨平台消息同步系统有移动端、桌面端、Web 端三个客户端后端服务负责消息的接收、路由、存储和推送。这个系统最近遇到的问题是跨端消息同步延迟高需要画一张架构图来辅助定位瓶颈。按前面说的流程我先回答三个问题图给谁看给后端和客户端开发看目的是定位消息从发送端到接收端的完整链路。在哪看先在评审会议上看之后会长期放在技术文档里。看完要做什么决策确定时延瓶颈在哪一层决定优先优化路由还是存储。目标明确了信息清单就跟着出来了。我需要的节点包括三类客户端节点、服务中间件节点、存储节点。具体有移动端、桌面端、Web 端三个入口接入网关负责连接保持和协议解析路由服务决定消息去哪个会话和哪个设备消息队列做削峰缓冲消息存储负责持久化在线状态服务维护设备连接状态推送服务负责向离线的目标端发通知最后是各端从存储拉取增量消息。4.2 用结构化数据定义图内容我选择用代码化方式定义这张图。工具无关紧要关键是先把结构表达清楚。我写了一份类似下面这样的结构化定义描述节点和连线。这个设计的思路是先把内容从“视觉”里剥离出来让图的信息模型先成立再谈渲染。{ title: 某跨平台消息同步系统架构, nodes: [ { id: mobile, label: 移动端, layer: client }, { id: desktop, label: 桌面端, layer: client }, { id: web, label: Web端, layer: client }, { id: gateway, label: 接入网关, layer: access }, { id: router, label: 路由服务, layer: service }, { id: queue, label: 消息队列, layer: service }, { id: store, label: 消息存储, layer: storage }, { id: status, label: 在线状态, layer: service }, { id: push, label: 推送服务, layer: service } ], edges: [ { from: mobile, to: gateway, label: 发送/拉取 }, { from: desktop, to: gateway, label: 发送/拉取 }, { from: web, to: gateway, label: 发送/拉取 }, { from: gateway, to: router, label: 投递 }, { from: router, to: queue, label: 写入 }, { from: router, to: status, label: 上报 }, { from: queue, to: store, label: 持久化 }, { from: store, to: push, label: 拉取待推 }, { from: status, to: push, label: 目标在线态 } ] }这一段定义里我把“层”的信息也放进去了。这个非常关键因为后面的布局计算完全依赖它。给每个节点标上 layer相当于预先完成了分组接下来只要让同一层对齐就好。4.3 布局坐标系与自动计算有了结构定义布局就可以交给程序做。我写了一个很简单的 Python 脚本按 layer 分组每组分配一个横坐标然后组内节点按顺序纵向排开。成本很低但对理解“代码化布局”很有帮助。import json def layout_graph(schema): nodes schema[nodes] edges schema[edges] layers {} for n in nodes: layers.setdefault(n[layer], []).append(n) ordered_layers [client, access, service, storage] positions {} layer_gap 160 node_gap 60 for idx, layer in enumerate(ordered_layers): x idx * layer_gap for j, n in enumerate(layers.get(layer, [])): y j * node_gap - (len(layers[layer]) - 1) * node_gap / 2 positions[n[id]] (x, round(y, 1)) return positions, edges schema json.load(open(schema.json, encodingutf-8)) positions, edges layout_graph(schema) for nid, coord in positions.items(): print(f{nid}: {coord})这段脚本跑了之后输出的坐标就是一张分层架构图的基本骨架。我自己做这个 Demo 的时候看到不同层天然形成四条竖列客户端在左、存储在最右中间是网关和各类服务整个图的流向非常明确从左到右主路径一目了然。坐标计算只是第一步。真实使用代码化工具时我还会在定义里补充两个东西主路径的高亮标记告诉渲染引擎这条链路上的节点需要加粗以及分组标题渲染后在每条竖列上方显示“客户端”“接入层”“服务层”“存储层”。有了这些一张可读性不错的架构图就出来了。4.4 成图后的视觉检查清单图渲染出来之后我不会直接就用而是会过一遍视觉检查清单。这张图的检查结果如下主链路是否唯一清晰客户端 → 网关 → 路由 → 消息队列 → 存储 → 推送这条路径在全图里是最显眼的。层与层之间的间距是否足够我设置了 160 的横向间距留白感够不会挤在一起。节点数量是否超限全图 9 个节点加上 9 条连线整体可控。颜色是否克制分成三组颜色主链路一种强调色存储用另一种色客户端统一用中性色。文字是否简短每条连线上的说明都缩到了四个字以内。检查的过程其实特别快但价值很大。很多图乍看还行放大才发现节点重叠、文字被裁、颜色表意不清。提前用清单过一遍比发布到文档里被一堆人吐槽再改要省事得多。5. 高频问题排查与避坑经验5.1 常见问题速查表我整理了这些年画图时遇到最多的问题以及对应的处理办法做成一个速查表。问题现象最常见原因处理建议一整张图太挤看不清楚信息量超过单图承载能力拆图按分组分别成图用一张总览图串起所有子图箭头线交叉严重布局方向选择不对换流向方向或者把分支放到主路径的同侧不重要的分支干扰主干没有做信息取舍弱化分支颜色和线宽甚至直接用“更多细节见子图”替代文字溢出节点边界节点尺寸和文字长度不匹配先定文字再定尺寸或者缩短标注导出到文档后模糊导出了位图改用矢量导出或提高导出分辨率图与代码很快失真图没有纳入版本管理用代码化定义并跟随仓库维护团队风格不统一缺少模板和颜色规范沉淀一份内部模板约定图层结构、色板、字体排查这些问题的核心心态是图是给人看的不是给自己交差的。一旦发现有读者反馈“看不懂”第一时间要问的是信息层次是不是乱了而不是读者水平不够。5.2 容易被忽略的视觉细节有几个细节属于那种“不说没人注意但注意到了就回不去”的级别。第一个是箭头方向的一致性。虽然图的流向是自左向右但分支也要保持一致的方向尽量不要出现“返回箭头”直着连回去而是绕一个明确的弯或者标注“异步回执”等字眼否则读者会误判流程方向。第二个是线宽和颜色深浅的层级。默认连接线用细线主链路用粗线待优化或故障路径用虚线或特殊标记。这一点小小的差异能让读者在第一时间识别重点。第三个是留白和间距。我倾向于让不同层之间的水平距离大于同层节点之间的垂直距离这样区块感就有了。有些工具默认布局会按照均匀分布处理导致分组感很弱这时就需要手动调整间距参数。第四个是深浅主题适配。技术文档往往会被读者在夜间模式下查看。如果图里用了淡黄色填充在浅色背景下没感觉深色背景下会变得非常刺眼。所以我现在的做法是优先使用语义明确的颜色蓝、绿、红少用亮色填充大面积区域避免主题切换后大量返工。5.3 让团队风格统一的一个小机制“风格不统一”是团队绘图里最磨人的问题。每个人画出来的图都有自己的习惯有人喜欢圆角框有人喜欢直角框有人图例在左上有人在右下。放到一起整个文档库就像拼盘。我尝试过一个成本很低但效果不错的机制在团队内部沉淀一份“制图约定”文档不叫规范就叫约定显得不那么强势。约定里只写五件事图的流向方向、节点形状使用规则、颜色表意规则、分组间距建议、导出格式要求。任何人画正式文档图之前先看一眼约定按统一框架去画。同时在绝大多数情况下我尽量把团队的正式图引向同一个工具生态。当大家用同一套模板、同一类代码化定义时风格差异天然会缩小。这个机制不需要领导去强推只要有两三个人带头使用后面新人照着已有文档画风格自然就对齐了。6. 最后分享一点我自己的体会这几年画图下来我最大的心得可能和很多人想的不一样画图最难的不是把信息画进去而是决定哪些信息不画进去。我在实际项目里反复遇到过这种情况一开始想表达全部最后图越来越重读者越来越少。后来我把标准简化为“一张图只讲一件事”反而效率高了很多。真正好的图表设计是让读者用最短的时间找到他最需要的那条路径让图和代码一样成为可以被其他人持续维护、改进的工程资产。每次画完图我都会试着盯着主链路看三十秒如果不能在三十秒内讲清楚这张图在表达什么我就会回去继续删。