1. 从一张草图到一套系统diagram-design 到底在解决什么问题很多人第一次听到 diagram-design 这个词会下意识觉得它只是“画图”的另一种说法。但真正在项目里被图表折磨过的人知道画图本身从来不是难点难点在于图表的可维护性、一致性和表达效率。我见过太多团队需求评审时随手画一张流程图开发阶段又重画一张架构图上线后运维再补一张部署图三张图各说各话改一个模块要同步改五个地方最后谁也不敢保证哪张图是最新的。diagram-design 要解决的正是这个“图与人、图与代码、图与文档之间脱节”的问题。它不是一个单纯的绘图工具而是一套以设计系统思维来管理图表资产的方法论加工具链。核心思路是把图表当成代码来对待用文本描述结构用版本控制追踪变化用统一的样式规范保证视觉一致最终让图表能够像函数一样被复用、被组合、被自动生成。这套东西适合谁如果你是技术文档写作者、系统架构师、产品经理或者任何需要频繁输出结构化图表的人diagram-design 能帮你把“画图”这件事从手工劳动变成工程实践。如果你只是偶尔画一张示意图发群里那可能用不上这么重的方案但了解它的思路对提升图表表达质量依然有帮助。我最初接触这个方向是因为一个跨平台系统项目里架构图每隔两周就要更新一次每次更新都要手动调整几十个框和箭头错一个连线就要返工半小时。后来我把图表描述抽成文本用脚本渲染改结构只改几行配置样式自动套用效率提升了不止一个量级。下面我把这套实践中沉淀下来的方法拆开讲包括工具选型、结构设计、样式规范、自动化集成和踩过的坑。2. 为什么“用代码画图”比拖拽更靠谱2.1 拖拽式绘图的三条死胡同先说清楚为什么我不推荐在需要长期维护的项目里用传统拖拽工具。第一条死胡同是版本对比几乎不可用。你改了一个框的位置导出的图片二进制文件在 Git 里只显示“文件已更改”根本看不出改了什么。第二条是样式漂移。三个人画三张图边框粗细、字体大小、颜色深浅全不一样拼在一起像三个不同项目。第三条是复用困难。一张子模块图在五张总图里出现子模块改了你得手动找到五张图逐一修改。这三条死胡同的本质是拖拽工具把“结构”和“表现”绑死在了一起。你拖动一个矩形既改变了它的逻辑位置也改变了它的视觉呈现两者无法分离。而 diagram-design 的核心洞察就是结构应该用文本描述表现应该用样式规则控制两者解耦。2.2 文本描述结构的实际收益把图表结构写成文本最直接的好处是可以用 Git 做 diff。比如下面这段用 Mermaid 描述的一个简单流程flowchart LR A[用户请求] -- B{鉴权通过?} B --|是| C[查询缓存] B --|否| D[返回 401] C -- E{命中?} E --|是| F[返回缓存数据] E --|否| G[查询数据库] G -- H[写入缓存] H -- F这段文本在 Git 里的变化一目了然新增了一个判断节点或者调整了某个分支的走向review 的人一眼就能看懂。而如果这是一张 PNG你只能看到“二进制文件不同”。对于需要严格评审的架构设计来说这种可审查性是刚需。另一个收益是批量生成。当你有二十个微服务每个服务的调用关系都需要一张图时手动画二十张是灾难。但如果你把服务依赖写成结构化数据比如 YAML 或 JSON用模板渲染二十张图可以一键生成改一个公共样式全部生效。2.3 什么场景不适合代码化当然我不是说所有图都该代码化。高度艺术化的信息图、需要精细排版的海报、一次性演示用的概念草图这些场景用专业设计工具更合适。代码化绘图的优势区间是结构清晰、需要频繁更新、需要多人协作、需要嵌入文档流水线的图表。判断标准很简单如果这张图三个月后还要改而且改的时候你希望知道改了什么那就值得代码化。3. 选型实战Mermaid、PlantUML、Graphviz 怎么挑3.1 三者的定位差异市面上主流的文本绘图方案不少我重点对比三个最常用的Mermaid、PlantUML 和 Graphviz。它们不是互相替代的关系而是各有擅长的领域。工具最擅长学习曲线渲染依赖样式控制Mermaid流程图、时序图、甘特图低浏览器/Node中等支持主题PlantUMLUML 全系、架构图、思维导图中Java强支持皮肤参数Graphviz复杂关系网络、自动布局中高本地二进制弱偏自动布局Mermaid 的优势是上手快、生态好。GitHub、GitLab、Notion 等平台原生支持 Mermaid 渲染你写完直接就能看到效果。它的语法接近自然语言非技术人员也能读懂。缺点是复杂布局的控制力有限节点位置基本靠自动排布。PlantUML 的优势是表达力强、图表类型全。从类图、时序图到部署图、思维导图几乎覆盖了软件工程所有标准图表。它支持丰富的皮肤参数可以精细控制颜色、字体、间距。缺点是渲染需要 Java 环境在纯前端场景下不如 Mermaid 方便。Graphviz 的优势是自动布局算法强大。当你有一百个节点、关系错综复杂时Graphviz 的布局引擎能自动算出相对清晰的排布这是手工调位置做不到的。缺点是它的 DOT 语言偏底层样式控制不够直观适合做数据分析类的关系图不太适合做演示用的架构图。3.2 我的组合策略在实际项目里我通常这样组合日常流程图和时序图用 Mermaid因为快且平台支持好正式架构文档用 PlantUML因为样式可控、图表类型规范数据关系分析用 Graphviz因为自动布局省心。三者可以共存于同一个文档体系通过统一的样式变量来保持视觉一致。这里有个关键细节如果你要在同一份文档里混用多种工具一定要统一颜色变量和字体。我的做法是定义一个theme.yaml里面存主色、辅色、字体族、圆角半径等然后写脚本把变量注入到各工具的配置里。这样即使工具不同出来的图也是一个视觉体系。3.3 一个容易忽略的选型因素渲染环境选型时很多人只看语法忽略了渲染环境。Mermaid 在浏览器里渲染适合嵌入网页和在线文档PlantUML 需要服务端或本地 Java 进程适合 CI 流水线里批量生成Graphviz 需要本地安装二进制适合脚本化处理。如果你的文档平台不支持某种工具的渲染那语法再好也用不上。所以选型第一步应该是确认你的发布环境支持什么再倒推工具选择。4. 把图表当代码管目录结构与命名规范4.1 为什么目录结构值得单独设计当图表数量超过二十张目录结构就开始影响效率了。我见过把所有.mmd文件堆在一个文件夹里的项目找一张图要翻半天改完也不知道影响了哪些文档。好的目录结构应该反映图表的逻辑归属而不是文件类型。我常用的结构是这样的diagrams/ architecture/ system-overview.mmd >flowchart TD req[用户请求] -- auth{鉴权服务} auth --|通过| cache[缓存层] auth --|拒绝| deny[返回错误]这样 ID 稳定改显示文本不影响引用关系显示文本清晰读图的人不用猜。如果节点需要在多处引用ID 一定要语义化比如auth-service而不是s1。5. 样式系统让一百张图看起来像一个人画的5.1 样式漂移的根源图表视觉不一致根源在于样式定义分散。每张图各自定义颜色、字体、间距改一个品牌色要改一百个地方。解决办法是把样式抽成单一数据源所有图表从同一个地方读取。以 Mermaid 为例它支持通过%%{init}%%指令注入主题配置%%{init: {theme:base, themeVariables: { primaryColor:#e8f0fe, primaryBorderColor:#4a6fa5, lineColor:#5a5a5a, fontFamily:system-ui, sans-serif, fontSize:14px }}}%% flowchart LR A[模块A] -- B[模块B]把这段init指令抽成一个公共文件每张图开头引入就能保证所有图共用一套视觉变量。PlantUML 类似用!include引入皮肤文件。Graphviz 则通过-G参数或配置文件注入。5.2 颜色语义化不要用“蓝色”思考样式系统里最重要的不是选什么颜色而是建立颜色与语义的映射。我通常定义这几组语义色主流程色正常路径的节点和连线决策色判断节点的强调色异常色错误分支和告警节点外部色第三方系统或边界外的组件数据色存储和数据库相关节点定义好语义后画图时想的是“这是一个异常节点”而不是“这个框要涂红色”。这样即使品牌色调整只要改语义映射表所有图自动更新。而且不同人画图时对同一类节点会用同一种颜色一致性自然就有了。5.3 间距和字体的隐形影响很多人只关注颜色忽略了间距和字体。实际上间距不一致比颜色不一致更显眼。两张图并排一张节点间距 20px一张 50px看起来就像两个不同团队做的。我的做法是在主题里固定几个间距档位紧凑 16px、标准 24px、宽松 40px按图表密度选用不随意写数值。字体同理。中英文混排时如果字体族没配好中文用宋体、英文用 Arial看起来会很割裂。我通常指定system-ui, -apple-system, Segoe UI, sans-serif这样的字体栈让系统自动选择最合适的中英文字体保证渲染一致。6. 自动化流水线从提交到渲染产物6.1 为什么需要自动化手工渲染图表有三个问题忘记渲染导致文档和源文件不同步、不同人本地环境渲染结果有差异、批量更新时重复劳动。自动化流水线解决的就是这三个问题提交即渲染、环境统一、批量处理。6.2 一个可复用的渲染脚本我用 Node.js 写了一个渲染脚本核心逻辑是遍历diagrams目录根据文件扩展名调用对应的渲染器输出到_build/output。简化版如下const fs require(fs); const path require(path); const { execSync } require(child_process); const SRC path.join(__dirname, diagrams); const OUT path.join(__dirname, _build, output); function walk(dir) { const entries fs.readdirSync(dir, { withFileTypes: true }); for (const entry of entries) { const full path.join(dir, entry.name); if (entry.isDirectory()) { if (entry.name.startsWith(_)) continue; walk(full); } else if (entry.name.endsWith(.mmd)) { renderMermaid(full); } else if (entry.name.endsWith(.puml)) { renderPlantUML(full); } } } function renderMermaid(file) { const rel path.relative(SRC, file); const outFile path.join(OUT, rel.replace(.mmd, .svg)); fs.mkdirSync(path.dirname(outFile), { recursive: true }); execSync(mmdc -i ${file} -o ${outFile} -t neutral -b transparent); console.log(rendered: ${rel}); } function renderPlantUML(file) { const rel path.relative(SRC, file); const outFile path.join(OUT, rel.replace(.puml, .svg)); fs.mkdirSync(path.dirname(outFile), { recursive: true }); execSync(plantuml -tsvg -o ${path.dirname(outFile)} ${file}); console.log(rendered: ${rel}); } walk(SRC);这个脚本的关键点是跳过下划线开头的目录比如_shared和_build保持输出目录结构与源目录一致输出 SVG 而非 PNGSVG 矢量、体积小、可搜索文本。6.3 接入 CI 的注意事项把渲染脚本接入 CI 时有几个坑要注意。第一渲染工具版本要锁定不同版本的 Mermaid 渲染结果可能有细微差异导致 CI 产物和本地不一致。第二渲染失败要阻断流水线不能静默跳过否则文档里会出现缺失的图。第三产物要缓存或提交如果文档平台不实时渲染就需要把 SVG 提交到仓库或发布到静态资源服务。我的做法是在 CI 里跑渲染脚本把产物提交到一个gh-pages分支或对象存储文档里引用产物的 URL。这样源文件和产物分离仓库不会因为二进制文件膨胀。7. 踩坑实录那些文档没写的细节7.1 Mermaid 的自动布局陷阱Mermaid 的自动布局在简单图上表现很好但节点一多就容易出现连线交叉和节点重叠。我遇到过一次一张有三十个节点的流程图Mermaid 渲染出来连线乱成一团完全没法看。排查后发现是节点之间的依赖关系太复杂自动布局算法找不到好的排布。解决办法有两个一是拆图把一张大图拆成几张子图用超链接关联二是手动指定方向用flowchart TD或flowchart LR控制主方向减少交叉。如果还是不行就换 PlantUML 或 Graphviz它们的布局算法对复杂图更友好。7.2 中文字体在 SVG 里的丢失问题用 Mermaid 渲染 SVG 时如果主题里指定的字体在渲染环境里不存在SVG 会回退到默认字体导致中文显示异常。我踩过一次坑本地渲染正常CI 渲染出来中文全是方框。原因是 CI 环境没有安装中文字体。解决办法是在 CI 环境里安装中文字体包或者在主题里指定通用字体栈让渲染器有多个回退选项。更稳妥的做法是渲染时把字体转成路径但这样会失去文本可搜索性需要权衡。7.3 版本升级导致的语法不兼容Mermaid 和 PlantUML 都在持续迭代新版本可能修改语法或默认行为。我有一次升级 Mermaid 后之前能渲染的图报错了原因是某个语法在新版本里被废弃。教训是锁定渲染工具版本升级前先在分支上全量渲染验证。可以在package.json里固定版本号不要用^或~。7.4 图表与文档的同步问题最后一个坑是图表更新了但文档没更新。文档里引用的还是旧图读者看到的是过时信息。解决办法是在文档里嵌入图表源文件而非图片让文档平台实时渲染。如果平台不支持就在 CI 里加一步校验检查图表源文件的修改时间是否晚于文档如果是就报警提示更新。8. 从单张图到图表库规模化后的组织思路8.1 建立图表索引当图表超过五十张光靠目录结构已经不够了。我建议建一个图表索引文件用表格列出每张图的名称、用途、所在路径、关联文档。这个索引可以手工维护也可以用脚本从文件注释里自动生成。索引的价值是让新人快速了解项目里有哪些图、分别在哪、什么时候用。8.2 图表的复用与组合规模化的另一个问题是重复画相似的图。比如十个微服务每个都有一张调用关系图结构类似只是节点不同。这时候可以把公共结构抽成模板用变量替换节点信息。Mermaid 本身不支持模板但可以用脚本预处理读一个 YAML 数据文件套模板生成多张.mmd。8.3 定期清理与归档图表库和代码库一样会积累废弃的图。我建议每个季度做一次清理删除不再引用的图、归档历史版本的图、合并重复的图。归档的图移到_archive目录不参与渲染但保留在 Git 历史里需要时可以找回。9. 我在这套方法里最看重的三个习惯第一个习惯是先写结构再调样式。很多人一上来就纠结颜色和间距结果结构改来改去样式白调了。我的做法是先用最朴素的样式把结构画对确认逻辑无误后再套主题。这样返工成本最低。第二个习惯是每张图都写注释。在图表源文件顶部用注释写明这张图的用途、作者、最后更新原因。过三个月回头看这些注释能帮你快速回忆上下文比看图猜意图高效得多。第三个习惯是图表和代码同仓库。图表描述的是系统结构系统结构变了图表就该变。把图表放在代码仓库里改代码时顺手改图评审时一起看能最大程度避免图表和实现脱节。如果图表放在独立的文档仓库很容易出现代码改了图没改的情况。这套 diagram-design 的方法我用了两年多最大的感受是画图这件事前期多花时间建规范后期省下的时间是指数级的。一开始可能觉得写文本比拖拽慢但当你需要改第十张图的时候就会庆幸当初把样式抽出来了。如果你正在被图表维护折磨不妨从下一张图开始试试用文本描述结构、用变量控制样式慢慢把这套习惯沉淀下来。