架构图用代码画：五套 DSL 的分工与 Kroki 统一渲染

架构图放进 Git 之后，改一次服务就要重画一遍，图和代码很快对不上。“图即代码”把图形描述成文本，让图纸能 diff、能审阅、能在 CI 里重新渲染。可一旦决定这么做，Mermaid、D2、Graphviz、PlantUML、Structurizr 就摆在面前。这篇按图种、渲染方式与许可把它们分开，再说 Kroki 这类统一渲染服务怎么用。

选型先看四件事

先定图种，再挑语法。C4 的上下文图、UML 时序图、依赖关系图，需要的表达能力完全不同，用错工具会比手画更慢。

第二看渲染位置。图要不要在 GitHub 的 Markdown 里直接显示，决定了团队能不能在 PR 里看到改动结果。第三看运行环境，JVM、Go、浏览器的依赖差别很大，CI 镜像体积也跟着变。第四看许可，尤其是把渲染器打包进商业产品时。

还有一项隐性成本：谁来改图。如果改图的人是不写代码的产品或测试，语法再简洁也会变成负担，这时导出一张静态图给人看，比要求对方学 DSL 更现实。把“维护者”写进选型清单，比比较功能表更能减少返工。

Mermaid：文档里嵌入成本低

Mermaid 用接近 Markdown 的写法描述图形，覆盖流程图、时序图、类图、状态图、ER 图、甘特图、C4、思维导图等类型。它采用 MIT 许可，库本身可以自由嵌入。

它的现实优势在生态：GitHub、GitLab 的 Markdown 会原生渲染 Mermaid 代码块，README 里写入一段就能出图，评审时改动以文本 diff 呈现。项目仍在持续更新，具体版本号以 npm 发布页为准，不必在文档里抄死。

需要脱离浏览器出图时，社区维护了命令行封装，可以批量把源码文件转成 SVG 或图像文件，适合放进构建脚本。参数与依赖以项目文档为准，别把版本号写死在镜像里而不做校验。

边界同样明显。自动布局对大图不友好，节点一多容易出现长连线与交叉，需要拆子图或改成多层结构。它适合中等规模的流程图与时序图，不适合当作大型架构的模型库。

D2 与 Graphviz：布局控制的两种取向

D2 面向“写起来像句子”的场景，箭头、容器嵌套、多方向布局的语法都比较直接，官方文档站是 d2lang.com。项目采用 MPL-2.0，源码在 GitHub 的 d2lang/d2。

它内置三个布局引擎：Dagro 为默认，走分层布局；ELK 适合带端口的有向图；TALA 专为软件架构图设计，需要用 --layout=tala 显式开启。导出格式包括 SVG、PNG、GIF、PDF 与 PPTX，PDF 和 PPTX 对接汇报场景比较省事。

Graphviz 走的是另一条路。它用 DOT 描述节点与边，把排版交给算法，dot、neato、fdp、sfdp、twopi、circo 分别对应分层、弹簧、径向与环形布局。官方下载页 按 14.x 与 15.x 分列安装包，许可为 Eclipse Public License。

把这两者放在一起看会更清楚：D2 想让你少写样式、结果稳定；Graphviz 想让你把关系交给引擎、规模优先。几百个节点的依赖图，用 DOT 生成再看效果，比手写节点坐标省力得多。

PlantUML 与 Structurizr：UML 与 C4 的分工

PlantUML 的强项是 UML 覆盖较完整，类图、时序图、组件图、用例图、状态图都有成熟写法，中文社区资料也多。它跑在 JVM 上，一个 jar 就能启动本地服务。

许可常被误读。官方 下载页 同时提供 GPL、LGPL、Apache、BSD、EPL、MIT 等多个构建：GPL 版带 ditaa、Jcckit 等集成，LGPL 版去掉了内嵌 GraphViz，EPL 版带 ELK 布局。选哪个版本，取决于你能否接受 GPL 的传染性，而不是“它是不是开源”。版本号按年份编排，2026 年为 1.2026.x。

Structurizr 解决的是另一个问题：一个模型出多张图。你在 Structurizr DSL 里描述系统、容器与关系，再生成 System Landscape、System Context、Container、Component、Dynamic、Deployment 六类视图。它由 C4 模型作者 Simon Brown 维护，是该模型的参考实现。

工具形态上，它有浏览器 playground、本地单机版、自托管服务端与导出 CLI。核心代码为 Apache-2.0，服务端是 open core：自行构建免费，预编译的企业版二进制需要授权。CLI 还能把视图导出成 PlantUML、Mermaid 或静态 HTML 站点，等于给前两种语法补了一条衔接路径。

Kroki：用一个接口统一渲染

Kroki 本身不是一种语法，而是一层 HTTP 封装。它把 PlantUML、Mermaid、D2、GraphViz、Structurizr、C4-PlantUML 等三十多种图语言收进同一套接口，用 GET 加 deflate+base64 编码，或用 POST 直接提交源码。

它的价值在于渐进迁移。老项目里的 PlantUML 文件继续能渲染，新写的图可以换 D2，调用方只需要改 URL 里的语言段。Kroki 采用 MIT 许可，官方提供免费公共服务，也可以用 Docker 或 Kubernetes 自建，适合内网与离线构建。

自建的常见做法是把它挂在内网，构建脚本用 POST 提交源码，拿回 SVG 后直接写进文档目录。这样一来，文档站不必装四五套渲染器，升级也集中在一个镜像上。

需要注意输出格式并不统一。同一个接口下，GraphViz 能出 PNG、SVG、JPEG、PDF，PlantUML 还多一个 txt，而 D2 目前只出 SVG。若流水线里要固定拿 PNG，得按语言分别核对。

架构图工具怎么组合：三种搭配

• 文档为主：Mermaid 写进 README 与设计文档，Kroki 负责 CI 里批量导出静态图，避免依赖具体平台的渲染。
• 架构为主：Structurizr 维护一份 C4 模型，导出 PlantUML 或 Mermaid 给不装工具的同事看，模型与图不再各写一遍。
• 生成关系图为主：用脚本把服务依赖、K8s 资源或数据库表结构拼成 DOT，交给 Graphviz 出图，人只维护数据源。

如果团队只需要流程图，Mermaid 单独用就够了，引入第二套语法只会增加维护面。想要更自由的画布，可以看 Excalidraw 这类手绘白板，它解决的是草稿阶段的表达，而不是可版本化的图纸。

把图纳入流水线时，还有两个小问题值得提前处理。一是中文字体，容器里缺字体时标签会变成方块，Docker 镜像要显式装上中文字体包。二是渲染结果不稳定，布局引擎升级后同一份源码可能微调位置，归档场景应固定渲染器版本。

Structurizr 新增的 MCP 服务端也算一条新线索：它能解析与校验 DSL，并把工作区导出成 PlantUML 或 Mermaid，接进 AI 助手的流程后，改模型不必再手动敲命令。这类集成还在早期，用之前建议先读 MCP 协议的边界，评估权限与数据流向。

最后一点经验：图即代码的收益来自评审，不来自语法本身。选一个团队都愿意改的写法，把渲染命令固定进 Makefile 或 CI 任务，比在四种语法之间反复横跳更有用。

相关地址

以下为文中各项目的官方入口，版本、许可与接口细节以这些页面为准。

• Mermaid（官网）：https://mermaid.js.org/
• Mermaid（GitHub 仓库）：https://github.com/mermaid-js/mermaid
• D2（官网文档）：https://d2lang.com/
• D2（GitHub 仓库）：https://github.com/d2lang/d2
• Graphviz（官网）：https://graphviz.org/
• Graphviz（下载页）：https://graphviz.org/download/
• PlantUML（官网）：https://plantuml.com/
• PlantUML（下载与许可）：https://plantuml.com/download
• Structurizr（官网）：https://structurizr.com/
• Structurizr DSL（GitHub 仓库）：https://github.com/structurizr/dsl
• Kroki（官网）：https://kroki.io/
• Kroki（GitHub 仓库）：https://github.com/yuzutech/kroki