用AI生成架构图：从代码扫描到依赖分析的全流程实践

打开你电脑里三年前的那个老项目README 里写着“微服务架构”实际代码里 Service 层两万行起步调用关系像一碗没搅开的面条。领导让你画一张架构图给新人做培训你盯着 IDE 里的类名列表沉默了十分钟。这是很多开发者真实的日常。过去画架构图靠的是人肉读代码、查依赖、理调用链再打开绘图工具一点点拖拽连线。一个中型项目光梳理关系就要大半天画完还要担心图过期。现在 GitHub 趋势榜上频繁出现一类项目把代码仓库交给 AI由大模型自动分析项目结构、依赖关系、模块边界直接生成架构图。这个思路正在改变“画架构图”这件事的底层逻辑。但这里要先把一个判断说清楚这类工具真正降低的不是“画图”的成本而是“读代码”的成本。以前我们缺的不是绘图软件而是能从代码里快速提炼架构信息的能力。AI 架构图工具补上的正是这一环。同时它也带来一个新的问题AI 生成的架构图未必完全正确需要人工校验否则你只是把“人肉读代码”换成了“人肉检查 AI 读代码”。这篇文章会从原理、适用场景、环境准备、核心流程、代码实现、结果验证、常见问题和最佳实践几个角度把“用 AI 自动生成架构图”这套方法讲透。读完你应该能判断自己的项目适不适合用这种方式以及真正落地时会踩到哪些坑。1. 为什么“AI 生成架构图”最近这么火先看一个普遍现象很多团队根本没有架构图。不是因为大家不想画而是画架构图的投入产出比太低。我接触过的项目大概分两类。第一类是刚启动的新项目架构相对清晰画图意愿强但项目一旦进入快速迭代图就很快过期。第二类是维护多年的老项目人员换了好几拨文档本来就少代码已经成了“唯一的事实来源”。想让新人理解系统只能靠老员工口头讲或者自己一行行读代码。传统方式画架构图的流程是这样的先通过 IDE 的项目结构、类名、包名做初步判断再用 Maven/Gradle 依赖分析工具梳理库依赖再用监控系统或日志整理服务调用关系最后打开绘图工具手动绘制。这个流程有几个明显问题代码量大人工分析容易漏。依赖关系和调用链复杂图一旦画错反而误导新人。绘图本身耗时画完往往已经过时。团队缺少统一规范每个人画出来的图风格都不一样。AI 架构图工具出现后流程变成了把代码仓库交给 AI 工具工具先扫描代码获取项目结构、包名、类名、依赖声明、调用关系等信号再把信号交给大模型做推理分析最终生成一份结构化的架构图描述。这个流程把“人肉读代码 手动绘图”压缩成了“自动化扫描 自然语言生成”。从技术层面看AI 生成架构图之所以能火是因为两类技术的成熟一是代码分析工具已经能稳定提取 AST抽象语法树、调用图、依赖图等信息二是大模型对代码结构的理解能力提升明显能根据这些结构化信息补全语义。二者结合才让“自动生成架构图”从玩具变成了可用的工具。所以说GitHub 趋势榜上这类项目走红本质上反映的是开发者的一个朴素需求架构文档不应该成为项目的奢侈品而应该是可以随代码一起维护的日常产物。2. 核心原理AI 是怎么“看懂”代码结构的要理解 AI 架构图工具先要搞清楚它不是直接拿着整个仓库的源码“阅读”而是有一套工作流程。市面上的工具实现方式各有差异但核心原理通常包含以下四个环节。第一个环节是扫描。工具会遍历代码仓库读取项目目录结构、包名、模块名、源码文件。不同语言的扫描策略不同Java 项目看 Maven/Gradle 配置和 jar 包依赖Python 项目看 import 语句和 requirements/pyproject 文件前端项目看 package.json 和目录结构。第二个环节是解析。工具调用语言编译器或解析器生成 AST再基于 AST 分析类之间的继承、组合、依赖关系方法之间的调用关系以及模块与模块之间的依赖。这一步输出的是结构化数据比如“OrderService 调用了 OrderRepository 的 findById 方法”。第三个环节是归纳。工具会把结构化数据中的噪声过滤掉按模块、层、服务等维度做聚合。比如一个订单系统可能有几十个类但归纳后大体可以分成 Controller 层、Service 层、Repository 层、外部接口层。第四个环节是生成。工具把归纳后的结构信息输入大模型配合提示词要求让模型输出架构图描述。常见的输出格式有 Mermaid 文本、PlantUML 文本、JSON 结构化数据或者直接调用绘图接口生成 PNG/SVG 图片。这里要特别强调一点很多 AI 架构图工具看起来“智能”但真正下功夫的是前三个环节。如果代码扫描和依赖分析做得不准确大模型再聪明也分析不出正确的架构。举个例子假设有一个订单服务类名是 OrderServiceImpl它注入了 OrderRepository 和 PaymentClient。扫描工具如果只拿到类名不知道 OrderRepository 属于数据访问层PaymentClient 属于外部服务客户端那么生成出来的架构图就可能把数据访问层和外部服务画在同一层。所以工具的归纳能力取决于它对项目脚手架、包名规范、框架约定的理解程度。从使用者的角度看你不需要掌握 AST 和大模型推理的所有细节但理解这个流程非常重要。因为它决定了你能对 AI 生成的结果做什么样的校验也决定了在什么情况下 AI 会画错。3. 适用场景与边界哪些项目适合哪些不适合先说适合的场景。微服务项目是最典型的场景。一个微服务仓库里可能有几十个服务模块服务之间通过 HTTP、消息队列或者 RPC 通信。人工梳理服务调用关系非常耗时而 AI 工具可以通过扫描配置文件和代码调用快速生成服务级别的依赖图。这张图对新人理解系统、对团队做架构评审、对排查链路故障都有直接帮助。遗留老系统也是很好的场景。这种项目通常代码量大、文档少、人员流动大。AI 工具可以作为一个“快速入门助手”让你在接手项目的第一周就拿到一张可参考的架构草图。虽然是草图但比自己从头读代码高效得多。还有一个容易被忽略的场景代码评审和架构治理。如果团队规定新代码必须绘制架构图纯靠人工很难坚持。引入 AI 自动生成后可以在每次提交时自动更新架构图把“画图”变成 CI/CD 流程里的一环。再看不适合的场景。第一纯前端 CSS/UI 代码占比很高的项目。这类项目的架构重点在于组件的组织方式和状态管理AST 扫描很难捕捉到“业务组件如何拆分”这种语义信息AI 生成的图容易停留在“目录结构图”层面价值有限。第二架构极度不规范的项目。如果一个项目的包名混乱、类职责不清、依赖关系是一团乱麻AI 生成出来的架构图也会是一团乱麻。工具只是把代码的现实情况如实反映出来并不能把混乱的代码变成清晰的架构。第三对架构图精度要求极高的场景。比如航空航天、医疗器械等安全关键领域系统架构图是合规资产的一部分需要多方评审确认。AI 生成的图只能作为参考草稿不能直接作为正式交付物。这里要给出一个清楚判断AI 架构图工具擅长回答“系统里有什么、谁依赖谁”但它不能回答“为什么这样设计”“这里哪里不合理”。前者是描述性问题后者是评价性问题。AI 能帮你高效完成描述评价还是得靠人。4. 环境准备与前置条件理解了原理和边界接下来是实操环节。由于 AI 架构图生成工具种类很多有在线 SaaS 产品有开源命令行工具也有 IDE 插件这里不绑定某个具体项目而是用一套通用的最小实践来讲。在开始之前你至少要准备四样东西。第一一份可访问的代码仓库。代码最好能正常 clone 到本地网络环境要能保证依赖下载。如果你平时访问 GitHub 不稳定需要先确认团队内部是否有合规的代码托管平台先把仓库托管到国内可访问的位置否则后续分析会因为网络问题反复失败。第二一套本地开发环境。不同语言需要不同的工具链。比如分析 Java 项目需要 JDK 和 Maven/Gradle分析 Python 项目需要 Python 解释器和 pip。最低要求是能在命令行执行构建或测试命令因为代码分析工具可能需要借助语言工具链完成依赖解析。第三一个大模型 API 的访问凭证。无论你用的是开源大模型部署的本地服务还是云端 API都需要能通过 HTTP 调用模型接口。没有模型凭证工具就只能做代码扫描无法生成架构描述。第四一个输出载体。架构图最终要以某种形式呈现给团队。常见选择包括 Markdown 文档中的 Mermaid 文本、项目管理平台上的图片附件、知识库里的结构化页面。建议刚开始用 Markdown 图片方便版本管理和分享。如果你拿不准版本记住一个原则以你实际项目使用的版本为准。比如项目里是 Java 8分析工具就不能用要求 Java 17 的版本。本文后面会给出通用脚本不依赖任何特定版本。5. 用最小示例跑通“代码 → 架构图”全流程为了讲清楚全过程我们构造一个最简单的 Python 项目作为示例。项目的目录结构如下demo-order/ ├── main.py ├── services/ │ ├── order_service.py │ └── payment_service.py ├── repositories/ │ └── order_repository.py └── models/ └── order.py这个项目模拟了一个订单模块的简化场景main.py 是入口OrderService 调用了 OrderRepository 和 PaymentServiceOrderRepository 依赖 Order 模型PaymentService 模拟外部支付调用。第一步我们需要用 Python 脚本扫描 import 关系。这里不引入复杂的 AST 库就用 Python 标准库中的 ast 模块做一个最小实现。# 文件路径scan_imports.py import ast import os import sys from collections import defaultdict def extract_imports(file_path): 使用 AST 解析 Python 文件提取 import 语句和 from ... import ... 语句。 with open(file_path, r, encodingutf-8) as f: tree ast.parse(f.read()) imports set() for node in ast.walk(tree): if isinstance(node, ast.Import): for alias in node.names: imports.add(alias.name.split(.)[0]) elif isinstance(node, ast.ImportFrom): if node.module: imports.add(node.module.split(.)[0]) return imports def scan_project(root_dir): 遍历项目目录统计每个文件依赖了哪些顶层模块。 dependencies defaultdict(set) for current_dir, _, files in os.walk(root_dir): if __pycache__ in current_dir or .git in current_dir: continue for file_name in files: if not file_name.endswith(.py): continue file_path os.path.join(current_dir, file_name) rel_path os.path.relpath(file_path, root_dir) imports extract_imports(file_path) dependencies[rel_path].update(imports) return dependencies if __name__ __main__: root sys.argv[1] if len(sys.argv) 1 else . result scan_project(root) for file_path, imports in sorted(result.items()): print(f{file_path}: {, .join(sorted(imports))})这个脚本做的事情很简单遍历目录下所有 Python 文件用 AST 提取 import 语句然后输出每个文件相对路径和它依赖的顶层模块。运行方式python scan_imports.py demo-order预期输出类似main.py: services models/order.py: repositories/order_repository.py: models services/order_service.py: models, repositories, services services/payment_service.py: models这一步的输出其实已经是一份依赖清单。人眼可以从这个清单里判断出order_service 依赖 order_repositoryorder_repository 依赖 order 模型main 依赖 services。但这样的清单还不够直观我们需要把它转化成图形。第二步写一个脚本把依赖清单转换成 Mermaid 文本。Mermaid 是一种用文本描述图表的语法很多 Markdown 编辑器、GitLab、GitHub 都原生支持渲染。我们生成的是 graph LR 类型的有向图。# 文件路径generate_mermaid.py from scan_imports import scan_project import sys def to_mermaid(dependencies): 将依赖关系转换为 Mermaid 有向图文本。 lines [graph LR] for file_path, imports in sorted(dependencies.items()): # 模块名去掉 .py 后缀和路径分隔符方便展示 node_name file_path.replace(.py, ).replace(/, _).replace(\\, _) lines.append(f {node_name}[\{file_path}\]) for dep in imports: dep_name dep.replace(/, _).replace(\\, _) lines.append(f {node_name} -- {dep_name}) return \n.join(lines) if __name__ __main__: root sys.argv[1] if len(sys.argv) 1 else . deps scan_project(root) print(to_mermaid(deps))运行python generate_mermaid.py demo-order输出的 Mermaid 文本类似graph LR main[main.py] -- services models_order[models/order.py] repositories_order_repository[repositories/order_repository.py] -- models services_order_service[services/order_service.py] -- models services_order_service[services/order_service.py] -- repositories services_order_service[services/order_service.py] -- services services_payment_service[services/payment_service.py] -- models把这段文本粘贴到支持 Mermaid 渲染的 Markdown 编辑器里就能看到模块依赖图。第三步引入大模型做语义归纳。分析 import 关系只能得到“文件依赖了谁”但看不出“哪个类是 Controller、哪个类是 Service、哪个数据访问层”。为了让架构图更有语义我们可以把依赖清单作为上下文输入大模型要求模型按照分层架构重新组织并输出 Mermaid 文本。这个步骤通常会用提示词来完成。下面是一个可复用的提示词模板你是一名资深软件架构师。下面是一个项目的模块依赖清单 {依赖清单} 请按以下要求输出 1. 识别 Controller 层、Service 层、Repository 层、Model 层 2. 用 graph LR 语法绘制分层架构图 3. 只输出 Mermaid 代码块不要额外解释。关键点是把扫描脚本的输出结果粘贴到{依赖清单}位置。模型会基于文件命名和依赖关系推断层次然后输出一份更接近“架构图”的 Mermaid 文本。这里的步骤没有一个固定的命令行工具能够一键完成实际使用中你既可以用 OpenAI、通义千问等模型的在线对话界面操作也可以用 Python 脚本调用 API 接口。需要注意的是调用大模型 API 时不要直接把整个仓库源码塞进去。一是 token 成本很高二是源码里可能包含敏感信息。正确做法是把扫描脚本生成的结构化摘要作为上下文最多补充少量关键文件的关键代码片段。到这一步我们已经完整跑通了一个“代码扫描 → 依赖提取 → 大模型归纳 → Mermaid 输出”的最小闭环。虽然示例是 Python 项目但同样的思路可以扩展到 Java、Go、TypeScript 项目只是扫描脚本需要改用对应的编译器或解析器。6. 运行结果与效果验证跑完上一节的三个脚本后怎么判断结果是好的还是坏的不要只看“能不能生成图”。生成图很容易生成一张正确的图才是目标。我建议从三个层面验证。第一验证文件级依赖是否准确。拿 Mermaid 生成的图回到 IDE 里抽查几个关键节点。比如图中显示order_service.py依赖models就要去 IDE 里看 import 语句是否真的存在。如果扫描脚本本身有 bug比如漏掉了from repositories.order_repository import OrderRepository这种导入图中就会丢失一条边。文件级依赖是后续所有分析的基础这层出错上层必然出错。第二验证分层是否合理。大模型生成的架构图里如果order_service.py被归到了 Repository 层说明模型判断错误。这时候需要检查文件命名是否规范或者提示词里是否需要补充项目背景信息。很多情况下分层错误不是模型笨而是项目命名实在太随意模型无从判断。第三验证图的表达能力。一张好的架构图核心价值是让人一眼看懂系统的骨架。如果生成的图连了无数条线密密麻麻挤成一团说明聚合程度不够。这时候应该调整提示词要求模型按“包级依赖”或“模块级依赖”输出而不是文件级依赖。对运行结果的预期我用一个判断来总结AI 生成的架构图应该达到“参考级”质量而不是“交付级”质量。所谓参考级就是你花 10 分钟复核后能拿来讲解、评审、培训。所谓交付级是经过架构师正式评审、纳入项目文档并在后续流程中维护的资产。当前阶段的 AI 工具更多是帮你快速生成第一版参考级架构图再靠你把它打磨成交付级。如果生成过程中发现 Mermaid 语法渲染失败第一优先检查中文符号。文件名中如果有中文括号、空格、特殊字符会导致节点定义出错。建议生成后先检查一遍 node 字符串是否包含非 ASCII 字符或特殊符号。7. 常见问题与排查思路在实际使用 AI 架构图工具的过程中下面这些问题出现频率最高。我把它们整理成一张排查表方便你按图索骥。问题现象可能原因排查方式解决方案扫描脚本没有输出任何依赖项目目录传错或 Python 文件不在指定目录下检查命令行路径参数确认目录存在先打印项目目录列表确认文件位置import 扫描结果明显不完整项目使用了动态导入或包内相对导入查看报错文件和 AST 分析结果补充处理相对导入或用语言自带的依赖解析工具生成的 Mermaid 在编辑器里渲染失败文件名包含特殊字符或中括号冲突检查 node 定义字符串是否合法对文件名做转义或使用 id 代替文件名大模型生成的分层结果混乱项目命名不规范或提示词缺少背景抽查 3 到 5 个关键类判断误分层原因在提示词中补充项目背景、包结构样例输入源码过大调用 API 超时一次性塞入的上下文太长检查请求体大小和 token 用量使用扫描结果摘要不要直接传源码文件生成的架构图太密集无法阅读层级粒度过细按文件级生成了所有关系统计图的节点数和边数提示词中要求按包或模块聚合结果与真实服务调用不一致扫描工具不支持某种语言或框架特性查看扫描日志确认语言支持范围换用对应语言的分析器或补充人工修正生成结果不稳定每次都不一样大模型生成具有一定随机性调整温度参数或提示词约束格式降低随机性要求模型输出固定格式的 JSON 或 Mermaid这里特别想展开讲一下动态导入的问题。以 Python 为例importlib.import_module(module.name)这种方式在 AST 阶段只能看到字符串参数无法判断它真实导入了哪个模块。如果项目大量使用动态导入扫描脚本会漏掉关键关系。遇到这种情况一个补救办法是结合测试覆盖率或者运行时调用链数据来补充依赖关系。另一个容易被忽略的问题是架构图会过期。代码每天都在变但图不会主动变。如果团队决定用 AI 生成架构图建议把它接入 CI/CD每次代码合并后自动重新生成并提交到文档仓库。否则三个月后这张图又是过期的和没有图没有本质区别。8. 最佳实践与工程建议把 AI 生成架构图从“玩一玩”变成工程实践有五个建议值得认真对待。第一个建议是分层分模块生成不要一次生成整仓架构图。如果仓库特别大一次性把全仓代码交给 AI 工具不仅效果差而且成本高。更实用的方式是先按模块生成局部架构图再手工拼接成系统全局图。比如先画订单模块内部图再画订单模块与其他模块之间的依赖图最后合成系统级架构。这样每一层图都比较清晰也方便不同团队维护自己的部分。第二个建议是提前约定项目结构规范。AI 生成架构图的质量和项目代码的规范程度强相关。一个包名叫utils、里面什么类都放的仓库无论 AI 多强都很难画出一张清晰的分层架构图。反过来如果项目遵循“controller / service / repository / model”的标准分包方式AI 很容易就能识别层次。从这个角度看AI 架构图工具不只是一张图的生成器更是一面镜子能反射出项目代码的健康程度。第三个建议是不要把敏感信息发给在线大模型。代码仓库里经常包含数据库连接信息、内部域名、算法逻辑、未公开的业务规则。直接把整个仓库喂给云端 API 存在信息泄露风险。稳妥的做法是先做本地脱敏替换掉 IP、账号密码、内部域名再生成结构摘要或者优先使用公司内部部署的开源大模型服务。涉及法律合规或商业机密时更要谨慎。第四个建议是架构图也纳入代码评审范围。如果团队把“架构图是否与代码一致”作为代码评审的一项检查点相当于强制大家维护架构图。很多团队用 AI 生成一次架构图后就不再更新核心原因是缺少机制。这里有一个轻量做法在 README 里放一个生成脚本文档写明“执行python generate_mermaid.py .即可更新架构图”让生成动作的成本降到最低。第五个建议是保留人工校验和复核流程。AI 生成架构图的结果不能直接进正式文档。建议至少经过一次团队内部评审让熟悉系统的开发者检查依赖关系、模块划分和边界描述。评审时重点关注三件事一是图中是否出现了不存在的依赖二是是否遗漏了关键的外部系统三是分层是否符合团队对系统的理解。这三个点确认没问题图才真正可信。除了这五条建议还有一个值得尝试的方向把架构图生成能力和团队的知识库结合起来。AI 生成的架构图可以作为新员工入职培训的入门资料也可以作为故障排查时定位服务的辅助工具。如果团队使用 Confluence 或语雀这类知识库可以把图定期同步上去并标注生成时间避免大家误把旧图当新图。9. 总结与后续实践方向回到最初的问题把代码交给 AI自动生成架构图这件事到底解决了什么它解决的是“从代码到架构认知”这条路上最耗时的那一段。开发者不再需要从头一行行读代码来理解系统AI 可以先扫一遍、画出草图你再在草图基础上做判断、修正、补充。这个过程中AI 负责把信息密度极高的代码压缩成可读的架构关系人负责校验语义和理解设计意图。两者结合才是完整的架构图生产力提升方案。从后续实践方向看有三层值得深入。第一层是把扫描逻辑做深。本文的 Python 示例只实现了最基础的 import 分析。真实项目中还有接口实现关系、Spring 注解装配、数据库表关联、消息队列消费关系等维度每一类关系都能在架构图上产生一条新的边。做深扫描逻辑是提升架构图质量的根本。第二层是把提示词工程做好。同一个项目的依赖信息用不同的提示词让大模型归纳出来的架构图质量差异非常大。你可以准备几套提示词模板分别对应“新项目架构概览”“服务依赖分析”“分层架构核查”等场景形成团队内部的最佳实践模板。第三层是思考架构图生成如何嵌入日常研发流程。最理想的状态是架构图和代码一样是一个可版本化的工程产物。代码变了图随之更新新同学入职打开图就能理解系统。要实现这个状态不能只靠一个工具还要靠团队约定、CI 流程和文档规范共同支撑。如果你手里的项目恰好是没有架构图的老系统建议先从一个小型微服务模块开始尝试用本文的思路跑通一遍流程。先不要追求一次生成完美结果而是把它当成一个辅助理解代码的工具逐步积累经验。等你在一个模块上验证了效果再慢慢扩展到更多模块。AI 不会替代架构师但它可以让每个开发者都更快地逼近“看懂系统”这个目标。这件事本身就值得一试。