先交代一下背景。我手头这个项目叫diagram-design听起来很普通就是图表设计四个字但它解决的是我在团队里被反复折磨了大半年的老问题架构图、流程图、依赖图永远和代码对不上。事情的起因很常见。一次技术评审会上新来的同学指着白板上的流程图问我这个图上写的消息队列代码里好像已经换成了别的中间件图是最新的吗我低头看了一眼版本记录的修改时间——上一次更新是十一个月前而系统已经迭代了三个大版本。全场沉默。不是大家不想维护而是那张图存在共享盘的某个无名字文件里画它的人早就换了项目。那一刻我开始认真思考一个问题为什么代码可以版本化、可 review、可自动化构建而架构图做不到于是就有了 diagram-design 这个项目——把所有图表当成代码工程来管理用文本定义图元用自动布局引擎排版用 CI 自动渲染让图跟着代码走而不是靠人肉记住哪张图还活着。这篇文章不聊概念只聊实操为什么我把架构图定义成工程资产选型时对比了哪些方案内部管线怎么拆落地时踩了哪些坑以及一个两周迁移的真实复盘。无论你是被图又过期了逼疯的技术负责人还是想规范组内文档的架构师它都值得你花几分钟看完。1. 为什么要把架构图当成一个代码工程来管理1.1 手绘图在评审会上掉链子的那几次我先说说手工绘图模式下最常见的几个死法。第一种是文件失联。图存在共享盘里文件名常常是最终版-v2(真的最终)-new.drawio这种等下次要改的时候打开一看内容还是上个季度的。第二种是单点持有。整个团队只有某一个同学会改这张图他休假图就冻结他转岗图就失传。第三种是改图成本大于画图。系统迭代时架构图理应跟着变但一张大图要手动挪十几个框、重画七八条线前后浪费两个小时最后大家干脆放弃治疗。我自己做过一次粗略统计团队维护的三十多张图里超过一半在图注时间上落后于代码变更只有不到三成能被称为勉强可用。这不是某一个团队的惰性而是工具链的错——传统绘图工具根本没有把版本变更记录自动检查这些最基本的软件工程能力当成设计目标。1.2 图的本质也是代码资产代码工程的核心能力是什么版本控制、变更审查、自动化校验、可追溯历史。把这些能力用在图上就是我常说的图即代码思维。diagram-design 项目把这套思维落成了三点。第一图有数据层节点、边、分组都是结构化定义不依赖鼠标拖拽的绝对坐标第二图有表现层布局由算法决定样式由主题统一管理人可以干预的是语义分组而不是这个框距离那个框 37 像素第三图有验证层构建时自动检查孤立节点、重复关系、空标签有问题直接让流水线失败。这样处理之后架构图就和业务代码站在同一个起跑线上了它住在 Git 仓库里每一次变更都有 diff每次合并都要走 review渲染由 CI 完成永远只有最新版。评审时打开链接看到的图和代码是同一时刻的快照不会再出现图上说的是旧的代码跑的是新的这种尴尬。1.3 这个项目适合谁来用如果你符合下面任意一条diagram-design 这套思路值得借鉴你所在的团队有大量系统架构图、调用链图、部署拓扑图且正在饱受图过期之苦你们每次评审都要浪费时间确认到底哪张图是对的团队里有同学愿意用敲键盘代替拖鼠标来画图你们已经接受了文档即代码docs-as-code的工作方式只想把图的环节补齐。它不适合的场景也有比如你只是临时画一张一次性示意图发给同事不需要长期维护那用绘图软件拖两下反而更快。这个项目解决的是需要长期活在代码仓库里的图目标清晰适用场景同样清晰。2. 选型实录四个代码化绘图方案我为什么没全选2.1 主流方案的横向对比代码化绘图社区里其实早有一堆成熟工具关键是选型时容易眼花缭乱。我把实际试用过的四个方向整理成了对比先看表再解释方向学习成本复杂图布局能力中文渲染主题定制CI 脚本化社区生态文本图表脚本Mermaid 这类低中流程图上佳较好需开启自动换行中成熟活跃经典图描述语言Graphviz / DOT中高强有向图非常稳一般依赖环境影响中成熟老牌稳定现代声明式绘图语言D2 这类低强默认布局好看好高成熟但使用者少快速成长通用在线绘图软件导出的文本格式低弱好低差一般先说明第四类通用在线绘图软件导出的文本格式我没有细测因为它的定位和代码化根本不同尽管能保存成文本但结构里充满了坐标点信息本质上还是在拖框子。真正值得纠结的是前三个。2.2 我的选择和取舍逻辑diagram-design 最后的主渲染器选了Mermaid 这类文本图表脚本原因是团队认知度最高——组里有几个同学已经会写基础语法不需要额外培训就能上手。我选它当主力还有一个考虑它的 flowchart 语法足够表达大多数微服务关系图、流程图、时序图内置主题也能满足日常需要。但只赌一个方案是不够的。我把Graphviz / DOT作为复杂有向图的兜底当图里节点超过五十个、依赖关系超过一百条时Mermaid 的布局引擎会开始力不从心而 DOT 的图布局算法dot、neato、fdp在这种场景下极其稳定。为此我在项目中留了一个复杂图目录专门放.dot文件。D2 这类现代声明式语言我也试过语法确实清爽默认出图效果可以说是三个里最好看的。但当时它的主题体系还不够成熟遇到团队品牌色调整时需要手写很多样式变量维护成本反而上来了。我的判断是它适合给客户做汇报的示意图但作为团队内部基础设施生态成熟度还差一点。所以它在我这里是一个实验性目录没有进主链路。顺带说一句版本的教训所有依赖都必须锁版本。Mermaid 这类工具的版本升级经常会改变渲染细节如果不锁版本某天合并代码后突然发现所有图连线粗细都变了追根溯源又是一个晚上。2.3 版本管理与多人协作机制选型定了之后真正的工程量在于多人协作。diagram-design 做了三件事第一一图一文件。每个图对应一个源文件.mmd或.dot文件名就是图的唯一标识例如order-service-deps.mmd。产物PNG/SVG可以不入库由 CI 统一生成也可以把核心图静态产物一并提交方便在 IDE 里快速预览——我选了后者因为改动频率低、好处直观。第二把图变更和代码变更绑在同一个 PR 里。如果开发者改了服务的调用关系他需要同时更新对应的图文件否则 CI 里单独的diagram:check会失败。这一步从机制上保证了图不会单独过期。第三视觉回归。关键图比如核心交易链路会维护一张 golden 快照每次渲染后做像素级对比差异超过阈值就提示人工确认。它防的不是内容错误而是主题升级、字体替换这些意外整容——这类问题人工看 diff 很难一眼发现机器反而敏感。3. 管线设计图元定义、自动布局、渲染输出的三层拆分3.1 领域模型把图拆成可组合的图元如果直接打开一张.mmd文件看新人会以为它只是带特定语法的文本但设计时我是按领域模型来组织的。一张图本质上由四类图元组成节点node唯一标识、展示名称、类型服务、数据库、外部系统、消息队列等边edge起点、终点、方向、关系标签调用、依赖、数据流分组group把节点归入某个业务域或限界上下文样式覆盖style override个别节点的高亮色、边框样式用于标注异常或重点。对应到文本语法就是一个这样的结构实际项目中我会把这段存成.mmd源文件flowchart TB subgraph order[订单域] A[订单服务] B[(订单数据库)] end subgraph pay[支付域] C[支付服务] D[(支付数据库)] end A --|读写| B C --|读写| D A --|RPC 调用| C看到没有我全程没有写任何一个像素坐标。我只是表达了订单服务和订单数据库是什么关系支付服务在哪里两个服务之间有没有调用至于这些框最终在画布上如何排布那是布局引擎的事。3.2 布局引擎为什么不能让节点自己长脚这是 diagram-design 项目理念上与手工绘图软件最大的分水岭。手工工具里每个框有绝对坐标拖动一个框旁边的线跟着变形而自动布局引擎负责把关系图计算成坐标图。为什么要自动化因为人工摆坐标在图的规模面前不可持续。五六个框你还能手动调好看三十个框加上交叉连线再手摆就是灾难每加一个节点所有线条可能都要重排没人愿意干。自动布局算法主要依赖 dagre 这类层级布局算法的好处是它会让节点尽量沿层级排布减少交叉保证连线不穿过节点。坏处是它不理解你的业务直觉——比如你想让订单域整体悬浮在画布右上角算法只关心图论上的合理性。应对办法是用语义分组来影响布局。想要某些节点待在一起就把它们放进同一个 subgraph想让两个大域之间少几条交叉线就先建域级边界再在域内建服务级节点。布局引擎会优先按分组聚合再处理组间的连线。我在项目里反复跟团队强调一个原则你永远不要试图通过加不可见节点或者手写坐标来微调位置那是饮鸩止渴。3.3 渲染适配SVG、PNG、可交互单页三种产物图的核心产物我做了三种各有用途SVG主产物。矢量格式缩放不糊适合在 README 和内部文档中直接引用PNG用于 IM 聊天、PPT 嵌入。我会指定渲染宽度比如 1200px并开启字体嵌入避免换台机器字变方框HTML 单文件用于评审和分享。所有内容内联在一个页面里支持鼠标滚轮缩放关键节点加跳转链接评审时大家对着这个页面讨论体验最好。具体的构建命令长这样由 CI 调用npx mmdc -i diagrams/order-service-deps.mmd -o dist/order-service-deps.svg -b transparent -w 1200这里有两个参数值得单独提一下。-b transparent是让背景透明这样图放到深色主题的文档里不会白一块。-w 1200是限定渲染宽度实际测试时发现宽度太小文字容易挤宽度太大超过 2000部分浏览器反而会触发锯齿渲染1200-1600 是比较稳的范围。3.4 目录规范一年后你还能看懂文件在干嘛管线再有条理目录乱成一锅粥也没用。diagram-design 的目录结构花了很大心思最终稳定成这样. ├── diagrams/ │ ├── order/ # 按业务域分目录 │ ├── payment/ │ └── infra/ ├── adr/ # 决策记录比如“为什么改用自动布局” ├── scripts/ # 构建、校验脚本 ├── dist/ # 自动生成的产物通常不入库 └── package.json文件命名我定了一条死规矩必须有意义且自解释。order-service-deps.mmd比1.0-final.drawio好一万倍因为前者在一年后仍然能被任何人理解后者只有画图者本人能猜出大概。每个目录下我会放一个 README写清楚这个目录的图是什么范围谁负责新增图。这事很土但它是整个项目能持续运转的地基。4. 落地阶段最常翻车的四个问题4.1 中文文本溢出看起来是小事翻车率极高我最早吃过最大的亏是中文文本溢出。英文渲染时一个标签十几个字符通常没什么问题换成中文后节点里的字会被挤成两行甚至直接溢出框外。这个问题在本地看 SVG 时还不明显一旦嵌入网页字体加载和环境差异就会让布局崩掉。排查后的处理方案按优先级排列改文案把过长的节点标签拆成短词比如订单服务缓存集群简化为订单缓存短标签是最省事的解开启自动换行在 flowchart 配置里启用文本换行同时给节点设置一个合适的宽度降低渲染字号密度全局主题里把字体调小一档通常能救回一批边缘案例。%% 在源文件头部声明主题和换行 %%{init: {theme: base, flowchart: {wrappingWidth: 100}}}%%这个配置的作用是告诉布局引擎当文字宽度超过 100 个字符单位时再换行而不是一到边界就断。实际效果因人因图而异我的建议是不要追求一个全局完美值而是对个别长文本节点单独用引号包裹并手动指定宽度。长文本节点永远是少数全局配置只解决 80% 的场景。4.2 自动布局变成蜘蛛网语义分层拯救图当一张图的连线超过一定数量自动布局也会失灵画布上全是交叉线像一盘打翻的意面。我的第一反应是布局算法不够强于是去论文里翻各种布局策略折腾了很久才意识到问题根本不在算法。真正的原因是我们的边定义太冗余。举个例子A 服务调用 BB 调用 C这本来是一条清晰的链路但很多人会顺手再画一条 A 到 C 的边表示间接依赖——这就是典型的冗余边。去掉它布局引擎能省下大量交叉计算。我在项目里做了一次链接清理把某张图从 47 条边减到 31 条可读性提升是肉眼可见的。第二个优化是语义分组约束布局。对于跨多个业务域的图我建议先把每条边标注好它属于哪个域间关系然后把域内关系尽量锁进同一个 subgraph。这样布局引擎天然处理成大组之间的主干连线 组内的细节连线层次感立刻出来了。4.3 配色与可访问性图是给人看的不是给色觉正常的你一个人架构图的受众永远包含没有你上下文的人其中一些人的色觉和你不完全一样。我最初设计的图用红绿两色区分正常链路和异常链路结果一位合作同学反馈说他看这两条线根本分不清。你说这算 bug 吗在当时的产品视角里它就是 ciritical 级别的 bug。所以我在 diagram-design 里做了一套可访问性规范不只依赖颜色重要区别同时用形状、线型实线/虚线/点线和颜色三重编码保证文本对比度前景色和背景色对比度至少 4.5:1不追求花哨保证能读给 SVG 加语义信息每个图节点生成title和desc方便读屏软件固定一套主题色色板统一管理下面是实测推荐的一组用途色值说明主文字#1f2328深灰黑对比度极佳页面背景#ffffff纯白最安全主链路#0969da蓝色搭配实线异常链路#cf222e红色搭配虚线分组背景#f6f8fa极浅灰不干扰主视觉这组色值不是从设计平台上抄的是实际渲染时一个个试出来的目的是在好看和高对比之间找一个长期不后悔的平衡点。4.4 CI 构建稳定性渲染失败就该让构建失败最容易被低估的是 CI 接入问题。这里的稳定性不是指渲染引擎崩溃而是指构建链路应该把图的问题当成一等错误暴露而不是悄悄跳过。我踩过的具体坑有三个。第一版本漂移没有锁版本时某天 CI 悄悄升了依赖版本所有图的边距都变了全组人对着 diff 困惑了一上午。现在我把依赖版本写死每次升级单独走一个 PR。第二超时文本图表的渲染依赖无头浏览器冷启动很慢如果 CI 任务默认超时时间是 30 秒大概率不够。我们最终把渲染任务的超时放宽到 120 秒并在脚本里加了--timeout参数稳定多了。第三失败静默早期脚本把渲染失败当作warning打印一下就继续导致图坏了没人知道。现在的规则是校验失败或者渲染失败CI 直接红没有任何商量余地。这段我强烈建议所有想把图表纳入 CI 的团队记住图也是交付物交付物坏了就没有绿色构建。5. 一次真实迁移散乱看板图集如何在两周内规范化5.1 现状盘点36 张图只有 15 张勉强可看理论讲完讲一个我实际带的迁移。某零售业务订单系统团队需要维护的架构相关图有 36 张分布在一个共享白板工具和若干本地文件里。作为对照组先做盘点9 张标注了已废弃但实际上还在被访问12 张内容相对完整但图注时间平均滞后两个月只有 15 张基本可用而可用的定义仅仅是图上的名词在代码里能找到对应。这个数据比我想象的还严重。36 张图里真正值得迁移的不到一半其余全是历史债务。所以迁移第一步不是把图导出来转格式而是砍掉该砍的。5.2 迁移节奏先冻结、再归类、后逐张验收两周的迁移节奏我拆成了三个阶段。**第一阶段第 1-2 天冻结图变更 清点分类。**暂停所有新图的绘制避免边迁移边新增然后把 36 张图按业务域归为五类逐张确认负责人哪怕只是这张图没人认领建议删除。**第二阶段第 3-7 天翻译成源文件草稿。**把值得保留的图逐张转成.mmd源文件。这个阶段不追求样式好看只求语义正确节点、边、分组是不是与当前代码一致。每天抽两个人各认领一批半天翻译、半天交叉 review。转译期间发现的大量图上写了调用但代码里根本没有这个接口的问题正好一并反馈给开发同事确认。**第三阶段第 8-14 天接入 CI 逐张验收。**把所有源文件接入渲染流水线补 golden 快照把构建失败和视觉变化当作硬门槛。验收标准就三条图上每个节点能在代码里找到对应服务、每条边能在运行时链路或配置里找到依据、CI 已经能产出最新渲染产物。全部迁移完成后旧白板文件整体归档锁定不再作为活跃文档。5.3 结果对比与评审体验的变化两周后最直观的变化是图有人负责了。每张图都有明确的 owner、明确的变更入口、明确的构建校验。第二次评审会我们直接在评审间投屏 CI 渲染出的最新图大家讨论时再也不会有人问这图是最新的吗这种话因为它就是从当前代码快照渲染出来的。另一个隐性收益是历史追溯。以前这张图是谁改的什么时候改的完全靠猜现在用 Git 看提交历史一目了然甚至可以回溯到具体某条边是在哪个需求里加进来的。听起来不酷但对长期维护一个业务系统的人来说这就是实打实的幸福感。6. 想复用这套思路这是起步清单与习惯建议6.1 最小可用起步从一张图开始不需要一上来就搞平台级工程化最小可用的起步建议是三步。第一步在项目仓库里建diagrams/目录把一个你最近不得不手动画的架构图画成文本源文件第二步在本地装好渲染命令行工具一键生成 SVG 和 PNG第三步写一个最简陋的 CI job让它在每次合并时执行渲染 产物更新。一个通用 CI job 的骨架大概是这个样子diagram-build: stage: build script: - npm ci - npm run diagram:build - npm run diagram:check artifacts: paths: - dist/diagrams/*关键是diagram:check这一步至少要包含源文件语法校验、是否存在孤立节点、是否有重复边 ID。这一步不做后面的 CI 再自动也只是自动生成过期图。6.2 团队习惯审图要像审代码工具是骨架习惯是血肉。我总结了几个对落地最有用的团队习惯一次改动只管一张图合并请求的粒度越小图 diff 越容易被 review一个大 PR 改了 8 张图没人愿意认真看最后往往是睁一只眼闭一只眼。先语义后样式画图前先在纸上写清有哪些节点、哪些边、哪些分组再转化成文本不要一上来就调颜色和字体。颜色永远是最不紧急的那一步。新图先声明边界再填充细节先建 2-3 个顶级 subgraph 划定业务域再去填充每个域里的具体节点布局效果远好于随手堆节点再后悔。6.3 后续可以扩展的方向diagram-design 跑通之后后续还有不少可扩展的点。如果你也走通了基础链路可以按需尝试大图交给专门的图布局引擎超过 50 个节点的有向依赖图建议额外接 Graphviz/DOT 语言避免文本图表脚本的布局引擎在大规模场景下力不从心面向客户的整洁出图交给现代声明式语言它默认布局现代、配色清爽成本低适合临时生成对外展示用的示意图从代码扫描自动生成依赖图配合静态分析工具把接口调用关系自动转成.mmd源文件这是图跟着代码走的终极形态主题与品牌化把团队/公司的品牌色做成一套主题变量渲染出来的所有图风格统一这是文档资产里隐藏的专业感来源。我在实际维护 diagram-design 的过程中最大的体会是图的价值不只在于画出来的那一刻而在于它能不能在一个团队里活过半年。只要把图当成代码管它就能像代码一样永葆青春如果把它当成画它迟早变成一张无人认领的装饰画。最后分享一个小技巧给diagram:check加上图源文件行数超限就报警的规则一张.mmd超过 200 行就提示拆图。第一次报警不用急着拆它只是提醒你这个图已经复杂到没人愿意维护了趁早拆分比等它变成巨型蜘蛛网再处理要省力得多。
先交代一下背景。我手头这个项目叫diagram-design听起来很普通就是图表设计四个字但它解决的是我在团队里被反复折磨了大半年的老问题架构图、流程图、依赖图永远和代码对不上。事情的起因很常见。一次技术评审会上新来的同学指着白板上的流程图问我这个图上写的消息队列代码里好像已经换成了别的中间件图是最新的吗我低头看了一眼版本记录的修改时间——上一次更新是十一个月前而系统已经迭代了三个大版本。全场沉默。不是大家不想维护而是那张图存在共享盘的某个无名字文件里画它的人早就换了项目。那一刻我开始认真思考一个问题为什么代码可以版本化、可 review、可自动化构建而架构图做不到于是就有了 diagram-design 这个项目——把所有图表当成代码工程来管理用文本定义图元用自动布局引擎排版用 CI 自动渲染让图跟着代码走而不是靠人肉记住哪张图还活着。这篇文章不聊概念只聊实操为什么我把架构图定义成工程资产选型时对比了哪些方案内部管线怎么拆落地时踩了哪些坑以及一个两周迁移的真实复盘。无论你是被图又过期了逼疯的技术负责人还是想规范组内文档的架构师它都值得你花几分钟看完。1. 为什么要把架构图当成一个代码工程来管理1.1 手绘图在评审会上掉链子的那几次我先说说手工绘图模式下最常见的几个死法。第一种是文件失联。图存在共享盘里文件名常常是最终版-v2(真的最终)-new.drawio这种等下次要改的时候打开一看内容还是上个季度的。第二种是单点持有。整个团队只有某一个同学会改这张图他休假图就冻结他转岗图就失传。第三种是改图成本大于画图。系统迭代时架构图理应跟着变但一张大图要手动挪十几个框、重画七八条线前后浪费两个小时最后大家干脆放弃治疗。我自己做过一次粗略统计团队维护的三十多张图里超过一半在图注时间上落后于代码变更只有不到三成能被称为勉强可用。这不是某一个团队的惰性而是工具链的错——传统绘图工具根本没有把版本变更记录自动检查这些最基本的软件工程能力当成设计目标。1.2 图的本质也是代码资产代码工程的核心能力是什么版本控制、变更审查、自动化校验、可追溯历史。把这些能力用在图上就是我常说的图即代码思维。diagram-design 项目把这套思维落成了三点。第一图有数据层节点、边、分组都是结构化定义不依赖鼠标拖拽的绝对坐标第二图有表现层布局由算法决定样式由主题统一管理人可以干预的是语义分组而不是这个框距离那个框 37 像素第三图有验证层构建时自动检查孤立节点、重复关系、空标签有问题直接让流水线失败。这样处理之后架构图就和业务代码站在同一个起跑线上了它住在 Git 仓库里每一次变更都有 diff每次合并都要走 review渲染由 CI 完成永远只有最新版。评审时打开链接看到的图和代码是同一时刻的快照不会再出现图上说的是旧的代码跑的是新的这种尴尬。1.3 这个项目适合谁来用如果你符合下面任意一条diagram-design 这套思路值得借鉴你所在的团队有大量系统架构图、调用链图、部署拓扑图且正在饱受图过期之苦你们每次评审都要浪费时间确认到底哪张图是对的团队里有同学愿意用敲键盘代替拖鼠标来画图你们已经接受了文档即代码docs-as-code的工作方式只想把图的环节补齐。它不适合的场景也有比如你只是临时画一张一次性示意图发给同事不需要长期维护那用绘图软件拖两下反而更快。这个项目解决的是需要长期活在代码仓库里的图目标清晰适用场景同样清晰。2. 选型实录四个代码化绘图方案我为什么没全选2.1 主流方案的横向对比代码化绘图社区里其实早有一堆成熟工具关键是选型时容易眼花缭乱。我把实际试用过的四个方向整理成了对比先看表再解释方向学习成本复杂图布局能力中文渲染主题定制CI 脚本化社区生态文本图表脚本Mermaid 这类低中流程图上佳较好需开启自动换行中成熟活跃经典图描述语言Graphviz / DOT中高强有向图非常稳一般依赖环境影响中成熟老牌稳定现代声明式绘图语言D2 这类低强默认布局好看好高成熟但使用者少快速成长通用在线绘图软件导出的文本格式低弱好低差一般先说明第四类通用在线绘图软件导出的文本格式我没有细测因为它的定位和代码化根本不同尽管能保存成文本但结构里充满了坐标点信息本质上还是在拖框子。真正值得纠结的是前三个。2.2 我的选择和取舍逻辑diagram-design 最后的主渲染器选了Mermaid 这类文本图表脚本原因是团队认知度最高——组里有几个同学已经会写基础语法不需要额外培训就能上手。我选它当主力还有一个考虑它的 flowchart 语法足够表达大多数微服务关系图、流程图、时序图内置主题也能满足日常需要。但只赌一个方案是不够的。我把Graphviz / DOT作为复杂有向图的兜底当图里节点超过五十个、依赖关系超过一百条时Mermaid 的布局引擎会开始力不从心而 DOT 的图布局算法dot、neato、fdp在这种场景下极其稳定。为此我在项目中留了一个复杂图目录专门放.dot文件。D2 这类现代声明式语言我也试过语法确实清爽默认出图效果可以说是三个里最好看的。但当时它的主题体系还不够成熟遇到团队品牌色调整时需要手写很多样式变量维护成本反而上来了。我的判断是它适合给客户做汇报的示意图但作为团队内部基础设施生态成熟度还差一点。所以它在我这里是一个实验性目录没有进主链路。顺带说一句版本的教训所有依赖都必须锁版本。Mermaid 这类工具的版本升级经常会改变渲染细节如果不锁版本某天合并代码后突然发现所有图连线粗细都变了追根溯源又是一个晚上。2.3 版本管理与多人协作机制选型定了之后真正的工程量在于多人协作。diagram-design 做了三件事第一一图一文件。每个图对应一个源文件.mmd或.dot文件名就是图的唯一标识例如order-service-deps.mmd。产物PNG/SVG可以不入库由 CI 统一生成也可以把核心图静态产物一并提交方便在 IDE 里快速预览——我选了后者因为改动频率低、好处直观。第二把图变更和代码变更绑在同一个 PR 里。如果开发者改了服务的调用关系他需要同时更新对应的图文件否则 CI 里单独的diagram:check会失败。这一步从机制上保证了图不会单独过期。第三视觉回归。关键图比如核心交易链路会维护一张 golden 快照每次渲染后做像素级对比差异超过阈值就提示人工确认。它防的不是内容错误而是主题升级、字体替换这些意外整容——这类问题人工看 diff 很难一眼发现机器反而敏感。3. 管线设计图元定义、自动布局、渲染输出的三层拆分3.1 领域模型把图拆成可组合的图元如果直接打开一张.mmd文件看新人会以为它只是带特定语法的文本但设计时我是按领域模型来组织的。一张图本质上由四类图元组成节点node唯一标识、展示名称、类型服务、数据库、外部系统、消息队列等边edge起点、终点、方向、关系标签调用、依赖、数据流分组group把节点归入某个业务域或限界上下文样式覆盖style override个别节点的高亮色、边框样式用于标注异常或重点。对应到文本语法就是一个这样的结构实际项目中我会把这段存成.mmd源文件flowchart TB subgraph order[订单域] A[订单服务] B[(订单数据库)] end subgraph pay[支付域] C[支付服务] D[(支付数据库)] end A --|读写| B C --|读写| D A --|RPC 调用| C看到没有我全程没有写任何一个像素坐标。我只是表达了订单服务和订单数据库是什么关系支付服务在哪里两个服务之间有没有调用至于这些框最终在画布上如何排布那是布局引擎的事。3.2 布局引擎为什么不能让节点自己长脚这是 diagram-design 项目理念上与手工绘图软件最大的分水岭。手工工具里每个框有绝对坐标拖动一个框旁边的线跟着变形而自动布局引擎负责把关系图计算成坐标图。为什么要自动化因为人工摆坐标在图的规模面前不可持续。五六个框你还能手动调好看三十个框加上交叉连线再手摆就是灾难每加一个节点所有线条可能都要重排没人愿意干。自动布局算法主要依赖 dagre 这类层级布局算法的好处是它会让节点尽量沿层级排布减少交叉保证连线不穿过节点。坏处是它不理解你的业务直觉——比如你想让订单域整体悬浮在画布右上角算法只关心图论上的合理性。应对办法是用语义分组来影响布局。想要某些节点待在一起就把它们放进同一个 subgraph想让两个大域之间少几条交叉线就先建域级边界再在域内建服务级节点。布局引擎会优先按分组聚合再处理组间的连线。我在项目里反复跟团队强调一个原则你永远不要试图通过加不可见节点或者手写坐标来微调位置那是饮鸩止渴。3.3 渲染适配SVG、PNG、可交互单页三种产物图的核心产物我做了三种各有用途SVG主产物。矢量格式缩放不糊适合在 README 和内部文档中直接引用PNG用于 IM 聊天、PPT 嵌入。我会指定渲染宽度比如 1200px并开启字体嵌入避免换台机器字变方框HTML 单文件用于评审和分享。所有内容内联在一个页面里支持鼠标滚轮缩放关键节点加跳转链接评审时大家对着这个页面讨论体验最好。具体的构建命令长这样由 CI 调用npx mmdc -i diagrams/order-service-deps.mmd -o dist/order-service-deps.svg -b transparent -w 1200这里有两个参数值得单独提一下。-b transparent是让背景透明这样图放到深色主题的文档里不会白一块。-w 1200是限定渲染宽度实际测试时发现宽度太小文字容易挤宽度太大超过 2000部分浏览器反而会触发锯齿渲染1200-1600 是比较稳的范围。3.4 目录规范一年后你还能看懂文件在干嘛管线再有条理目录乱成一锅粥也没用。diagram-design 的目录结构花了很大心思最终稳定成这样. ├── diagrams/ │ ├── order/ # 按业务域分目录 │ ├── payment/ │ └── infra/ ├── adr/ # 决策记录比如“为什么改用自动布局” ├── scripts/ # 构建、校验脚本 ├── dist/ # 自动生成的产物通常不入库 └── package.json文件命名我定了一条死规矩必须有意义且自解释。order-service-deps.mmd比1.0-final.drawio好一万倍因为前者在一年后仍然能被任何人理解后者只有画图者本人能猜出大概。每个目录下我会放一个 README写清楚这个目录的图是什么范围谁负责新增图。这事很土但它是整个项目能持续运转的地基。4. 落地阶段最常翻车的四个问题4.1 中文文本溢出看起来是小事翻车率极高我最早吃过最大的亏是中文文本溢出。英文渲染时一个标签十几个字符通常没什么问题换成中文后节点里的字会被挤成两行甚至直接溢出框外。这个问题在本地看 SVG 时还不明显一旦嵌入网页字体加载和环境差异就会让布局崩掉。排查后的处理方案按优先级排列改文案把过长的节点标签拆成短词比如订单服务缓存集群简化为订单缓存短标签是最省事的解开启自动换行在 flowchart 配置里启用文本换行同时给节点设置一个合适的宽度降低渲染字号密度全局主题里把字体调小一档通常能救回一批边缘案例。%% 在源文件头部声明主题和换行 %%{init: {theme: base, flowchart: {wrappingWidth: 100}}}%%这个配置的作用是告诉布局引擎当文字宽度超过 100 个字符单位时再换行而不是一到边界就断。实际效果因人因图而异我的建议是不要追求一个全局完美值而是对个别长文本节点单独用引号包裹并手动指定宽度。长文本节点永远是少数全局配置只解决 80% 的场景。4.2 自动布局变成蜘蛛网语义分层拯救图当一张图的连线超过一定数量自动布局也会失灵画布上全是交叉线像一盘打翻的意面。我的第一反应是布局算法不够强于是去论文里翻各种布局策略折腾了很久才意识到问题根本不在算法。真正的原因是我们的边定义太冗余。举个例子A 服务调用 BB 调用 C这本来是一条清晰的链路但很多人会顺手再画一条 A 到 C 的边表示间接依赖——这就是典型的冗余边。去掉它布局引擎能省下大量交叉计算。我在项目里做了一次链接清理把某张图从 47 条边减到 31 条可读性提升是肉眼可见的。第二个优化是语义分组约束布局。对于跨多个业务域的图我建议先把每条边标注好它属于哪个域间关系然后把域内关系尽量锁进同一个 subgraph。这样布局引擎天然处理成大组之间的主干连线 组内的细节连线层次感立刻出来了。4.3 配色与可访问性图是给人看的不是给色觉正常的你一个人架构图的受众永远包含没有你上下文的人其中一些人的色觉和你不完全一样。我最初设计的图用红绿两色区分正常链路和异常链路结果一位合作同学反馈说他看这两条线根本分不清。你说这算 bug 吗在当时的产品视角里它就是 ciritical 级别的 bug。所以我在 diagram-design 里做了一套可访问性规范不只依赖颜色重要区别同时用形状、线型实线/虚线/点线和颜色三重编码保证文本对比度前景色和背景色对比度至少 4.5:1不追求花哨保证能读给 SVG 加语义信息每个图节点生成title和desc方便读屏软件固定一套主题色色板统一管理下面是实测推荐的一组用途色值说明主文字#1f2328深灰黑对比度极佳页面背景#ffffff纯白最安全主链路#0969da蓝色搭配实线异常链路#cf222e红色搭配虚线分组背景#f6f8fa极浅灰不干扰主视觉这组色值不是从设计平台上抄的是实际渲染时一个个试出来的目的是在好看和高对比之间找一个长期不后悔的平衡点。4.4 CI 构建稳定性渲染失败就该让构建失败最容易被低估的是 CI 接入问题。这里的稳定性不是指渲染引擎崩溃而是指构建链路应该把图的问题当成一等错误暴露而不是悄悄跳过。我踩过的具体坑有三个。第一版本漂移没有锁版本时某天 CI 悄悄升了依赖版本所有图的边距都变了全组人对着 diff 困惑了一上午。现在我把依赖版本写死每次升级单独走一个 PR。第二超时文本图表的渲染依赖无头浏览器冷启动很慢如果 CI 任务默认超时时间是 30 秒大概率不够。我们最终把渲染任务的超时放宽到 120 秒并在脚本里加了--timeout参数稳定多了。第三失败静默早期脚本把渲染失败当作warning打印一下就继续导致图坏了没人知道。现在的规则是校验失败或者渲染失败CI 直接红没有任何商量余地。这段我强烈建议所有想把图表纳入 CI 的团队记住图也是交付物交付物坏了就没有绿色构建。5. 一次真实迁移散乱看板图集如何在两周内规范化5.1 现状盘点36 张图只有 15 张勉强可看理论讲完讲一个我实际带的迁移。某零售业务订单系统团队需要维护的架构相关图有 36 张分布在一个共享白板工具和若干本地文件里。作为对照组先做盘点9 张标注了已废弃但实际上还在被访问12 张内容相对完整但图注时间平均滞后两个月只有 15 张基本可用而可用的定义仅仅是图上的名词在代码里能找到对应。这个数据比我想象的还严重。36 张图里真正值得迁移的不到一半其余全是历史债务。所以迁移第一步不是把图导出来转格式而是砍掉该砍的。5.2 迁移节奏先冻结、再归类、后逐张验收两周的迁移节奏我拆成了三个阶段。**第一阶段第 1-2 天冻结图变更 清点分类。**暂停所有新图的绘制避免边迁移边新增然后把 36 张图按业务域归为五类逐张确认负责人哪怕只是这张图没人认领建议删除。**第二阶段第 3-7 天翻译成源文件草稿。**把值得保留的图逐张转成.mmd源文件。这个阶段不追求样式好看只求语义正确节点、边、分组是不是与当前代码一致。每天抽两个人各认领一批半天翻译、半天交叉 review。转译期间发现的大量图上写了调用但代码里根本没有这个接口的问题正好一并反馈给开发同事确认。**第三阶段第 8-14 天接入 CI 逐张验收。**把所有源文件接入渲染流水线补 golden 快照把构建失败和视觉变化当作硬门槛。验收标准就三条图上每个节点能在代码里找到对应服务、每条边能在运行时链路或配置里找到依据、CI 已经能产出最新渲染产物。全部迁移完成后旧白板文件整体归档锁定不再作为活跃文档。5.3 结果对比与评审体验的变化两周后最直观的变化是图有人负责了。每张图都有明确的 owner、明确的变更入口、明确的构建校验。第二次评审会我们直接在评审间投屏 CI 渲染出的最新图大家讨论时再也不会有人问这图是最新的吗这种话因为它就是从当前代码快照渲染出来的。另一个隐性收益是历史追溯。以前这张图是谁改的什么时候改的完全靠猜现在用 Git 看提交历史一目了然甚至可以回溯到具体某条边是在哪个需求里加进来的。听起来不酷但对长期维护一个业务系统的人来说这就是实打实的幸福感。6. 想复用这套思路这是起步清单与习惯建议6.1 最小可用起步从一张图开始不需要一上来就搞平台级工程化最小可用的起步建议是三步。第一步在项目仓库里建diagrams/目录把一个你最近不得不手动画的架构图画成文本源文件第二步在本地装好渲染命令行工具一键生成 SVG 和 PNG第三步写一个最简陋的 CI job让它在每次合并时执行渲染 产物更新。一个通用 CI job 的骨架大概是这个样子diagram-build: stage: build script: - npm ci - npm run diagram:build - npm run diagram:check artifacts: paths: - dist/diagrams/*关键是diagram:check这一步至少要包含源文件语法校验、是否存在孤立节点、是否有重复边 ID。这一步不做后面的 CI 再自动也只是自动生成过期图。6.2 团队习惯审图要像审代码工具是骨架习惯是血肉。我总结了几个对落地最有用的团队习惯一次改动只管一张图合并请求的粒度越小图 diff 越容易被 review一个大 PR 改了 8 张图没人愿意认真看最后往往是睁一只眼闭一只眼。先语义后样式画图前先在纸上写清有哪些节点、哪些边、哪些分组再转化成文本不要一上来就调颜色和字体。颜色永远是最不紧急的那一步。新图先声明边界再填充细节先建 2-3 个顶级 subgraph 划定业务域再去填充每个域里的具体节点布局效果远好于随手堆节点再后悔。6.3 后续可以扩展的方向diagram-design 跑通之后后续还有不少可扩展的点。如果你也走通了基础链路可以按需尝试大图交给专门的图布局引擎超过 50 个节点的有向依赖图建议额外接 Graphviz/DOT 语言避免文本图表脚本的布局引擎在大规模场景下力不从心面向客户的整洁出图交给现代声明式语言它默认布局现代、配色清爽成本低适合临时生成对外展示用的示意图从代码扫描自动生成依赖图配合静态分析工具把接口调用关系自动转成.mmd源文件这是图跟着代码走的终极形态主题与品牌化把团队/公司的品牌色做成一套主题变量渲染出来的所有图风格统一这是文档资产里隐藏的专业感来源。我在实际维护 diagram-design 的过程中最大的体会是图的价值不只在于画出来的那一刻而在于它能不能在一个团队里活过半年。只要把图当成代码管它就能像代码一样永葆青春如果把它当成画它迟早变成一张无人认领的装饰画。最后分享一个小技巧给diagram:check加上图源文件行数超限就报警的规则一张.mmd超过 200 行就提示拆图。第一次报警不用急着拆它只是提醒你这个图已经复杂到没人愿意维护了趁早拆分比等它变成巨型蜘蛛网再处理要省力得多。
