1. 复盘 diagram-design我为什么把画图当成工程来做diagram-design 是我沉淀了大半年的技术制图规范。它不是一个画图软件也不是某个框架里的自动生成插件而是一套面向技术文档、架构评审、故障排查和新人培训的“画图方法论”。过去团队里每个人都会画图但画出来的东西风格各异有人用圆角矩形有人用直角矩形有人把数据库画成圆柱有人把数据库画成桶箭头颜色更是五花八门。图一多大家就开始互相问“这个框代表什么”“这条虚线什么意思”沟通成本比写代码还高。我用 diagram-design 想解决的就一个问题让一张技术图在没有任何口头解释的情况下也能被团队里所有人用同一种语言读懂。同时它也要能适配文档、幻灯片、白板、代码仓库这些不同的展示场景既能表达复杂系统又不会让看图的人一头扎进细节里出不来。如果你也在做方案设计、技术选型输出、组内分享或者要长期维护一套系统架构文档那我建议你先别急着拖组件。先把画图这件事当工程来做你后面省下的解释成本会非常可观。这篇内容适合后端、前端、运维、大数据方向的开发人员也适合需要画流程图、时序图、网络拓扑图的产品和技术写作者。1.1 一张图被反复修改背后的真实原因先说一个真实场景。某次做架构方案评审我提前准备了一张服务依赖图。在线评审的时候一位同事问“这个灰色框是已有的服务还是这次要新建的”另一个人问“从网关到订单服务的箭头是同步调用还是异步事件”我当时一一解释但评审完我发现这张图脱离了讨论现场没过几天就再也没人看懂了。这就是大多数技术图的通病画图的人脑子里带着完整上下文默认看图的人也懂这些上下文。但实际看图的人往往只看图不看你脑中那些默认。于是图越改越复杂最后变成了只有作者本人能读懂的“密码图”。这个经历让我意识到制图必须先定义信息语义再考虑排版和配色。语义不一致再好看的颜色都是噪音。1.2 diagram-design 交付什么内容diagram-design 实际沉淀下来的是四类东西一份符号语义表、一套布局规则、一组可复用的模板、一张评审自查清单。它不强求你用某个特定工具而是要求所有产出物遵循同一套信息表达规则。因为工具可以换来换去但底层逻辑如果不统一换工具只会把混乱搬个家。符号语义表解决“框和线代表什么”布局规则解决“信息怎么排布更不容易读错”模板解决“不同场景下的图应该长什么样”评审自查清单解决“画完之后怎么确认自己没有自嗨”。这四样东西组合起来就是一套可以长期维护的制图基础设施。你可以把它放到团队文档库或者跟着代码仓库维护每次更新时走版本记录。1.3 不同场景的图要有不同优先级我最早犯的错是想用一套规则约束所有图。后来发现架构图、流程图、拓扑图、时序图各自的目标不一样不应该完全同构。架构图重点看组件边界和依赖关系流程图重点看分支和异常路径拓扑图重点看网络连接和部署位置时序图重点看消息顺序和生命周期。diagram-design 对它们只约定底层的通用语义再为每种图扩展出针对性规则。图类型核心问题最该突出的信息最容易被忽略的信息架构图系统由哪些部分组成模块边界、依赖强弱部署边界、归属关系流程图一件事怎么被完成主线顺序、分支条件异常回退、超时补偿时序图组件之间怎么协作消息顺序、调用方向异步回调、并发区域拓扑图节点如何互连链路、端口、区域分组安全策略、流量走向画图前先确认这是哪一类图比先选择什么配色重要得多。方向错了形式做得再精美也没有价值。2. 拆解核心思路先定信息骨架再谈视觉表达diagram-design 的底层思路其实非常简单把所有技术图都当成“信息结构”来设计。视觉只是信息的载体如果信息结构没有梳理清楚后面所有排版技巧都只是装饰。我一般把设计流程分成三块先回答决策问题再拆信息层级最后才进入符号和布局。2.1 动笔前先回答三个问题我每次画图前都会在文档顶部写一句话类似“这张图用来让新同学在 10 分钟内理解订单创建的主链路”。写不出来的话说明连我自己都不知道这张图到底要传递什么。三个固定问题分别是给谁看的看完之后他需要理解什么或做出什么判断这张图会出现在哪里这三个问题直接决定信息取舍。给新同学看就要把核心链路画得粗一些把容灾细节折叠起来给稳定性评审专家看就要把超时、重试、降级路径放上去。出现在幻灯片里文字要少字体要大出现在代码仓库的说明文档里可以多放注释但不要用太密的布局。场景不同同一套系统可以拆成好几张图而不是硬塞成一张“全家福”。2.2 信息分层主链路、辅助链路、上下文设计图的时候我把信息分成三层。第一层是主链路它是图里的主角视觉上要最突出第二层是辅助链路比如缓存、异步通知、日志上报它们围绕主链路存在第三层是上下文比如外部系统、部署边界、用户入口用于帮助读者定位。这三层不是并列关系而是按视觉权重递减的关系。实际操作时我会先用文字把主链路写出来比如“用户请求经过网关转发到订单服务订单服务写库后发送事件通知服务消费事件并短信通知用户”。主链路成立之后再把缓存、重试、监控这些辅助链路挂上去。最后补上下文边界。这个顺序保证了图画出来不会变成一团乱麻因为你的视线始终有一条主线可以跟着走。2.3 符号语义统一到一张图例上diagram-design 里最核心的是那张符号语义表。没有这张表每个框都要靠标签说明图永远干净不了。我采用的规则尽量少而明确圆角矩形表示当前系统内的服务或模块直角矩形表示外部系统或第三方组件菱形表示判断分支圆柱表示数据存储虚线框表示部署边界或逻辑分组。箭头方面实线箭头表示同步调用虚线箭头表示异步事件或消息粗箭头表示这条路径是主链路。这套规则的好处是它不依赖工具也不限制创意。任何人拿到一张符合规范的图先看图例和主粗箭头就能抓住骨架再顺着实线虚线把细节补齐。注意不要在同一张图里堆满十几种形状那样等于没有规则。为了表达某些特殊含义你最多增加一两种扩展符号而且必须画进图例区。2.4 布局法则方向、对齐、交叉布局是大多数人画图时最容易失控的地方。diagram-design 定了几条硬性法则整张图只能选择一个主导方向要么自上而下要么从左到右不允许东一块西一块地乱放所有节点尽量对齐到网格上不要出现莫名其妙的居中漂移连线尽量走正交路径少用斜线同一条线上的箭头要统一方向不能一会儿向右一会儿向左。为什么这么较真因为人的视线在水平方向和垂直方向上的移动成本最低。方向统一时读者可以用扫描的方式理解图而不是来回跳着寻找顺序。连线交叉是最大的阅读障碍尽量减少交叉哪怕因此需要重复出现同一个节点。重复节点配合虚线框引用也远好过一团剪不断理还乱的连线。3. 实操流程从需求到终稿的五步法纸上谈兵没有用我把自己常用的完整流程拆成五步。这套流程不用额外开发工具完全靠习惯就能跑起来。你现在就可以拿一个真实项目试一次。3.1 工具与交付形态怎么选工具选择会影响效率但不应该影响规范。diagram-design 里只有两类工具定位一类是所见即所得的矢量画板适合做演示图和精细排版另一类是文本化图表语言适合把图的源文件放进代码仓库走版本管理和多人评审。两种形态各有取舍我一般用表格来决定每次用什么。维度矢量画板文本化图表语言上手速度快直接拖拽需要记少量语法精细排版强像素级可控较弱布局由算法决定版本对比差二进制文件难 diff好文本可以直接 diff多人协作需要在线协作机制天然适配代码评审流程适合场景对外演示、概念草图代码仓库存档、长期维护我的习惯是临时画个草图用白板正式沉淀进文档库的图尽量用文本化描述。因为长期维护的图迟早会被改文本形式让改动记录、责任边界都变得非常清楚。3.2 五步法具体操作第一步写需求笔记。用三句话说明给谁看、看什么、放哪里。这一步不能跳哪怕只花两分钟。第二步画信息骨架。先在纸上或白板上用最简单的方框和箭头把主链路画出来完全不管排版和颜色只确认“有多少个节点、多少条关键路径”。骨架阶段如果节点超过十五个就考虑分层拆图。第三步套模板和符号语义。把骨架里的方框替换成规范形状把箭头替换成实线、虚线或粗箭头给数据存储加上圆柱符号。第四步做布局与标注。确定方向和网格对齐加上图例、标题、版本和一句摘要说明。第五步评审修正。找一个人对你的图做“无讲解阅读”他读不懂的地方就是你要改的地方。这五步看起来笨但恰恰是它保证了最后产物的可读性。3.3 一个订单链路图的落地示例我拿一个最常见的订单创建链路来演示。需求笔记很简单给新同学看理解一次下单请求的主链路放在系统文档首页。信息骨架画出来后文本示意大概是这样[用户] --HTTP-- [接入网关] --RPC-- [订单服务] --SQL-- [订单库] | --MQ事件-- [通知服务] --短信-- [用户]对照规范我把外部用户画成直角矩形网关、订单服务、通知服务画成圆角矩形订单库画成圆柱。HTTP 调用和 RPC 调用画实线箭头MQ 事件画虚线箭头核心链路加粗。辅助链路比如“日志采集”和“监控告警”并不放上这张图而是单独拆成一张可观测性图。最终图里没有多余颜色主链路一种强调色辅助链路统一灰色图例放在右上角。这样落地之后新同学看文档时不再需要到处问人。他先看图例再顺着粗箭头读一遍就知道订单服务是整个链路的核心数据库写入和 MQ 事件是紧随其后的关键动作。一张图能够独立完成这个使命就不辜负它占据的那块文档版面。4. 核心细节与避坑技巧颜色、文字、连线有了清晰的骨架剩下的就是细节。很多图画得丑、读着累不是信息问题而是颜色和排版的细节出了问题。这部分我把实践里最有用的几条写下来都是常规文档里不太会提的。4.1 配色越克制越专业一张技术图里颜色承担的是分类功能不是装饰功能。diagram-design 默认采用“灰底 一种强调色 语义色”的配色方式。所有普通组件用浅灰填充加深灰描边主链路或者核心组件用一种强调色只有表示异常、危险、阻断的时候才用红色这类高饱和语义色。绿色尽量少用因为它和“成功”绑定得太紧不是所有读者都有同样的语义预设。配色还要考虑色弱读者。不要用红绿作为唯一区分方式红色组件除了颜色外最好再加粗边框或者在标签里加“故障”这样的文字前缀。深浅色背景下也要验证对比度深色模式下不要使用大面积深蓝配黑字浅色模式下不要大面积使用亮黄底。我通常会在导出前切到深色背景预览一遍确认连线不会被背景吃掉。4.2 文字排版和留白节点里的文字要短最好不超过六个字。无法缩短时把完整的名称写进图例图上只留缩写。字号尽量统一不要把标题、模块名、注释堆成三种大小互相干扰。文字对齐要么全部居中要么全部左对齐不要同一个框内一个居中一个靠下。斜体和下划线尽量避免因为容易把文字和超链接混在一起。留白是很多人忽略的维度。节点与节点之间保持足够间距不要让边框贴在一起连线上不要放太多文字必须标注时把文字放在线的中间上方并且给文字加一层背景色避免和连线重叠。图里的信息密度宁可低一些也不要为了一页放下更多内容而牺牲可读性。4.3 连线端口与折点连线画得是否专业看两个地方起点终点接在哪儿以及折点是否干净。节点通常有四条边的中点可以作为端口连线尽量从边的中间进出不要从任意角落斜插进去。如果两个节点之间有多个连线要保证所有连线从同一侧进出避免一条从上面走一条从下面绕最后乱成一团。折点数量越少越好。正交折线每增加一个折点阅读负担就增加一分。有些图工具会自动布局但它并不理解业务语义所以我自己偏好先手工摆好节点顺序再让工具按网格自动整理。当出现长距离连线时宁可多放一个“重复节点”做转折也不要让一条线横穿整张图去跨越多个无关组件。4.4 把图例做成图的一部分图例不是可选项。我见过很多图画得非常精细却没有图例结果每个读者都在猜灰色虚线框到底是什么。diagram-design 要求图例必须直接出现在图内而不是写在文档正文里。图例区放在右上角或左下角占的位置不需要很大但要包含所有使用到的形状和箭头样式并且加上一句简要说明。图例还要配合摘要文字。我会在图下方加一行比如“本图展示订单创建主链路虚线表示异步消息红色框表示异常场景节点”。摘要文字比图例更进一步它直接告诉读者“这张图怎么看”。有了它即使读者完全不了解项目背景也能在一分钟内进入状态。5. 常见问题与排查技巧实录实操过程中我踩过的坑基本都能归到下面几类。这里面有些问题是工具层面就能解决的有些必须回到信息层面重新思考。5.1 图又满又密怎么办图太满通常不是因为内容多而是因为一张图试图承载太多目标。我不建议靠缩小字体、压缩间距来硬塞正确做法是拆图。把大图拆成“总览图 细节图”总览图里只保留模块边界和主要依赖细节图里再展开每个模块内部流程。两图之间用相同的模块命名和编号互相引用读者先看总览再按需点进细节。拆图时要注意维护索引。每张细节图都要明确标注“这是总览图中第几号模块的内部实现”否则拆完之后读者反而找不到上下文。实务上我会用编号分组比如 A 组是接入层B 组是业务层C 组是数据层。总览图里的 C-2 走进去就是对应的数据层细节图。这样图的数量变多了但单张图的负担变轻了。5.2 连线交叉怎么都排不掉交叉线的本质是节点顺序没有配对好。大多数情况下把上下游节点按照“调用发起方在上游被调用方在下游”的顺序重新排列交叉就会减少。如果还有交叉看看能否让多条连线走同一条“总线”比如统一经过消息队列或网关再分发。总线表达真实业务上的汇聚点同时也顺带解决了视觉杂乱。另一种有效技巧把同一层的节点放在同一个水平带内让连线只在相邻带之间出现不要跨越多个带。如果两个节点距离非常远说明它们在架构上很可能不该直接耦合。这时候与其调整连线不如回头问问业务上是否真的存在这条直连路径。图不好画往往是架构本身绕了路。5.3 团队成员不按规范执行规范落地最大的阻力不是理解而是习惯。为了解决这个问题我把 diagram-design 做成了一张“一页速查表”和一批模板——而不是几十页手册。团队成员第一次画图时只要复制模板改内容格式就不会跑偏。评审时我只看自查清单不啰嗦个人偏好。清单里全是客观检查项图例是否齐全是否只有一个主导方向主链路是否加粗有没有超过三种强调色。如果还是有人不遵守多半是因为模板不够好用。这时候不要怪人要去更新模板。规范是给人用的如果它让画图变得更慢那迟早会被抛弃。好的规范应该让最简单的一次画图也直接达标。5.4 快速自查清单检查项通过标准图例与符号图中出现的所有形状和箭头都能在图例里找到单一结论一句话能说清这张图表达什么主链路核心路径在 3 秒内能被识别方向整图只有一个主导阅读方向颜色强调色不超过一种语义色有文字辅助文字节点标签不超过六个字无斜体和下划线连线交叉尽可能少端口都在节点边框中间版本信息有标题、维护人、日期或版本号自查清单会让每个人在导出图之前冷静十秒钟。我实测下来这一张表比任何制度都管用因为它的判断标准足够客观团队评审时不容易吵起来。5.5 图被复用后失去上下文很多图第一次画的时候效果很好三个月后打开却没人看得懂。原因是没有记录上下文。我后来在每张图的源文件头部固定写一段注释包含三个信息这张图给谁看、当前版本解决了什么问题、下次修改时需要重点确认哪些假设。这些注释不进入最终展示但对维护者来说是救命信息。文档里的实际展示位置也会影响理解。图不要孤立地挂在页面中间前后至少要各有一句话交代背景。如果一张图属于“故障排查专项”就在图下方说明触发条件是什么看完图下一步该做什么。读者带着任务来看图比被丢进一张陌生系统图里的体验要友好得多。6. 踩过这些坑之后我最想保留的三个习惯把个人经验沉淀成规范的过程里我留下三个反复验证有效的习惯。它们不是多复杂的技术但长期价值非常高分享出来供你参考。6.1 每张图只留一个主角复杂系统里处处都是信息但一张图只能有一个核心信息。画图前我会问自己如果读者只能从这张图里带走一件事我希望它是什么这件事就是主角。主角用粗边框或高亮色突出其他所有内容围绕它展开。没有主角的图读起来就像没有重点的会议散场后什么都不记得。我在重构某个系统的架构图时最初把十几个微服务全画上去每个服务都用不同颜色结果评审时大家各看各的谁也说不清重点。后来我把图分成三张一张讲“流量如何进入系统”主角是网关一张讲“订单状态如何流转”主角是状态机一张讲“数据如何落库”主角是存储层。每张图主角清晰评审效率立刻上来了。6.2 把图当成会进化的代码技术图不是交付的一次性产物它和代码一样需要持续维护。所以我更倾向于使用文本化图表语言来保存正式图让每次改动都可以 diff、可以回滚、可以留提交说明。团队里任何人想改图不是直接编辑一张图片而是修改源文件并触发评审。这样图的演进过程会被完整记录也不会出现“文档里那张图已经和线上系统完全对不上”的失控状态。我最开始也觉得这个习惯有点重直到某次排障时需要确认某个模块是哪个版本引入的依赖。因为图源文件里有完整的提交历史十分钟就定位到了变更记录。这个效率提升让我坚定了“图也能走代码评审”的思路。6.3 保持 30 秒读懂的标准一张经过 diagram-design 处理的图应该达到一个硬指标一个对这个项目完全陌生的人看它 30 秒后能用自己的话复述出主链路和关键依赖。达不到就继续改。这个标准听起来苛刻但很有效。它逼着我把最想表达的信息放到最显眼的位置把不重要的细节收进折叠区把含糊的箭头改成明确的语义。我现在画完图之后习惯找身边的同事做一次“30 秒测试”——只让他看图不做任何解释。测试结果几乎总是指出我之前没想到的模糊点。这个动作做多了画图的时候就会自然提前把容易误解的地方处理干净。时间长了团队里的图会慢慢形成一种统一的“呼吸感”哪怕不看署名也能一眼认出这是按同一套规范画出来的。这就是 diagram-design 真正想达到的状态。