先说点实在的。DIAGRAM-DESIGN 这个名字乍一听是个美工活儿好像就是把图画好看。但真正在系统设计里把它当作一个项目来推进之后我才意识到这件事的本质根本不是画图而是把系统里那些没法用文字说清楚、一说就各执一词的结构性知识用一组有约束的图形语言固化下来。我做过一个内部系统整轮图表治理历时两个多月涉及架构图、时序图、部署图、调用链路图等几十张存量图的重构过程中踩过不少坑最后沉淀出一套可以复用的分层方法、工具选型和图面规范。这篇文章就把整个思路完整盘一遍适合正在被文档里的图过期评审会没人看得懂图多人在同一张图上乱改这些问题折磨的团队和个人。1. 为什么大多数系统图画完就烂掉三个根因先别急着学工具、找模板。我花了大半个月的力气才想明白一件事图表画完就没人看、没人维护通常不是工具的问题也不是画图的人不够认真而是从一开始就把图当成了一次性交付物而不是需要持续维护的资产。下面三个根因基本覆盖了 90% 的图表腐烂案例。1.1 图与代码脱节没有来源的图就是摆设最常见的死法是图上画的模块调用关系跟代码仓库里真实存在的调用关系对不上。这种图第一次评审还能糊弄过去等到系统迭代两轮之后新人照着图去排查问题照着图去理解服务依赖一查一个不吱声从此这份图就再也没人信了。我当时接手的第一件事是拿现有架构图和代码仓库里的实际依赖做了一次对照审计。结果触目惊心图示的服务有 36 个实际生产环境里跑着的服务 41 个图上画了网关直连数据库实际代码里网关层根本不感知数据库图上没有的某个消息队列恰恰是现在订单链路里最关键的中间件。说白了这张图不是不准确而是半虚构。这背后的根因是图是某位同学在某个时间点凭记忆画出来的画完后没有任何机制把图和真实系统绑定。后来我定了一条铁律——任何一张架构图必须标注数据来源和最后核对时间。没有来源的图评审时直接打回不允许进文档库。这个动作看起来很笨但它逼着所有画图的人去代码里、配置里、监控面板里找依据而不是凭脑子里的印象画。1.2 信息密度失控一张图塞下了所有信息等于什么都没说第二个高频死法是把架构图当成了系统全家福。服务、数据库、缓存、消息队列、定时任务、第三方依赖、网络分区、认证中心一股脑全塞进一张图里。画的人觉得信息越全越好看的人却完全抓不住重点满屏的框和线视觉上先崩溃了。我见过最夸张的一张架构图A2 纸都打不下缩印成 PDF 之后字体完全看不清。图上光连线就有 200 多条还有 14 种颜色的图例。结果评审会上问一句下单流程的主链路是哪几条在场七八个人没人能当场指出来。这就是典型的信息密度失控——图承载了太多不同抽象层级的内容读者根本不知道先看什么、重点是什么。同类问题也发生在时序图上。有人把一次完整的接口调用画了 30 多个生命线从浏览器到网关到鉴权到各个微服务再到数据库还顺便把失败重试、异常分支全画进去最终变成一张没人有耐心看完的天书。这里我学到的教训很朴素一张图只讲一件事。画调用链路的图就不要混入部署拓扑画部署拓扑的图就不要试图表达业务状态流转。信息全不是架构图的目标重点清楚、路径明确才是。删掉那些也许以后能用上的元素图的质量立刻提升一个档次。1.3 多人无序改图没有版本和规范的图改一个词都是灾难第三个根因藏得比较深通常要等团队规模变大之后才暴露。早期几个人画图靠默契、靠口头约定问题不大。但十个人以上都在往同一张图上加节点、改连接、调颜色的时候混乱就开始了。我经历过一次真实翻车现场某天做架构评审投影仪上打出来的部署图跟上周文档里的版本完全不是一回事某个核心服务的节点被挪了位置还多了两条来源不明的虚线。会上问了一圈三个人都说我上周改过一点。至于为什么改、改了哪部分、依据是什么——没人说得清。那张图最后只能当作作废处理大家各凭记忆拼凑一份临时版继续开会。这件事之后我开始认真研究图也应当被当作代码来管理这个思路。图不能是一坨只能在 GUI 里拖拽、无法 diff、无法回滚的二进制文件图应当有版本、有评审记录、有变更说明最好还能有一套自动化的检查规则挂在流水线里。这是后来整个 DIAGRAM-DESIGN 项目转向文本化方案的最直接的导火索。2. 四层图各管一件事画图前的分类学把上面三个根因想清楚之后我意识到光靠大家认真点根本无法解决问题必须给团队一套明确的图表分类体系。分类的目的不是限制大家的创作自由而是让每张图都有清晰的职责边界读者看到这张图就该知道它讲的是哪个层面的事。我当时采用的分层思路大体上对应业内常说的 C4 模型——系统上下文、容器/模块、组件、部署四个层级各自承担不同的叙事职责互不混用。2.1 第一层系统上下文图讲清楚系统在哪里系统上下文图是整个体系里最高层、也最容易被忽视的图。它不关心内部怎么实现只回答一个问题这个系统跟它外部世界之间的边界在哪谁依赖谁。画系统上下文图时主题系统通常只需要画一个大的圆角框或矩形框放在图中央外部角色用户、上游系统、下游服务、第三方平台分布在四周用箭头表示调用方向和数据流向。这张图的受众是产品经理、新入组的同学甚至非技术背景的业务方目的是让所有人对系统的边界达成共识。当时我把这个层次的图单独拎出来规范还治了一个实际问题有段时间业务方总觉得你们系统应该能直接对接某个外部平台开发这边反复解释边界不在这光靠嘴说没用。后来我把系统上下文图画清楚外部依赖圈的边界一目了然再评审这种诉求时直接翻到第一张图指给业务方看争论成本低了很多。画好这层图的关键点是克制外部系统外到哪个边界为止要明确。我当时定了条内部约定外部系统只画到我们直接对接的那一个面不需要把它内部再展开。展开的事属于下一层级。2.2 第二层容器与模块图讲清楚系统由什么组成在系统上下文图之下的这一层开始打开系统外壳。这里说的容器不特指 Docker 之类的容器化技术而是泛指系统内部相对独立的运行单元、部署单元或模块比如一个 Web 应用、一个后台任务进程、一个数据库实例都是容器层的元素。这一层的核心任务是表达系统内部有哪些主要组成单元单元之间如何交互。当时我为那个内部系统画的容器图把 41 个服务按领域边界归拢成十几个逻辑模块每个模块画成一个框框里列出主要服务名。模块之间的连线只画强依赖关系弱的、间接的依赖直接忽略否则线一多又乱了。画这层图的时候我吃过一个亏一开始想做得太细把每个服务之间的 REST 调用都画出来结果得到一张比原来更乱的服务网格图。后来反过来先按业务域分组组内服务不连线只画组与组之间的调用关系图面一下就清爽了。记住这层讲的是组成结构不是分布拓扑更不是调用明细。2.3 第三层组件与核心链路图讲清楚关键路径怎么走第三层进入具体运行单元内部或者跨单元的某条核心业务链路。典型代表就是组件图一个服务内部有哪些组件和时序图一次请求如何在各单元之间传递以及调用链路的骨干图。这层图是日常开发、排查问题、做代码评审时利用率最高的也是最容易画乱的。我的建议是组件图只画具备稳定性的核心组件和关键依赖别把框架自动生成的那些类也画上去时序图则只画一条主链路异常分支和重试逻辑如果确实重要单独另开一张图宁可用文字描述也不要硬塞进来。这里有一个非常实用的处理方式给每条核心链路编号。比如下单主链路 L1支付回调链路 L2编完号之后文档、代码注释、评审记录里都可以直接引用见 L1 链路图。这个编号体系让图从一个孤立的文件变成了整个知识库里的坐标锚点谁要讨论哪条链路报个编号就能找到对应的图。2.4 第四层部署拓扑图讲清楚系统跑在哪里部署拓扑图是单独的一类跟上面几层关注的维度完全不同。前面三层关心逻辑上系统由什么组成部署图关心物理上每个组件运行在什么环境、依赖哪些基础设施。我通常要求部署图上至少表达四类信息环境划分开发、测试、生产、网络区域内网、外网、隔离区、节点类型虚拟机、容器、物理机、关键中间件实例数据库主从、消息队列集群、缓存集群。部署图不需要画业务链路不需要画服务之间的调用关系它的读者是运维同学和值班人员。还有个常见误区有人喜欢在部署图上顺便标注延迟指标或容量信息比如这里大概能扛 1 万 QPS。我个人建议这些信息不要直接堆在图上可以在图的附件说明里补充。因为容量是会变的图本身却不容易每次跟着变。图上信息越静态越好动态数据留给文档和监控大盘。3. 工具选型之争从拖拽画图转向文本化方案的完整逻辑图表分类体系搭好之后接下来就是工具选型。这一步很多团队会吵架有人习惯了拖拽式工具有人坚持要写文本。我把自己的真实需求摆到台面上发现答案其实不难选就看你的核心诉求是什么。3.1 先想清楚三个诉求可 diff、可回滚、可评审我对图表工具的第一诉求不是什么炫酷的交互而是图能不能纳入版本管理。原来的流程里拖拽工具保存出来的是二进制文件或自有格式文件Git 对它的 diff 基本不可读——两个人同时改一张图合并结果完全不可控。这在多人协作场景里是致命的。第二诉求是可回滚。图作为一种资产偶尔会有改错的时候。文本化方案天然支持用 Git 回滚到任意历史版本哪次改坏了git revert 一下就能回到上一个正常状态。拖拽方案虽然有些也支持历史记录但颗粒度和可控性普遍没那么理想。第三诉求是可评审。我们希望图在提交之前能被自动检查、能被人在线 review。而文本化方案生成的图源文件是普通文本可以像代码一样发起合并请求评审人可以逐行查看改动而不是对着两张图截图猜哪里不一样。明确这三个诉求之后我几乎没有犹豫就转向了文本化方案。业内这类方案不少核心思路都是用结构化的文本描述图形元素再借助渲染器生成图片或矢量图。好处是文本本身极其轻量可以在任意编辑器里编写可以进 Git可以写脚本做校验。3.2 文本化方案的工作流长什么样我当时搭的流程大概是这样仓库里建一个专门的目录比如 docs/diagrams里面按层级分子目录存放所有图表源文件。团队成员的作图流程是复制现有模板文件按规范修改文本描述提交合并请求由 CI 自动触发语法检查和规范校验校验通过后再由至少一位熟悉该模块的同事 review最后合入主干。这套流程跑顺之后几个变化非常明显。第一图没了这种事基本绝迹——所有图都跟着代码一起进版本库不会散落在某个人的个人网盘里。第二图的变更记录变得可追溯任何一次修改都能说清楚为什么改、谁改的、改了什么。第三新成员上手时不再需要从零摸索读一遍文本源文件就能看懂图的内容甚至结构设计思路。刚开始团队里也有人不适应毕竟从鼠标拖拽出图切到写文本出图直观反馈上会弱一些。但坚持一两个迭代之后大家普遍真香了——尤其是遇到跨分支合并、多版本共存这些场景文本方案的优势是拖拽工具没法比的。3.3 拖拽工具仍然有价值什么时候该用回去讲到这里必须说句公道话文本化方案不是银弹拖拽工具在某些场景下依然不可替代。最典型的场景是快速探索和头脑风暴。比如评审会上现场讨论一个新方案的拓扑关系几个人在白板上画来画去——这种时候用拖拽工具或电子白板效率最高内容也经常是临时的压根不需要进版本库。另一个场景是给非技术角色看的概念图、架构岛图需要高度定制视觉风格拖拽工具有现成的模板库比手写文本更出效果。我的处理方式是把二者当作用途互补的两类工具正式资产进文档库、受版本控制、用于长期维护的图一律走文本化方案临时草稿开会讨论、一页纸讲idea、个人笔记用拖拽或手绘都随意。分清场景工具之争也就自然化解了。4. 一套可以直接落地的图面规范方向、配色、命名、校验分类学了、工具定了接下来真正拉开差距的是图面规范。没有规范十个人画的图就有十种风格有了规范哪怕画图的人水平参差不齐成品也能保持一致的阅读体验。这套东西不需要多高深关键在于每个元素都有明确的为什么。4.1 方向与布局箭头永远从调用方指向被调用方第一个约定是关于方向的。我最开始没有统一方向规范结果有的图里箭头表示被调用关系有的表示数据流向还有的干脆是和谁通信大家全凭个人习惯。后来团队定了一条死规则凡是不涉及数据流时序的图一律用调用方向作为箭头语义也就是箭头从调用方指向被调用方如果某张图需要表达数据流方向必须在图注里显式说明不允许默认混用。布局方向上也定了偏好核心入口在左核心出口在右支持性组件放中间下方。这样做之后读者看图的时候视线是稳定的——第一眼往左找入口第二眼顺着方向往右扫很快就建立起路径感。评审效率提高得非常明显因为大家不需要反复确认这个箭头到底是谁调谁。4.2 颜色语义颜色不是装饰是信息编码配色是最容易翻车的地方。很多人画图时按我喜欢什么颜色来涂结果满屏红红绿绿信息层次全被颜色毁掉了。我把颜色收回为一种严格的信息编码核心链路的主节点用一种主色外围依赖用另一种颜色可选/待定组件单列一种颜色已废弃或计划下线组件再单列一种颜色。这套做法还引出了一个小工具在 CI 校验环节里加了一条颜色检查规则扫码包里的文本源文件统计用到的颜色枚举是否超出约定集合超出就报错。这样就从人治改成了机治。大家一开始觉得连颜色都要管太苛刻了后来看图速度上来了反而没人抱怨了。4.3 命名、编号与图例让每张图成为知识库的坐标命名规则同样重要。当时我定下来的规范是文件命名用图类型-业务域-序号三段式例如seq-order-L1表示时序图-订单域-链路编号 L1图中每个元素都必须有可读的名称禁止出现服务 A节点 B这种临时名。元素名称要么跟代码仓库里的服务名完全一致要么在名称下面用括号标注来源。图与图之间的编号也要贯通。前面的章节里提到的链路编号体系在这里补完每条核心业务链路都有唯一编号编号可以跨图引用。这样一张时序图里的L1在架构评审文档里被引用时读者按编号就能定位到对应的图。时间长了这套编号就成了团队内部的共同语言。图例是另一个容易被忽略的细节。每张图我要求在左上角放一个小图例区至少说明箭头语义、主要颜色含义、边框类型的区别。不要觉得图例多余——我见过太多图画的人心知肚明看的人一头雾水图例就是那道最省力的沟通桥。4.4 自动化检查清单把规范变成命令规范光写进文档是没有用的必须靠工具强制执行。我最终在流水线里挂了五类检查这也是整个 DIAGRAM-DESIGN 项目里投资回报率最高的一部分语法检查所有文本绘图源文件必须能被渲染器解析解析失败直接构建失败。元素命名检查不允许出现服务A测试1这类临时用名。颜色检查只允许使用规范中约定的颜色枚举。文件路径检查图必须落在预先规划的分类目录下不允许胡乱堆放。引用完整性检查文档中引用的链路编号如L1必须在图表索引中存在避免引用了一张不存在的图。这些检查用简单的脚本就能实现。与其天天开会强调大家要遵守规范不如让合并请求在检查失败时自动打回把规范变成硬约束。团队里没有一个人因为检查太严格而抱怨恰恰相反大家觉得省去了很多来回扯皮。5. 从十张乱图到可维护视图库一次完整的改造实录规范和方法论都有了接下来讲一段真实推进过程中的完整套路。概括起来就是先盘点分级再逐张重画最后把图嵌进日常研发流程里。5.1 第一步盘点与分级先重画高价值的图拿到一堆存量图不要埋头一张一张全重画那会把团队累垮。我当时先把所有图分了三类A 类是核心资产图包括系统上下文图、下单主链路时序图、核心模块依赖图、线上部署拓扑图。这类图是平时使用频率最高、影响面最大的优先重画精度要求最高。B 类是重要但不紧急的图比如次要业务域的时序图、工具链流程图。排在第二批。C 类是历史遗留的、已经描述废弃逻辑的图直接归档标上已废弃见 XX 图不再维护。分级之后团队的工作量一下子清晰了。A 类图约十张用两周时间逐张过完B 类图穿插在日常迭代里逐步替换C 类选定一个时间节点统一做清理。没有这一步单是先改哪张就能争论半天。5.2 第二步逐张重画时的三个对照每一张图重画时我不允许画图的人只对着旧图美化而是要求做三个对照对照代码仓库里的真实实现对照生产环境的部署与中间件清单对照线上监控面板实际存在的调用关系。三个对照做完这张图才算有资格进入新版本文档。这套流程执行下来很多图已经不是重画而是重建了。以某条核心下单链路为例旧图里画的是订单服务直接查库存但代码里实际是先走缓存、缓存未命中才回源数据库并且中间还隔了一个库存领域服务。画完对照之后新图和真实系统终于站在了同一条线上。后来新同学按着图排查线上问题第一次对着图直接定位到了瓶颈节点这是我印象最深的一次正反馈。5.3 第三步让图在研发流程里活起来光有一批静态的新图还不够最怕的是半年之后图又老回去了。所以我把图表维护嵌进了正常的研发节奏每次涉及服务拆分、接口变更、依赖调整的迭代开发同学必须在同一个合并请求里更新对应的图架构评审的准入条件里也加了一条无图不评审。这个规矩最开始是最难推的因为大家觉得增加了工作量。但坚持三个月后效果非常明显——架构文档库里的图始终和代码同步评审会上的讨论不再浪费在图不对的纠错上而是集中在真正的架构取舍上。对一个中等规模的团队来说这种图的更新速度和代码同步带来的效率复利远远大于当初画图付出的成本。6. 后半程才是真正的坑多人协作、自动校验与防旧机制前面讲的都是怎么把图画出来但这个项目里最深的体会是画图只占两成精力维护占八成。后半程踩的这些坑才是 DIAGRAM-DESIGN 真正值钱的部分。6.1 多人协作时文本冲突比你想象的频繁转文本化方案之后图源文件确实能进 Git 了但多个分支同时改同一张图还是会产生冲突。有一次我和另一位同事分别改两张时序图都动了同一个生命线的位置合并时冲突标记让渲染器直接罢工。处理这类问题常见的几种方案各有取舍最简单的是在约定的分支规则里做一人一图核心链路图不要两个人同时改再进阶一点可以把公共的组件定义抽成可复用的片段图本身只负责引用这样改公共定义时只冲突一处最理想的是让团队习惯在文本图上做小幅高频变更避免憋一个超大多分支合并。我们最终选了一人一图 公共片段抽取的组合冲突率降到了可以接受的频率。但说句实话文本图的冲突永远存在不可能完全消除。重要的是不要把冲突看作事故而是把它当作两个人确实对同一个结构有不同理解的信号顺便触发一次评审对齐。6.2 自动校验的真正难点是语义校验语法和颜色这些结构检查容易做难的是语义校验。什么叫语义问题一张架构图里画了 10 个服务但代码仓库里只找得到 9 个——这种不一致靠静态检查是看不出来的。我试过在流水线里挂一个脚本去解析文本绘图源文件里的服务名再和代码仓库的模块列表做匹配跑不通的服务名直接告警。这个脚本不算复杂但对团队帮助很大因为它把图与代码同步这个要求从纯靠自觉变成了机器可查的指标。不过我也要提醒一句自动校验不是万能的它只能查可形式化表达的问题像这条链路的依赖设计是否合理这种问题永远需要人来评审。工具负责守住底线人负责提升上限。6.3 防止图再次腐烂的手段设立图管家角色最后一个经验也是我觉得最有复制价值的在团队里指定一个图管家角色。这个角色不一定要全职可以由熟悉工具链、理解架构全貌的资深同学兼任。图管家的职责不是自己画所有图而是维护图表目录结构、更新规范文档、审核合并请求里的图表变更是否符合分层与命名要求、定期抽查全量图与代码的一致性。图管家机制本质上是用明确的职责归属来代替人人有责等于人人无责。团队里其他成员不需要操太多心遇到拿不准的图表设计问题知道找谁确认这比在 Wiki 里写一百条请遵守规范的废话都有用。这也是我在这套图表体系跑了一年之后觉得最值得保留的一项机制性设计。回头总结我自己的体会图表设计最大的瓶颈从来不是画图技巧而是图的信息治理。想清楚每张图该讲哪一层的事用文本化工具把它纳入版本管理用规范约束图面表达再用机制防止它变质这一套组合拳打下来任何团队的图表资产都能从一次性摆设变成越用越值钱的知识底座。如果你也打算做一次 DIAGRAM-DESIGN 式的图表治理建议从最小的 A 类图开始试点跑顺一条链路、一个域的图再逐步铺开。千万别想着一步到位图表治理是一场持续迭代的事。
