架构图生成工具避坑指南：自动布局画得快，画得对是另一回事

dctc_青龙

[TITLE]
架构图生成工具避坑指南：自动布局画得快，画得对是另一回事
[/TITLE]

[CATEGORY]
tech
[/CATEGORY]

[KEYWORDS]
华强北,memU / MemU ,科技数码,AI,热点
[/KEYWORDS]

[FID]
41
[/FID]

[CONTENT]# 架构图生成工具避坑指南：自动布局画得快，画得对是另一回事

这几年架构图工具的卖点几乎一模一样：不用拖拽、不用对齐、不用一个像素一个像素地抠，写段文本或者说句人话，图就出来了。演示的时候确实爽。可一旦接进真实的工程流程，问题会集中爆发——它们解决的是"画"的成本，没解决"画对"这件事。

自动布局之所以看着能用，是因为演示图大多只有七八个节点，单层调用，谁也不依赖谁。真实系统不长这样。一个中等规模的后端，网关、鉴权、业务服务、消息中间件、缓存、存储，再挂几个三方接口，四五十个节点是常态，跨层调用和反向依赖到处都是。这个体量，正好落在布局引擎开始失控的区间。

## 自动布局的边界：能渲染，不等于能读

主流方案其实就两条路线。PlantUML 底层还是 Graphviz 的 dot；Mermaid 早期默认 dagre，某些场景能切 ELK；D2 同样把布局交给 dagre 和 ELK，另外自己搞了一套 TALA。这些引擎大多走分层绘制（layered drawing）的路子，三步走：按依赖把节点切层，再定每层内部的顺序来减少交叉，最后算坐标、绕障碍连线。

麻烦出在第二步。层内排序本质是求"最少交叉"，节点一多就没法精确解，所有引擎用的都是启发式近似。同一份图，换个参数、升个版本，排出来的次序就能不一样。这也是为什么同一段代码，本地渲染和在 CI 里渲染，版本差一点就可能得到完全不同的版面。评审时有人问"数据库怎么跑到左边去了"，没人答得上来。

症状基本能列成一张清单：

- **连线穿过节点**：跨层调用被迫绕路，线压在文字上，读图全靠猜；
- **标签叠在一起**：边上的协议名、端口号堆成一坨，放到 200% 还是糊的；
- **分组框错位**：subgraph / container 的边框和子节点对不齐，看着像子节点跑出去了；
- **层级判断失真**：引擎把"查数据库"和"发 HTTP 请求"当成同一种边，排出同一个方向；
- **版面乱抖**：改一个标签的字，整张图重排。

社区里对规模的共识大概是：五十个节点以内、没有嵌套容器，dagre 还凑合；一旦层次密起来，交叉和间距问题会肉眼可见地恶化，这时候才轮到 ELK 上场。

更要命的是，布局引擎不懂语义。它不知道哪个是边缘网关、哪个是外部依赖、哪个是早该删掉的历史包袱，只能按拓扑关系机械排。你也没法跟它说"支付那三个服务必须放一块"，除非手动指定坐标——可一旦开始手填坐标，自动布局还剩多少价值？

D2 在这块想了另一条路。它的 TALA 引擎是专门为软件架构图设计的，支持容器级方向，能用 `near` 把某个形状钉在另一个旁边，用 `top`/`left` 锁位置，连数据库表的连线都能指到具体某一行。代价官方文档自己写在 cons 里了：TALA 带随机性，改个标签就可能级联出完全不同的版面。想要确定性，就得退回 dagre 或 ELK，然后回到同一个老问题。

## 渲染器版本：比布局更难控的变量

Mermaid 的生态优势来自 GitHub、GitLab、Notion 的原生渲染，嵌进文档几乎零成本。代价是渲染结果被目标平台的渲染器版本卡着——同一段 `graph TD`，在不同产品里显示得不一样，跨团队协作时这种偏差反复出现。

这坑最近一年更明显了。Mermaid 12.0.0 是个破坏性版本，把 ELK 打进主包，还设成 flowchart、state、class、ER、requirement 这些图类型的默认布局，默认主题换成 neo 外观，运行环境要求 ES2024。也就是说，同一份文件在 11.x 和 12.x 下渲染，不只是排版不同，连配色和字体观感都两码事。而各平台什么时候升级，用户说了不算：文档站升了，代码托管平台可能还锁在旧版；draw.io 的文档写得很清楚，图类型默认仍走 dagre，只有显式配置才切 ELK，环境里找不到 ELK 还会自动回退。

于是就有了很典型的一幕：作者在自己机器上写 `layout: elk`，版面调得挺满意，提交到仓库，评审页面看到的是 dagre 排出来的另一张图。两边讨论的根本不是同一张画。

可控的做法三条：

1. **把渲染结果当产物提交**。CI 里渲一次，SVG 落进仓库，评审看产物，不看平台实时渲染；
2. **锁版本**。`package.json` 里钉死 mermaid 主版本，本地预览和 CI 用同一个；
3. **跨平台图别用新特性**。要到处显示的图，避开 `layout`、`defaultRenderer` 这类依赖渲染器支持的配置，语法越保守越好。

## 图表即代码：维护成本被系统性低估

图跟代码一起放仓库、随 PR 更新，听着很工程化，真跑起来，多数团队三个月内就放弃了。

衰减曲线大概长这样：第一周兴致最高，DSL 写得极细，连端口都标；第一个月碰上第一次服务拆分，改图的人发现要动十几处引用，PR 里图的部分被单独拆出来往后放；第三个月，图里的服务名和线上已经对不上，但没人愿意从头捋，于是这张图进入"还在仓库里，但没人看"的状态。

原因在于架构图有它自己的变化规律。服务拆分、改名、部署形态变更，决策往往发生在图之外，而改 DSL 的人通常不是做决策的人。结果就是图里描述的仍是两个季度前的结构，比一张静态截图更容易误导人——它自带"随时同步"的可信度暗示，读者默认它是最新的。

业内管这个叫架构漂移（architecture drift）。代码坏了会立刻报错，测试挂、构建挂、告警响，都是即时信号；过期的架构图只会安安静静挂在那儿，等着把下一个翻它的人带偏。做安全评审时尤其危险：图上画的边界防护可能早撤了，新接的三方数据流也不会自己长上去。

Structurizr 用 C4 模型加 DSL 来对付这件事，系统上下文、容器、组件分层管理，一份模型出多个视图，思路清楚，也是 C4 作者本人的参考实现。但学习曲线和团队接受度是硬门槛——让全组接受"先改模型再出图"，比让他们学会写 Markdown 难太多。绝大多数团队的实际选择是：图照旧画在 Lucidchart 或 draw.io 里，仓库只留一份导出文件。

## AI 生成：错误成本最高的一类

这两年新加的"自然语言生成架构图"，是最需要在评审里保持警惕的一类。

问题不在画得难看，而在画得过于合理。大模型看着一段需求描述生成的图，会自觉补齐负载均衡、消息队列、缓存层、监控告警——这些在真实系统里未必存在，图上却标得齐全又规范。对不熟悉这套系统的人来说，它比手绘草图更有欺骗性，因为看着就像经过严谨设计的。

常见情形是这样：需求文档写"支持高并发下单、保证库存不超卖"，AI 大概率给你 API 网关 + 订单服务 + 库存服务 + Redis + Kafka 削峰 + 分布式锁一整套。而团队实际实现可能只是数据库行锁加一层本地缓存，量级远没到要削峰的地步。图交上去，评审会第一句话就变成"我们什么时候上的 Kafka"，然后花二十分钟解释这张图不代表现状。

代码反向生成也一样。从配置或 IaC 文件推断拓扑的工具，遇到动态注册、服务网格、sidecar 注入这些模式，经常丢链路，输出的图表面完整，关键调用路径却漏了。拿去对外汇报还行，用来定位故障就是负资产——排障最怕的，就是拿着一张"看着全对"的图去找一个不存在的服务。

这里有条容易混的边界。现在的 AI 工具确实越来越"懂上下文"：接上项目记忆、接上 memU 这类面向 agent 的记忆框架，模型能记住你们团队的命名习惯、历史决策、上次为什么弃掉某个中间件。但懂上下文和画得对是两件事——记忆能让图更像你们家的风格，验证不了线上真实的调用链。图的正确性只能来自能核对的证据：流量日志、链路追踪、资源配置清单。

判断一张 AI 生成的图能不能用，逐个组件问三个问题就行：

- 这个组件在生产环境里**有实例**吗？监控面板上找得到吗？
- 它和上下游的**调用方向**对吗？是被调用，还是主动去拉？
- 这条边上的**协议和数据格式**写对了吗？同步还是异步？

三个问题只要有一个答不上来，这图就只能当草稿。四十个节点里通常有六到十个是幻觉出来的，比例不算高，但足以让整张图的结论失效。

## 四类工具的失效场景对比

| 类型 | 代表 | 价格档位 | 主要失效场景 | 适合谁 |
|---|---|---|---|---|
| 文本渲染 | Mermaid / PlantUML / D2 | 免费开源 | 复杂版面不可控，跨平台渲染不一致 | 文档内嵌小图、README 模块关系 |
| 模型驱动 | Structurizr / IcePanel | Structurizr 开源，Server 版需授权；IcePanel 免费档 1–5 名编辑、100 个模型对象，Growth 40 美元/编辑/月，Scale 80 美元/编辑/月 | 学习成本高，团队难以长期遵守 | 有专职架构角色、需要多视图的中大型团队 |
| 云架构绘制 | Cloudcraft（Datadog 旗下） | 随任一 Datadog 订阅免费，不限用户与图数 | 只覆盖云上资源，混合架构得手工补 | 已用 Datadog 且以公有云为主的团队 |
| 通用协作画布 | Lucidchart / draw.io | Lucidchart 免费档 3 份可编辑文档、单文档 75 个图形（早期 60 个，历史上改过多次）；付费按席位 | 无自动布局，规模上去靠人力维护 | 需要多人实时编辑和汇报级排版的团队 |

表里最容易被忽略的是免费档的具体限制。Lucidchart 那个单文档图形数，连线和文本框一起算，一张四十节点的图加上连线标签，画到一半就容易触顶。而这个阈值历史上从 60 调到 75，本身就说明它是个会变的商业参数，不适合当选型前提。开源方案在生成能力上并不落后，缺的是多人实时编辑和版本对比——偏偏这两项才是评审阶段真正用得上的。

## 成本核算：按席位计费的真实账

按席位收费的工具，十人以上团队用起来不便宜。拿 IcePanel 的 Growth 档举例，四十美元单价看着还行，十名编辑一年就是四千八百美元。如果团队里一半人只是看图、不参与编辑，那就该用它的查看者不限量策略，把编辑席位压到三到五个。这一步没做，账单无声翻倍。

真正的隐性成本在别处：培训、迁移、导出锁定。一个团队从 draw.io 迁到模型驱动工具，光是把已有的二十几张图重新梳理、抽象成模型对象，通常就得投两周以上人力；万一最后流程不匹配放弃了，这部分纯亏。选型时更实在的做法是先拿一个真实项目试跑，两周只干一件事——看这个工具能不能表达你们最复杂的那张图。

## 不建议使用生成工具的场景

强监管系统的合规架构文档、跨组织的接口边界说明、要当合同附件的部署拓扑——这三类图，错误成本远高于绘制成本，逐项人工确认还是省不掉。

说具体点，凡是图上每根连线都可能被人拿去追责的场合，都别交给自动生成：

- 审计和合规申报材料，图就是证据，错一个数据流向就是实质问题；
- 甲乙双方签署的技术附件，图是责任边界；
- 故障复盘里用来定位的调用链图，画错了直接把排查引向错误方向；
- 涉及数据跨域、跨境流动的说明，一条边画错就是合规风险。

适合交给工具的，是那些"本来就要重画很多次"的图：日常评审的数据流草图、README 里的模块关系、临时对齐用的部署示意。这类图寿命以天计，自动化的收益盖得住精度损失。

## 一套可以落地的折中流程

别在"全自动"和"全手工"之间二选一，按用途分层是成本最低的：

- **草稿层**：文本渲染或 AI 生成，允许不精确，用来讨论和拉齐认知，出了会议室就能删；
- **评审层**：人工在协作画布上排，只留当前决策相关的十到二十个节点，其余折叠；
- **归档层**：模型驱动或手工绘制，随版本发布更新，带更新日期和责任人；
- **对照层**：从监控、链路追踪或云资源清单导出的真实拓扑，只用来校验上面三层，不对外。

每张图在角落标两行字——最后更新时间、负责确认的人。这两行比任何自动化都管用，因为它把"这图可信吗"变成能立刻回答的事实。华强北这边做硬件供应链系统的团队尤其吃这一套：SKU、仓、物流、报关几套系统对接方太多，谁也不敢说自己记得住全貌，图上有个明确责任人，比多买一套工具更解决问题。

## 趋势判断

接下来一两年，架构图工具的分化会沿着"可信度"走，而不是继续拼生成速度。可验证性会变成卖点——图跟真实资源、真实调用链的比对能力，比一句描述出图重要得多。苗头已经能看到：工具开始提供漂移评分、模型与云资源自动对账、把图挂到监控面板上点击下钻。Structurizr 这类模型驱动方案会慢慢渗透进中大型团队，纯 AI 生成则长期停在草稿层。

科技数码这行的工具迭代一向如此，功能列表每季度都在变，工程上的判断标准却变得很慢。在那之前，一个务实的判断标准是：这张图要是画错了，谁会付出代价。答案越具体，越该手工确认。

你们团队现在还在维护多少张"没人看但一直在仓库里"的图？