架构图工程化：用文本化描述与自动化管线终结图表腐烂

1. 图表腐烂问题在技术项目里为什么会反复出现说一个我在很多团队里都见过的现象项目启动时架构师画了一张漂亮的架构图大家惊叹、鼓掌然后这张图被扔进 Wiki 或者文档库里前三个月还有人打开看半年后里面的服务名字和项目实际的命名对不上了一年后连画图的人都说不清这张图想表达什么最终所有人都默契地绕开它凭记忆和老同事口述了解系统。这不是个别团队的纪律问题而是绝大多数技术项目的常态。我在自己负责的项目中做过一次统计一个维护了两年多的系统文档目录里躺着 40 多张图其中只有 7 张能勉强对应到当前代码结构剩下的全部处于“曾经有价值、现在只能考古”的状态。最讽刺的是没人愿意删掉它们因为删了总觉得缺了什么留着又没人维护。所以当我接触 diagram-design 这个概念时我首先想到的不是它有没有好看的模板而是它能不能解决图表领域最根本的两个问题图表能否跟随代码持续演化以及图表能否被团队像审查代码一样严肃对待。前面这个问题指向技术选型后面这个问题指向工程规范两者缺一不可。如果你的团队现状是“图都是白板照片和临时工具截屏”那么你真正需要的不是一款更好用的画图软件而是一整套把图表当作工程产物来管理的思路。这篇文章我就围绕 diagram-design 展开把我这两年在不同项目里验证过的方法、工具和踩过的坑一次说清楚。我会按照这个顺序来聊先从图表腐烂的根源说起因为不搞清楚你画的那张图为什么必然过期换任何工具都白搭然后把工具选型这件事讲透给出不同场景下我实际用下来最顺手的组合接着分享一套能落地的图表设计规范它保证的是“让图从一开始就不容易腐烂”再往下是自动化管线让图表跑进 CI、参与代码评审这是 diagram-design 工程化的关键一步最后聊几个大图治理的技巧和真实项目里绕不开的坑。如果你正在维护一个有一定规模的技术项目或者你负责团队的技术文档建设这篇文章应该能给你一些可以立刻用起来的东西。即便你只是刚开始接触 diagram-design照着后面的步骤一步步来也能少走不少弯路。2. 那些画完就没人维护的图问题到底出在哪里很多人以为图表过期是因为团队不重视文档我不完全同意这个判断。我观察下来图表腐烂几乎是必然结果它由三个结构性问题共同导致。2.1 图形化信息天然比文字更难感知“过期”代码有一个其他东西无法替代的优势它每时每刻都在被机器执行一旦代码和需求不匹配编译失败、测试报错、线上事故问题立刻暴露。文字文档稍微差一点但还能通过搜索、版本对比、变更历史去感知新旧。但图形是二维信息人眼识别一张图是否过期的成本非常高——你得逐条核对图里的每一个组件名是否还在、每一个依赖关系是否真实存在。我见过一个非常典型的案例某系统的架构图里有六个微服务实际代码里已经拆成了九个其中两个被合并掉了。这张图看起来依然“很完整、很专业”每一个方框和箭头都画得很工整但它的每一处细节都在撒谎。读图的人如果没有同时在脑内加载一份最新的服务清单他根本发现不了问题。这就是图表跟代码最大的不同代码挂了会报错而图和真实系统不一致时不会给你任何反馈。2.2 图表工具的工作流天然脱离代码变更流程想一想大多数团队画图的场景架构师在某个工具里画完图导出 PNG粘贴到文档里。这个链路上存在两个巨大的断点——画图工具里的源文件和代码仓库没有任何关系源文件本身也无法参与 code review。我在评审一个同事的架构图时经常遇到这种情况他改了一个服务的依赖关系重新导出了一张图片但在 diff 视图里我只能看到整张图片像一块没有缝隙的砖头一样被替换了。没有人能在这种 diff 里看出他到底改了什么于是同事养成了习惯改动之后在群里喊一声“我更新了架构图”然后大家就默契地接受这个变更。这个场景在代码评审里完全不可接受。如果一份代码的 diff 长这样任何团队都会拒绝合并。但图表长期享受着“免审查”的特权因为它们不在代码变更的链条上。2.3 缺乏可验证的“图即代码”基础还有一个深层次问题即使你把画图源文件放进了 Git 仓库如果它是以某种二进制格式保存的依然没法做真正有意义的 diff。很多绘图工具的源文件本质上是一份序列化后的 JSON 或者二进制块一行坐标偏移就能让整个 diff 面目全非。所以我在前两年逐渐淘汰了“鼠标拖拽式”的绘图工具作为主文档工具转而全面拥抱文本化图表描述语言。这类语言的核心思路是你不需要关心坐标和连线怎么画只需要用结构化的文字描述“有哪些节点、节点之间是什么关系”渲染引擎自动完成布局。这就是 diagram-design 真正有意思的地方——当图表源文件变成纯文本它就能享受代码世界的一切基础设施Git 版本管理、Diff 审查、多人并行开发、CI 自动校验。我把团队从腐烂图表中拉出来的第一步就是把所有核心图表从“二进制画布”迁移到“文本描述”让每一张图都成为仓库里一份可追踪、可评审、可自动检查的文件。3. 工具链选型对比拖拽画布、文本绘图还是代码原生绘制关于绘图工具网上能搜到一堆推荐清单但大多数文章只是在罗列功能很少帮你分清这些工具在工程化链路里各自的生态位。我在不同阶段用过几乎市面上主流的绘图方案这里直接给大家一个我总结的选型框架以及我实际在工作里采用的组合。3.1 四类工具的本质区别市面上的图表工具按工作模式可以分成四类它们的工程化能力是递进的类型代表核心优势核心局限工程化程度画布拖拽类Figma、draw.io、Excalidraw上手快自由度高适合快速表达想法源文件难以 diff无法自动化校验低在线白板类Miro、Boardmix多人实时协作适合头脑风暴展示性强严肃文档能力弱版本混乱低文本描述类PlantUML、Mermaid纯文本描述能进仓库能 diff复杂布局表达能力有限定制样式较麻烦高代码绘制类Graphviz、D2自动化布局能力强适合数据驱动生成图学习曲线较陡审美需要二次加工高其中前两类适合“想清楚”的阶段适合画讨论稿、方案草图后两类适合“定下来”的阶段适合作为文档资产长期维护。很多人恰恰搞反了在方案还在反复摇摆时他们花大量时间在拖拽工具里把图美化得一丝不苟等方案定了该把这套图作为正式文档沉淀了却依然停留在画布工具里导致后续每一次变更都无法追踪。3.2 我最终留下的组合我现在的技术文档架构里图表的生成方案分三个层级每个层级都有自己的使命第一层讨论期用 Excalidraw。它足够轻打开网页就能画画出来的图自带一种“手绘感”没人会把草稿当正式文档反而促进了讨论氛围。讨论结束、方案确认后这张图的历史使命就结束了我不会刻意保存它。第二层架构图、部署图等静态结构图用 PlantUML。我选择它的核心原因一是文本描述非常紧凑写起来快二是它对序列图和部署图有很强的内置支持三是有成熟的 CI 集成。虽然它的默认审美被人吐槽不少但配合主题配置后效果完全够用后面我会讲。第三层节点多、关系复杂、需要自动布局的图用 Graphviz 的 dot 语言。Graphviz 的布局引擎是几十年的老牌技术处理几十个节点的依赖关系图依然稳定。我主要用它来生成服务依赖图、数据流向图这类“信息密度高但构图要求不高”的场景。在文本绘图工具之外我还会在标准文档站里内置一个基于 HTML/CSS 的手工绘图区用于处理少数“高度定制视觉”的场景比如对外发布的产品架构宣传图。这类图讲究视觉冲击力和品牌一致性自动化工具确实做不到但也正因为视觉要求高它们一般是低频维护的腐烂风险反而没那么大。3.3 为什么我不用“更漂亮的”在线设计平台来管理架构图这里我得说反话。在线设计平台、协作白板这类工具在“绘制”和“演示”这两个环节确实体验极佳甚至比文本绘图工具好看一个量级但它们在长期文档管理面前有几个致命伤图表源文件和代码仓库是隔离的很多平台甚至连版本历史都做得模模糊糊想精确找回“三个月前那版”非常痛苦。无法在代码评审中对图进行有意义的逐行 diff 审查。团队里任何一个人改了一处依赖关系别人看到的只是一个“更新后的图片”无从知道改了什么、为什么改。API 能力普遍有限你很难在 CI 里自动触发重新渲染也很难对图片进行自动化内容校验。免费版对文档数量、成员数量、导出清晰度都有限制一旦团队规模上来功能收费就是一笔不容忽视的开销而文本绘图工具是零成本无限量。所以我的态度很明确白板和在线设计工具用于“讨论和演示”文本绘图工具用于“资产沉淀”。如果你把两者混为一谈团队文档库迟早变成图片坟场。4. 为团队定义一套可持续演化的图表设计规范工具选型解决的是“用什么画”规范解决的是“画出来的图能不能让全世界看懂”。我在推行 diagram-design 的过程中发现大部分团队连最基本的图表命名规范都没有更别说统一的视觉约定。一套好的图表规范不需要覆盖所有细节它应该回答四个问题图中的要素如何命名、分层边界画在哪、连线怎么表达语义、配色有什么固定含义。4.1 命名规范让每个节点在图上被无歧义识别我最先定义的规范是节点命名。节点名称必须和代码仓库里的真实标识保持完全一致——服务名就写服务在注册中心的名称数据库就写连接配置里的库名外部依赖写域名或系统名。绝不写“用户服务”这种口语化名称因为口语名称和代码标识不可能一一对应换一个人来读就要猜。对于图中的文字说明我要求必须使用主动语态和可证实描述。比方说一个节点旁边写“处理支付请求”是可以的因为读图的人能拿着这句话去代码里找对应的 Handler但写“承载核心业务”就是垃圾文字它无法被验证也没有任何实际信息量。我还对颜色做了一套固定映射核心业务组件用蓝色系基础设施组件用灰色系外部系统用橙色系有风险或待重构的组件用红色虚线标记。这套规则贴在文档站首页每一个画图的人都得遵守。视觉风格统一之后团队里的任何人拿起一张陌生的架构图第一眼就能按颜色定位信息的优先级。4.2 分层规范单向依赖是架构图的最低底线架构图最常见的腐烂原因其实是分层混乱。很多图把所有组件画在同一张大画布里服务调用关系像蜘蛛网一样交织根本分不清上下游。我的做法是强制分层。以最常见的微服务架构为例我把所有节点压缩到最多四个泳道接入层、应用服务层、数据层、外部依赖层。每一层用一个横向矩形框框住所有连线只能从上往下走如果出现下层调用上层的反向依赖要么是画错了要么是真的存在架构问题——而这种问题正是架构图应该暴露出来的。分层规范还有一个隐性好处的它能倒逼真实性。当你把所有服务填进这四层时一个在架构上很混乱的系统会被直观地显现出来你在图上看到的“一团乱麻”其实就是代码里真实存在的耦合。此时图不再只是文档而是架构治理的体检报告。4.3 文字描述规范图上写什么话、不写什么话项目里我还遇到过一个问题图上的文字说明特别多每个节点都挂了一大段解释。这看起来是在“认真做文档”实际上反而让图没法读——一张图塞满了文字人眼根本抓不住重点。我的规范是图上只保留能帮助理解结构的最小文字信息更详细的解释写进节点对应的同名文档中。如果一张图的文字量超过节点数量的两倍说明它正在从架构图退化成说明书应该分拆。这里还有一个特别容易踩的坑在节点描述里写“计划中”“待定”这类带时效性的词。图的腐烂往往就是从这种字眼开始的——上线三个月后没人还记得要去把“计划中”改成“已上线”于是这张图就从“未完成”永远停留在了“计划中”。我的建议是不确定的内容不上正式架构图只在讨论期草稿里出现。5. 把图表接入 CI/CD 的自动化管线让腐烂成为不可能规范讲得再好如果完全依赖人的自觉最终还是会松掉。我在自己负责的项目里真正让图表焕发新生是因为把图表接进了自动化的链路——从代码入库到可视化渲染再到检查发布全程不依赖人工。5.1 仓库结构让图表源文件和代码活在同一个地方第一步是在代码仓库里划分一个专门放图的目录。我把所有文本绘图源文件放在 docs/diagrams/ 下目录内按子系统分子目录。文件名与图内容强相关例如 payment-service-architecture.puml、data-pipeline-dependency.gv。这一步看起来简单但它触发了三个连锁反应第一图和代码共享同一个 Git 历史代码变更和架构图变更可以在同一个 commit 里被审查从机制上杜绝了“改了代码忘了改图”的可能第二所有图文件可以被 IDE 直接编辑不需要打开额外的绘图工具心智负担降低很多第三任何人都可以发起修改架构图的 PR就像改代码一样。5.2 自动渲染与发布一套命令从源文件到在线文档源文件放进仓库之后下一步是自动渲染。我的做法基于 Docker 镜像部署一套文档构建流水线每当我们往 main 分支合并新的 commitCI 作业会自动拉取仓库里所有 PlantUML 和 Graphviz 源文件执行渲染命令生成 SVG 和 PNG然后嵌入到文档站点中。渲染命令也支持本地执行我通常在提交前运行一条 make diagrams 命令确认所有源文件语法正确、能正常出图。我放一个简单的 Makefile 示例方便你理解整个流程的骨架# 本地渲染 diagrams diagrams: docker run --rm -v $(PWD)/docs/diagrams:/diagrams \ rjlutz/plantuml-cli:latest \ java -jar /opt/plantuml.jar -tsvg -o /diagrams/out \ /diagrams/**/*.puml docker run --rm -v $(PWD)/docs/diagrams:/diagrams \ adityasharma/dot:latest \ dot -Tsvg /diagrams/data-pipeline-dependency.gv \ -o /diagrams/out/data-pipeline-dependency.svg值得说的是我所有的产出都用 SVG 而不是 PNG。SVG 是矢量格式在文档站里放大不糊同时体积比 PNG 小加载快。如果担心旧浏览器兼容问题可以在渲染时同时输出一个 PNG 作为降级方案。5.3 内容自动化校验在 CI 里抓住不合理的依赖关系文本化最大的红利是可以对图的内容做自动化断言。我在 CI 的校验环节里加了几个自定义脚本用来抓“结构性错误”第一个校验是节点命名校验。脚本会扫描所有 .puml 文件里定义的组件名和注册中心的服务列表做对拍发现图上写了但实际不存在的服务名直接报错不允许合并。这个校验一瞬间解决了文档的“考古感”因为任何失效的服务名都会在代码评审阶段被机器挡住。第二个校验是依赖方向校验。我在脚本里定义了四个分层的白名单依赖规则任何从数据层指向接入层的反向依赖都会被系统标红并给出警告日志。这不是死板地阻止你画这样的图而是在提醒你这一条反向依赖要么是图漏画了中间的调用链要么是代码存在循环依赖两种情况都值得在评审会上过一遍。第三个校验是领接矩阵的单调性如果 A 组件依赖了 BB 又依赖了 C那么图上不该同时出现 A 直接指向 C 的连线。这种“跳过一跳”的画法容易掩盖真实链路我让 CI 自动检测并建议改为 A → B → C 的分步表达。这些校验规则加起来只有几百行脚本却极大地改变了团队对架构图的态度——图的变化不再是“一条静默的改动画”而变成了“一次能被讨论的变更”。5.4 Git Diff 审查用文字 diff 取代整图替换当所有图表源文件变成纯文本后Git 的 diff 机制第一次能对图生效。团队评审一个架构变更时不再需要对着两张截图来回切而是能直接看到源文件里的增删改 payment-service-architecture.puml - [Order Service] - [Inventory Service] : 扣减库存 [Order Service] - [Stock Service] : 预占库存 [Order Service] - [Warehouse Service] : 校验发货仓库这个 diff 的价值在于评审人不再仅凭自觉去猜测“图改了没改、改了哪里”所有变更都清晰可见。和代码评审合入同一个 PR 之后架构图的修改也就正式纳入了团队的质量体系。我实际观察过推行这套机制后的团队变化——三个月后几乎所有核心图都跟代码保持了一致性因为已经不存在“改了代码忘了改图”的温床了。6. 大图和复杂场景拆图、分层聚焦与关键细节取舍自动化管线解决的是维护问题但当一个系统的规模足够大时你最先面临的是“一张图画不下”的问题。我处理过一张包含 40 多个服务、200 多条依赖线的巨型 PlantUML 源文件渲染出来的 SVG 有 2 米宽任何人都不可能在一屏内看完它更别谈从里面获取有效信息了。6.1 拆图原则一按调用链路切分不按团队组织切分很多团队喜欢按组织架构拆图——支付组画一张支付架构订单组画一张订单架构。但这样拆出来的图之间有大量重复的公共依赖而且技术上没法保证单向依赖。我采用的拆图逻辑是按关键调用链路和边界上下文切分。每个边界上下文内的图只画这个上下文的内部组件以及它依赖的下游上下文的泛化表示。例如订单上下文只画出它依赖的外部接口名不在图里展开支付上下文内部有哪几个服务的细节。如果要看支付上下文的内部实现有另一张独立的图与之通过超链接关联。这套做法叫“分层聚焦”第一眼读者看到的是宏观拓扑有需要时再进入第二层看细节。它比一张巨图的表达能力更强也更适合文档站的导航结构。6.2 拆图原则二系列图要共用图例与模块编号拆成多张图之后图与图之间的信息关联就成了新问题。我在文档站里给所有图配了统一的图例页在源文件层面把所有公共组件提取为公共的 PlantUML 封装例如统一的数据库图标、缓存节点、MQ 节点避免每一张图里都在重复定义样式。更进一步我给每个组件分配了一个稳定的模块 ID例如支付服务是M-03。任何图里出现这个组件都带上M-03标签。读者在不同图里看到相同的 ID就能确定是同一个组件不会因为图标画法不一致而产生误认。6.3 时序图在复杂交互场景里的特殊处理结构架构图拆完还有一类场景值得单独提一下——时序图。时序图描述的是多个模块之间在一次完整业务请求里的消息顺序它的维护成本比结构图更高因为每新增一个下游依赖都可能牵动多条消息线。我在用 PlantUML 处理时序图时会刻意做一件在很多教程里看不到的事情用分组箭头group把一次请求括起来禁用自由散落的箭头描述。这样做的原因是对时序图做代码 diff 时开发人员能看到“这次提交为支付回调流程新增加了一个对账请求”而不是在几十条消息线里去大海捞针。我还要求时序图中每个参与者后面的说明文字里写上相关联的接口签名或者消息队列 topic 名。这个细节让时序图的读者可以无缝衔接到 API 层文档而不需要再去搜代码。7. 真实项目里我踩过的六个坑与应对方法工具链和规范看起来都挺顺但实际推行 diagram-design 的过程中我碰到了不少在文档和教程里不会写的问题。这些坑如果你不提前预防大概率也会撞上。7.1 中文字体渲染成豆腐块的坑PlantUML 对中文的支持依赖环境里的字体文件我在部署 CI 渲染容器时一开始没安装任何中文字体所有中文节点名渲染出来全是方框。这个问题不只是 CI 有——团队里任何一个没有安装特定字体包的同事本地渲染也会乱。解决办法是容器基础镜像里安装fonts-noto-cjk和fontconfig并且在 PlantUML 配置里显式指定中文字体。我在 Makefile 里加了一行docker run --rm -v $(PWD)/docs/diagrams:/diagrams \ -e PLANTUML_FONTSansMono \ --entrypoint sh рlANTUML-image \ -c apt-get update apt-get install -y fonts-noto-cjk dot -Tsvg ...这种环境问题最烦人因为你本地百分百正常一到 CI 就坏。建议从一开始就把“中文字体验证”加进 CI 校验里避免后期偶发。7.2 自动布局不稳定导致 diff 噪音太多Graphviz 和 PlantUML 的自动布局算法在大多数情况下能给出合理结果但当图里有新增节点时它可能会大幅度改变其他节点的坐标位置导致即便只改了一个节点整张图的布局都变了。这会让前方代码评审的氛围变得很微妙——丁点改动看起来像翻新。预防办法是尽量减少同一个源文件里的节点数量。如果一个图超过 25 个节点就考虑拆图通过超链接串联。同时对 Graphviz 的图我给每个子图设置了固定 rankdir并尽量用ranksame约束同一层节点的相对位置降低布局位移概率。7.3 SVG 体积爆炸导致文档站加载卡顿文本绘图工具生成的 SVG 通常带大量嵌套的g元素和样式属性当节点达到几十个后SVG 体积可能膨胀到几 MB文档站首页加载时浏览器直接卡死。我的解决方法是在渲染管线里增加一道 SVG 压缩优化步骤用 svgo 这个工具做路径优化和元素清理。优化后大部分 SVG 能压缩掉 60%-80% 的体积加载速度立刻恢复。建议你把压缩也放进 Makefile而不是每次手动跑。7.4 多人并行修改同一个图文件的合并冲突代码能并行开发是因为一行一行 diff 很精确但文本图表语言的 diff 同样是按行的两个同事同时在一个大文件的不同区域加节点很容易产生合并冲突而且解决起来比代码更头疼——因为删掉一行坐标定义箭头就断了。我给团队定的规矩是一次性修改架构图的 commit 尽量不要和代码功能 commit 混在一起且每次改图尽量小步快跑。这听起来像废话但在实践中是减少冲突最有效的办法。7.5 过度追求“把每张图都自动化”的误区不是所有的图都应该被工程化。我一开始犯过一个推动过度的问题把团队里的所有图包括一张讨论用的手绘流程草图都想方设法导进 PlantUML 重画一遍。结果同事们花了很多时间在微观排版上产出却远不如直接在草稿纸上讨论来得快。后来我明确了一个原则只有需要长期维护的、面向系统交付的图才纳入 diagram-design 工程化管线一次性讨论用的图随意、自由、尽快画完就扔。这个原则贯彻之后团队对图表的抵触情绪显著降低因为大家意识到“工程化”不是要增加画图负担而是让真正值得沉淀的图获得体系的保护。7.6 文档和图表两套系统脱节最后一个坑发生在文档结构的集成层。很多团队文档站里图表是一个独立的菜单跟技术文档是割裂的。架构图归架构图接口文档归接口文档读文档的人很难在一篇讲支付链路的文章里顺手看到对应的架构图。我的解决办法是在每篇技术文档的标题开头通过自动渲染插入相关图表。实现机制很简单文档站构建时扫描文档里的元数据diagram-refs字段把指定的图渲染结果内嵌到页面中。这样读者在阅读文字说明时身边永远有一张“此刻讲到的架构”上下文的关联强度就完全不一样了。8. 我在实际项目里的最终体会把 diagram-design 从一句口号变成一个可运行的工程体系我前后花了大半年踩了上面这些坑最终的收获远不只是“文档变好看了”这么简单。最直观的变化是团队在代码评审时多了一把叫“架构图 diff”的尺子。过去只有代码改到耦合严重时大家才意识到架构烂了现在架构图的变更会先在评审里暴露问题——比如这张图新增了一条本该不存在的调用链就是一次提前的架构健康检查。另一个收获在知识传递上。新同事入职时不再是丢给他一堆过期的文档让他自己考古而是从仓库里拉出最新渲染的架构图跟着图的调用链去读代码。这个过程非常顺畅因为图上的每一个名字都能对到真实代码几乎不存在“图上写的是一个代码里是另一个”的认知断层。如果你打算在团队里也引入这套思路我给你三条最关键的经验它们比任何工具配置都重要。第一先从最重要的两三张核心架构图开始改造不要一上来就全面铺开等团队尝到版本管理和 diff 审查的甜头后再渐渐扩大范围。第二底层源文件一定要用文本描述语言不要贪图一时的美观沿用二进制画布。第三把自动化校验当成第一公民宁可牺牲一部分灵活度也要保证这里的“图”不可腐化。最后分享一个我自己养成的小习惯每次提交代码之前顺手看一眼受影响子系统的架构图变没变。没变不代表你一定没改架构但至少提供了一个提醒——如果你动了服务之间的调用关系架构图几乎一定有变化。这样慢慢坚持下来你会发现自己开始像重视代码一样重视每一张图图和系统从此不会再分道扬镳。