最近GitHub 趋势榜上这类“AI 辅助生成架构图”的项目热度很高。核心玩法不再是你手动画方框、拉箭头而是把整个代码仓库交给 AI让它分析依赖关系、分层结构、模块边界再自动生成一张清晰可读的架构图。很多开发者在团队协作、项目文档维护、代码评审这些场景里都在尝试把这类工具落地。这篇教程会围绕“代码 AI 架构图”这条主线展开梳理 AI 生成架构图的基本原理、最小可用环境、完整实操流程以及我整理的一些避坑经验。适合有编程基础、正在维护中大型项目的开发者也适合刚接触架构设计、想快速理解陌生代码仓库的新手。1. 背景与核心概念1.1 为什么架构图总是“过期”做过一段时间项目维护的同学大概率遇到过这样的场景项目文档里的架构图还是几个大模块叠在一起但代码仓库里早就拆分成了十多个微服务中间还接入了消息队列、缓存、定时任务。手动维护架构图本质上是一个成本极高的工作因为代码每天都在变而架构图很难同步更新。架构图的价值在于它能让人快速理解系统“长什么样”代码的依赖是怎么走的模块之间通过什么方式通信。但是传统绘制方式有两个痛点绘制成本高需要人先通读代码梳理模块再手工绘图。维护成本更高代码稍微重构图就需要重新画否则文档和实现就会脱节。AI 生成架构图的思路就是把“人读代码再画图”这个流程变成“工具读代码AI 整理结构再渲染成图”。它不是简单把代码拉成一个树枝状目录而是借助大模型对代码语义的理解输出符合架构表达习惯的图。1.2 什么是从代码到架构图的自动化从技术角度看这类流程一般分为四步静态分析、语义理解、中间建模、渲染输出。静态分析扫描代码文件提取文件之间的引用关系。比如 Java 里的 importPython 里的 from ... import ...TypeScript 里的 import 语句。语义理解把仓库结构信息交给 AI让 AI 判断哪些模块是应用层哪些是基础设施层哪些是领域模型哪些只是工具函数。中间建模AI 把理解结果转成结构化的架构描述语言。常见的有 PlantUML、Structurizr DSL、Mermaid 等。渲染输出再把描述文件渲染为 PNG、SVG或者嵌入到文档站点中。换句话说AI 不止是帮你画图它先帮你“读”了一遍代码再按照架构表达规范组织信息。这就是这类工具和传统 IDE 插件比如自动生成类图的核心区别。1.3 常见应用场景这类技术比较适合以下几种场景新成员上手项目直接生成一张总览架构图比一个个打开目录高效得多。代码评审辅助评审前快速看到模块依赖判断是否存在循环依赖或者不合理的跨层调用。文档自动化把架构图生成接入 CI/CD每次代码合并后自动更新文档。存量系统梳理接手一个没有文档、模块混乱的老项目需要快速盘点系统构成。2. 环境准备与版本说明AI 生成架构图的核心依赖是代码分析能力和 AI 模型的调用链路。本节给出一个可复制的参考环境具体版本和项目实际情况有关不需要完全相同。2.1 本地环境清单本文示例以常见环境为准重点演示配置思路工具推荐版本用途Node.js18 或 20 LTS很多 CLI 工具基于 Node.js 构建Python3.10AI SDK、脚本扩展Git2.30代码仓库管理Java可选11如果分析 Java/Maven 项目需要Docker可选20隔离运行环境版本需要根据你的项目实际情况调整。如果你分析的是 Python 项目就确保 Python 环境干净如果是 Java 项目就注意 Maven/Gradle 的构建环境。2.2 AI 模型服务接入自动生成架构图一般需要接入大模型能力。当前可选方式主要有两种调用云厂商 API比如 OpenAI 兼容接口、国内大模型平台的开放 API效果稳定但需要申请 API Key。本地部署模型通过 Ollama 等工具加载本地模型数据不出内网适合有保密要求的项目。无论选择哪种方式都要注意密钥保护强烈建议通过环境变量传入不要硬编码在配置文件中。export AI_MODEL_PROVIDERopenai_compatible export AI_MODEL_API_KEY你的API密钥 export AI_MODEL_NAMEgpt-4o-mini如果你使用的是本地模型也可以像下面这样配置export AI_MODEL_PROVIDERollama export AI_MODEL_BASE_URLhttp://localhost:11434/v1 export AI_MODEL_NAMEqwen2.5-coder:14b2.3 示例项目结构为了演示完整流程我们准备一个简单的电商后端项目目录结构大致如下ecommerce-backend/ ├── src/ │ ├── main/ │ │ ├── java/com/example/ │ │ │ ├── controller/ │ │ │ ├── service/ │ │ │ ├── repository/ │ │ │ ├── model/ │ │ │ └── config/ │ │ └── resources/ ├── pom.xml └── README.md一个标准的 Spring Boot 分层项目包含 Controller、Service、Repository、Model、Config 五个核心层非常适合用来验证 AI 架构图工具的分层识别能力。3. 核心原理拆解3.1 代码分析依赖收集是基础AI 生成架构图的第一步是先把代码仓库“读”成结构化的数据。这一步常见的技术方案有两种。第一种是基于 AST 的静态分析。ASTAbstract Syntax Tree抽象语法树是代码语法结构的一种树形表示通过解析器生成。工具可以通过遍历 AST找出每一个类、函数、方法的定义位置以及它们引用了哪些外部符号。比如分析一个 Java 文件可以拿到类名OrderService依赖类OrderRepository、ProductClient注解Service公开方法createOrder(OrderDTO dto)第二种是启发式扫描。有些工具不解析完整语法而是通过正则、字符串匹配等方式提取 import、require 语句。这种方式速度快但精度相对较低。对架构图生成来说AST 方式更可靠。这个环节的质量决定了架构图的准确性。如果依赖都提取错了AI 后面的“理解”就会跟着错。3.2 AI 理解语义归纳是核心代码分析拿到的是“谁依赖谁”的原始关系但架构图不只要画依赖线还要表达模块的职责和层级。AI 在这里承担的是“架构师”角色。比如AI 看到 OrderController 依赖 OrderServiceOrderServiceImpl 依赖 OrderMapperOrderMapper 对应 Order 表它会把它们归成三层接口层controller业务层service数据层repository同理如果代码里出现了 KafkaListener、RabbitListener 这类注解AI 就会判断系统用到了消息队列如果出现了 OpenFeign 或 RestTemplateAI 会判断系统存在外部服务调用。这一步有个关键概念叫“架构视角”。AI 不是你让它画什么就画什么而是基于代码中的模式主动判断架构风格。为了得到更准确的结果通常要提供上下文提示比如“这是一个微服务系统请按分层架构输出”。3.3 中间建模DSL 是人与机器之间的桥梁AI 理解了代码结构后不能直接画图而是先生成一种中间描述。这类描述语言最常用的是 C4 Model、Structurizr DSL、PlantUML。Structurizr DSL 的示例workspace { model { user person 用户 webApp softwareSystem 电商系统 { controller container Web 层 Spring MVC 处理 HTTP 请求 service container 业务层 Spring Service 业务逻辑 repository container 数据层 Spring Data 数据库访问 database container 数据库 MySQL 存储订单和数据 } user - webApp 浏览商品 webApp.controller - webApp.service 调用业务逻辑 webApp.service - webApp.repository 访问数据 webApp.repository - database 读写 } views { container webApp { include * autolayout } } }这份 DSL 已经比较接近最终图了但它仍然是文本方便人工审查和修改。AI 生成完后人可以在这一步校对确认层级、依赖是否合理再进入渲染。3.4 渲染输出从描述到图片DSL 文件最终要渲染成图片。不同工具有不同渲染方式有的是本地命令行渲染有的是通过在线服务渲染也有的是基于 Graphviz 引擎渲染。渲染后的产物可以集成到文档中比如放在 Markdown 文件里或者发布到 GitBook、VuePress 等站点。下面用一张 ASCII 简图表示整个流程代码仓库 | | (1) 静态分析 v 依赖关系数据 | | (2) AI 语义理解 v 架构描述 DSL | | (3) DSL 渲染 v 架构图PNG/SVG/Mermaid4. 完整实战案例接下来进入实操环节。我们以“分析一个 Spring Boot 项目自动生成 C4 容器图”为目标跑通整个流程。由于当前很多 CLI 工具仍处于快速迭代阶段下面代码示例以思路演示为主你使用时需要按自己选定的工具调整命令。4.1 创建测试项目如果你已经有一个想分析的项目可以跳过这一步。如果没有先用下面命令创建一个最小的 Spring Boot 项目骨架mkdir ecommerce-backend cd ecommerce-backend mkdir -p src/main/java/com/example/{controller,service,repository,model,config} touch pom.xml touch src/main/java/com/example/EcommerceApplication.javapom.xml保持最简配置核心内容如下project modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdecommerce-backend/artifactId version1.0.0/version packagingjar/packaging parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency /dependencies /project注意Spring Boot 3.2.x 需要 JDK 17 及以上请确保本机 Java 版本满足要求。在 controller、service、repository、model 各层放一个简单类。这里以 OrderController 为例// 文件路径src/main/java/com/example/controller/OrderController.java RestController RequestMapping(/api/orders) public class OrderController { private final OrderService orderService; public OrderController(OrderService orderService) { this.orderService orderService; } PostMapping public Order createOrder(RequestBody OrderDTO orderDTO) { return orderService.createOrder(orderDTO); } }其他类类似重点是让项目里有明确的 import 依赖关系。AI 工具会根据这些 import 关系推断分层结构。4.2 安装 CLI 工具假设你选择的工具提供了 npm 包或 Python 包安装方式通常是npm install -g code-to-arch或者使用 Python 版本pip install code2arch如果工具支持本地运行不依赖远程服务那么安装完成后可以直接分析仓库。4.3 初始化配置大多数成熟的架构图工具都支持配置文件。配置文件用来控制以下内容分析目录是分析当前整个仓库还是只分析某个子目录。忽略路径一般要排除 build、node_modules、dist、.git 等目录。架构风格指定输出分层架构、微服务架构还是别的风格。AI 模型参数模型名称、温度、最大 token 等。下面是一个常见的配置文件示例以arch-gen.config.json为例{ projectRoot: ., sourceDirs: [src/main/java], ignorePaths: [build, node_modules, dist, .git, target], architectureStyle: layered, outputFormat: png, ai: { provider: openai_compatible, model: gpt-4o-mini, temperature: 0.2, maxTokens: 4096 } }字段说明sourceDirs告诉工具去哪找代码避免把配置文件、脚本全扫进来。ignorePaths一定要加。否则 Node 项目的 node_modules 会被当成源码分析结果会非常混乱。architectureStyle可选值包括 layered分层、microservices微服务、event-driven事件驱动等。temperature生成类任务的随机性参数建议调低到 0.2 左右保证输出稳定。4.4 运行生成命令配置完成后执行生成命令code2arch generate --config arch-gen.config.json如果一切正常工具会输出类似下面的日志[INFO] 开始分析代码仓库... [INFO] 已扫描 36 个 Java 文件 [INFO] 提取到 128 个类284 条依赖关系 [INFO] AI 正在理解模块职责... [INFO] 生成架构描述文件... [INFO] 渲染架构图... [INFO] 完成架构图已输出到 docs/architecture.png这里有个容易踩坑的地方AI 生成速度受网络影响较大。如果项目很大建议先对单个模块或核心目录执行分析验证效果后再全量扫描。4.5 检查中间 DSL刚才提到AI 生成的中间 DSL 最好人工审核一下。回到我们的示例假设工具生成了一个architecture.dsl文件可以打开看看workspace { model { user person 用户 system softwareSystem 电商后端 { web container Controller 层 Spring MVC 接收外部 HTTP 请求 biz container Service 层 Spring Service 处理核心业务逻辑 data container Repository 层 Spring Data JPA 封装数据库操作 db container MySQL 数据库 持久化业务数据 } user - system.web 发起请求 system.web - system.biz 调用业务接口 system.biz - system.data 访问持久层 system.data - system.db SQL 读写 } views { container system { include * autolayout } } }检查重点分层是否准确。依赖方向是否正确。是否少了关键的中间件比如 Redis、MQ。模块命名是否符合团队表达习惯。如果发现 DSL 描述和实际代码有出入可以直接修改 DSL再重新渲染。这是文本中间层的优势人工可以低成本干预。4.6 将架构图生成接入 CI实际项目中架构文档最大的问题是“一次性画完之后再也不更新”。为了避免这个问题可以把架构图生成过程接进 GitHub Actions。下面是一个工作流示例文件路径为.github/workflows/arch-docs.ymlname: Generate Architecture Docs on: push: branches: [main] paths: - src/** jobs: generate-arch: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 20 cache: npm - name: Install CLI run: npm install -g code-to-arch - name: Generate Architecture Diagram run: code2arch generate --config arch-gen.config.json env: AI_MODEL_API_KEY: ${{ secrets.AI_MODEL_API_KEY }} - name: Upload Artifact uses: actions/upload-artifactv4 with: name: architecture-diagram path: docs/architecture.png这样做的好处每次源码变更后架构图自动重新生成。团队可以在 GitHub Actions 页面直接下载最新图。避免“代码和文档分叉”的经典问题。注意这里用到了secrets.AI_MODEL_API_KEY密钥要配置在 GitHub 仓库的 Settings - Secrets and variables - Actions 中绝对不能直接写在 YAML 文件里。4.7 结果说明预期完成效果如下生成了architecture.dsl和architecture.png。图中清晰展示 Controller、Service、Repository、MySQL 的分层关系。后续代码结构变化时可以重新执行命令更新图。5. 常见问题与排查思路AI 生成架构图看起来“全自动”但实际应用中会遇到不少问题。下面汇总常见问题、原因和解决方案。问题现象常见原因解决思路生成的架构图只有目录树没有业务模块关系工具没有提取 import/依赖信息检查 sourceDirs 配置确认代码目录没有被排除AI 把 Controller 和 Service 识别成同一层代码命名不规范或者模型上下文不足在配置中补充架构提示词说明分层规则生成的图太复杂节点和连线过多扫描范围太大包含了测试代码和工具类配置 ignorePaths先聚焦核心模块网络超时 / API 报错AI 服务不稳定或 key 配置不对检查 env 变量切换备用模型或本地模型DSL 生成正确但渲染报错环境缺少 Graphviz 等渲染依赖安装对应渲染组件或使用在线渲染服务分析 Java 项目时某些依赖识别不到Maven 依赖未下载IDE 构建缓存导致 AST 不全先执行 mvn clean compile再重新分析生成的架构描述遗漏了消息队列代码中只有配置类使用 MQ 注解未实际调用人工在 DSL 中补充或调整提示词强调中间件识别中文字符在 PNG 中显示为方块渲染环境缺少中文字体安装 fonts-noto-cjk或使用 SVG 输出5.1 “AI 漏掉模块”怎么处理这是比较常见且影响较大的问题。如果 AI 生成的架构图漏掉了某些业务模块首先确认这些模块是否在扫描目录范围内。比如某个工具模块在common/目录但配置文件只写了src/main/java自然就扫不到。其次检查模块之间是否存在真实的代码依赖。如果模块 A 只是通过反射或动态配置调用模块 BAST 静态分析可能抓不到依赖AI 自然就会忽略。5.2 “架构图太乱”怎么优化架构图不是越全越好。一个包含几百个节点的架构图信息量虽然大但对阅读者来说基本没有意义。工程上的做法是分层呈现系统上下文图只画用户、外部系统、当前系统三个层级。容器图画应用、数据库、消息队列等运行单元。组件图只画某一个容器内部的组件。你可以在配置中开启“按分层导出”功能或者手动把 DSL 里的视图拆分成多个 view。5.3 “AI 生成结果不稳定”怎么办大模型的生成结果天然带有随机性。同一个仓库跑两次可能得到不同的架构描述。为了减少这种差异可以尝试把 temperature 调到 0。在提示词中固定架构风格比如“必须按照 Controller/Service/Repository 三层结构输出”。使用代码分析器输出依赖关系作为“强制约束”让 AI 在此基础上做语义归纳而不是让 AI 自己从零推断依赖。6. 最佳实践与工程建议6.1 从小项目开始验证不建议一上来就把整个几十万行代码的仓库丢给 AI。架构图生成工具对大仓库的处理可能比较慢而且 AI 上下文有限代码一多反而抓不住重点。建议先拿一个新模块或者小服务实验跑通流程后再逐步扩大到核心系统。6.2 保持代码分层清晰AI 能生成的架构图质量本质上取决于代码本身的结构质量。如果代码里所有类都堆在一个 package 下类名都是 Test1、Test2依赖关系混乱再强的模型也画不出清晰的架构图。所以这类工具不是用来“美化烂代码”的而是用来“反映代码现状”的。如果生成的图看起来不行先想想代码结构是不是也需要优化。6.3 人工审核 DSL 后再出图这是整个流程中最重要的一道防线。AI 生成的内容必须经过人工确认架构分层是否符合团队约定。依赖图中是否有异常调用链。是否存在 AI 幻觉比如根本不存在的模块。建议在 CI 流程中设置一个审批环节AI 先生成 DSL提交 PR架构师 review 通过后才渲染并发布文档。6.4 保护密钥和隐私如果你的项目需要保密要格外注意API Key 不要提交到 Git 仓库。大仓库不要直接发送给外部 AI 服务建议只发送依赖摘要不发送完整源码。有条件的团队可以部署本地模型或者选择支持私有化部署的工具。6.5 把架构图看成“活的文档”架构图不是画完就归档的交付物而是应该持续更新的“活文档”。接入 CI 之后每次代码变更只要在配置范围内架构图都会自动更新。团队可以在文档站点中引用这张图而不是让每个新人都来看同一个“陈旧”的 PPT。6.6 不要忽视性能问题代码分析工具在大型仓库上性能差异很大。如果项目规模较大建议只分析核心模块排除业务代码之外的构建产物。分模块生成架构图再组合成一张总览图。在 CI 中设置缓存避免每次全量重新分析。7. 总结与学习路线把代码交给 AI 自动生成架构图本质上是把“代码解析”和“架构表达”两边都自动化。静态分析负责精确提取依赖AI 负责语义理解和架构归纳DSL 中间层负责让人能低成本审查和修改最后再渲染成图。这样一个链路能够有效缓解架构文档长期过期的问题。这篇文章涵盖了从概念到落地的完整过程。你可以先从一个小项目开始尝试跑通后加入团队文档流程。需要重点掌握的关键点有三个第一个是配置文件里 sourceDirs 和 ignorePaths 很重要直接决定工具能不能拿到有效代码。第二个是 AI 生成的 DSL 一定要有人工审核环节不要无脑发布。第三个是可以把生成流程接入 CI让架构图随代码一起演进。如果在这个基础上继续深入学习可以关注 C4 Model、领域驱动设计DDD、事件风暴这些架构设计方法它们会帮助你更好地理解代码结构也能让你在审核 AI 生成的架构描述时更有判断力。动手跑一遍比看十篇教程都有效果。找一个小项目配好环境用本文的流程生成一张架构图然后对比一下 AI 的理解和自己的设计是否一致。如果不一致试着调整提示词或补充架构风格很快就能掌握这套工具的用法。
AI辅助生成架构图：从原理到实战的完整指南
最近GitHub 趋势榜上这类“AI 辅助生成架构图”的项目热度很高。核心玩法不再是你手动画方框、拉箭头而是把整个代码仓库交给 AI让它分析依赖关系、分层结构、模块边界再自动生成一张清晰可读的架构图。很多开发者在团队协作、项目文档维护、代码评审这些场景里都在尝试把这类工具落地。这篇教程会围绕“代码 AI 架构图”这条主线展开梳理 AI 生成架构图的基本原理、最小可用环境、完整实操流程以及我整理的一些避坑经验。适合有编程基础、正在维护中大型项目的开发者也适合刚接触架构设计、想快速理解陌生代码仓库的新手。1. 背景与核心概念1.1 为什么架构图总是“过期”做过一段时间项目维护的同学大概率遇到过这样的场景项目文档里的架构图还是几个大模块叠在一起但代码仓库里早就拆分成了十多个微服务中间还接入了消息队列、缓存、定时任务。手动维护架构图本质上是一个成本极高的工作因为代码每天都在变而架构图很难同步更新。架构图的价值在于它能让人快速理解系统“长什么样”代码的依赖是怎么走的模块之间通过什么方式通信。但是传统绘制方式有两个痛点绘制成本高需要人先通读代码梳理模块再手工绘图。维护成本更高代码稍微重构图就需要重新画否则文档和实现就会脱节。AI 生成架构图的思路就是把“人读代码再画图”这个流程变成“工具读代码AI 整理结构再渲染成图”。它不是简单把代码拉成一个树枝状目录而是借助大模型对代码语义的理解输出符合架构表达习惯的图。1.2 什么是从代码到架构图的自动化从技术角度看这类流程一般分为四步静态分析、语义理解、中间建模、渲染输出。静态分析扫描代码文件提取文件之间的引用关系。比如 Java 里的 importPython 里的 from ... import ...TypeScript 里的 import 语句。语义理解把仓库结构信息交给 AI让 AI 判断哪些模块是应用层哪些是基础设施层哪些是领域模型哪些只是工具函数。中间建模AI 把理解结果转成结构化的架构描述语言。常见的有 PlantUML、Structurizr DSL、Mermaid 等。渲染输出再把描述文件渲染为 PNG、SVG或者嵌入到文档站点中。换句话说AI 不止是帮你画图它先帮你“读”了一遍代码再按照架构表达规范组织信息。这就是这类工具和传统 IDE 插件比如自动生成类图的核心区别。1.3 常见应用场景这类技术比较适合以下几种场景新成员上手项目直接生成一张总览架构图比一个个打开目录高效得多。代码评审辅助评审前快速看到模块依赖判断是否存在循环依赖或者不合理的跨层调用。文档自动化把架构图生成接入 CI/CD每次代码合并后自动更新文档。存量系统梳理接手一个没有文档、模块混乱的老项目需要快速盘点系统构成。2. 环境准备与版本说明AI 生成架构图的核心依赖是代码分析能力和 AI 模型的调用链路。本节给出一个可复制的参考环境具体版本和项目实际情况有关不需要完全相同。2.1 本地环境清单本文示例以常见环境为准重点演示配置思路工具推荐版本用途Node.js18 或 20 LTS很多 CLI 工具基于 Node.js 构建Python3.10AI SDK、脚本扩展Git2.30代码仓库管理Java可选11如果分析 Java/Maven 项目需要Docker可选20隔离运行环境版本需要根据你的项目实际情况调整。如果你分析的是 Python 项目就确保 Python 环境干净如果是 Java 项目就注意 Maven/Gradle 的构建环境。2.2 AI 模型服务接入自动生成架构图一般需要接入大模型能力。当前可选方式主要有两种调用云厂商 API比如 OpenAI 兼容接口、国内大模型平台的开放 API效果稳定但需要申请 API Key。本地部署模型通过 Ollama 等工具加载本地模型数据不出内网适合有保密要求的项目。无论选择哪种方式都要注意密钥保护强烈建议通过环境变量传入不要硬编码在配置文件中。export AI_MODEL_PROVIDERopenai_compatible export AI_MODEL_API_KEY你的API密钥 export AI_MODEL_NAMEgpt-4o-mini如果你使用的是本地模型也可以像下面这样配置export AI_MODEL_PROVIDERollama export AI_MODEL_BASE_URLhttp://localhost:11434/v1 export AI_MODEL_NAMEqwen2.5-coder:14b2.3 示例项目结构为了演示完整流程我们准备一个简单的电商后端项目目录结构大致如下ecommerce-backend/ ├── src/ │ ├── main/ │ │ ├── java/com/example/ │ │ │ ├── controller/ │ │ │ ├── service/ │ │ │ ├── repository/ │ │ │ ├── model/ │ │ │ └── config/ │ │ └── resources/ ├── pom.xml └── README.md一个标准的 Spring Boot 分层项目包含 Controller、Service、Repository、Model、Config 五个核心层非常适合用来验证 AI 架构图工具的分层识别能力。3. 核心原理拆解3.1 代码分析依赖收集是基础AI 生成架构图的第一步是先把代码仓库“读”成结构化的数据。这一步常见的技术方案有两种。第一种是基于 AST 的静态分析。ASTAbstract Syntax Tree抽象语法树是代码语法结构的一种树形表示通过解析器生成。工具可以通过遍历 AST找出每一个类、函数、方法的定义位置以及它们引用了哪些外部符号。比如分析一个 Java 文件可以拿到类名OrderService依赖类OrderRepository、ProductClient注解Service公开方法createOrder(OrderDTO dto)第二种是启发式扫描。有些工具不解析完整语法而是通过正则、字符串匹配等方式提取 import、require 语句。这种方式速度快但精度相对较低。对架构图生成来说AST 方式更可靠。这个环节的质量决定了架构图的准确性。如果依赖都提取错了AI 后面的“理解”就会跟着错。3.2 AI 理解语义归纳是核心代码分析拿到的是“谁依赖谁”的原始关系但架构图不只要画依赖线还要表达模块的职责和层级。AI 在这里承担的是“架构师”角色。比如AI 看到 OrderController 依赖 OrderServiceOrderServiceImpl 依赖 OrderMapperOrderMapper 对应 Order 表它会把它们归成三层接口层controller业务层service数据层repository同理如果代码里出现了 KafkaListener、RabbitListener 这类注解AI 就会判断系统用到了消息队列如果出现了 OpenFeign 或 RestTemplateAI 会判断系统存在外部服务调用。这一步有个关键概念叫“架构视角”。AI 不是你让它画什么就画什么而是基于代码中的模式主动判断架构风格。为了得到更准确的结果通常要提供上下文提示比如“这是一个微服务系统请按分层架构输出”。3.3 中间建模DSL 是人与机器之间的桥梁AI 理解了代码结构后不能直接画图而是先生成一种中间描述。这类描述语言最常用的是 C4 Model、Structurizr DSL、PlantUML。Structurizr DSL 的示例workspace { model { user person 用户 webApp softwareSystem 电商系统 { controller container Web 层 Spring MVC 处理 HTTP 请求 service container 业务层 Spring Service 业务逻辑 repository container 数据层 Spring Data 数据库访问 database container 数据库 MySQL 存储订单和数据 } user - webApp 浏览商品 webApp.controller - webApp.service 调用业务逻辑 webApp.service - webApp.repository 访问数据 webApp.repository - database 读写 } views { container webApp { include * autolayout } } }这份 DSL 已经比较接近最终图了但它仍然是文本方便人工审查和修改。AI 生成完后人可以在这一步校对确认层级、依赖是否合理再进入渲染。3.4 渲染输出从描述到图片DSL 文件最终要渲染成图片。不同工具有不同渲染方式有的是本地命令行渲染有的是通过在线服务渲染也有的是基于 Graphviz 引擎渲染。渲染后的产物可以集成到文档中比如放在 Markdown 文件里或者发布到 GitBook、VuePress 等站点。下面用一张 ASCII 简图表示整个流程代码仓库 | | (1) 静态分析 v 依赖关系数据 | | (2) AI 语义理解 v 架构描述 DSL | | (3) DSL 渲染 v 架构图PNG/SVG/Mermaid4. 完整实战案例接下来进入实操环节。我们以“分析一个 Spring Boot 项目自动生成 C4 容器图”为目标跑通整个流程。由于当前很多 CLI 工具仍处于快速迭代阶段下面代码示例以思路演示为主你使用时需要按自己选定的工具调整命令。4.1 创建测试项目如果你已经有一个想分析的项目可以跳过这一步。如果没有先用下面命令创建一个最小的 Spring Boot 项目骨架mkdir ecommerce-backend cd ecommerce-backend mkdir -p src/main/java/com/example/{controller,service,repository,model,config} touch pom.xml touch src/main/java/com/example/EcommerceApplication.javapom.xml保持最简配置核心内容如下project modelVersion4.0.0/modelVersion groupIdcom.example/groupId artifactIdecommerce-backend/artifactId version1.0.0/version packagingjar/packaging parent groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-parent/artifactId version3.2.5/version relativePath/ /parent dependencies dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-web/artifactId /dependency dependency groupIdorg.springframework.boot/groupId artifactIdspring-boot-starter-data-jpa/artifactId /dependency dependency groupIdcom.mysql/groupId artifactIdmysql-connector-j/artifactId scoperuntime/scope /dependency /dependencies /project注意Spring Boot 3.2.x 需要 JDK 17 及以上请确保本机 Java 版本满足要求。在 controller、service、repository、model 各层放一个简单类。这里以 OrderController 为例// 文件路径src/main/java/com/example/controller/OrderController.java RestController RequestMapping(/api/orders) public class OrderController { private final OrderService orderService; public OrderController(OrderService orderService) { this.orderService orderService; } PostMapping public Order createOrder(RequestBody OrderDTO orderDTO) { return orderService.createOrder(orderDTO); } }其他类类似重点是让项目里有明确的 import 依赖关系。AI 工具会根据这些 import 关系推断分层结构。4.2 安装 CLI 工具假设你选择的工具提供了 npm 包或 Python 包安装方式通常是npm install -g code-to-arch或者使用 Python 版本pip install code2arch如果工具支持本地运行不依赖远程服务那么安装完成后可以直接分析仓库。4.3 初始化配置大多数成熟的架构图工具都支持配置文件。配置文件用来控制以下内容分析目录是分析当前整个仓库还是只分析某个子目录。忽略路径一般要排除 build、node_modules、dist、.git 等目录。架构风格指定输出分层架构、微服务架构还是别的风格。AI 模型参数模型名称、温度、最大 token 等。下面是一个常见的配置文件示例以arch-gen.config.json为例{ projectRoot: ., sourceDirs: [src/main/java], ignorePaths: [build, node_modules, dist, .git, target], architectureStyle: layered, outputFormat: png, ai: { provider: openai_compatible, model: gpt-4o-mini, temperature: 0.2, maxTokens: 4096 } }字段说明sourceDirs告诉工具去哪找代码避免把配置文件、脚本全扫进来。ignorePaths一定要加。否则 Node 项目的 node_modules 会被当成源码分析结果会非常混乱。architectureStyle可选值包括 layered分层、microservices微服务、event-driven事件驱动等。temperature生成类任务的随机性参数建议调低到 0.2 左右保证输出稳定。4.4 运行生成命令配置完成后执行生成命令code2arch generate --config arch-gen.config.json如果一切正常工具会输出类似下面的日志[INFO] 开始分析代码仓库... [INFO] 已扫描 36 个 Java 文件 [INFO] 提取到 128 个类284 条依赖关系 [INFO] AI 正在理解模块职责... [INFO] 生成架构描述文件... [INFO] 渲染架构图... [INFO] 完成架构图已输出到 docs/architecture.png这里有个容易踩坑的地方AI 生成速度受网络影响较大。如果项目很大建议先对单个模块或核心目录执行分析验证效果后再全量扫描。4.5 检查中间 DSL刚才提到AI 生成的中间 DSL 最好人工审核一下。回到我们的示例假设工具生成了一个architecture.dsl文件可以打开看看workspace { model { user person 用户 system softwareSystem 电商后端 { web container Controller 层 Spring MVC 接收外部 HTTP 请求 biz container Service 层 Spring Service 处理核心业务逻辑 data container Repository 层 Spring Data JPA 封装数据库操作 db container MySQL 数据库 持久化业务数据 } user - system.web 发起请求 system.web - system.biz 调用业务接口 system.biz - system.data 访问持久层 system.data - system.db SQL 读写 } views { container system { include * autolayout } } }检查重点分层是否准确。依赖方向是否正确。是否少了关键的中间件比如 Redis、MQ。模块命名是否符合团队表达习惯。如果发现 DSL 描述和实际代码有出入可以直接修改 DSL再重新渲染。这是文本中间层的优势人工可以低成本干预。4.6 将架构图生成接入 CI实际项目中架构文档最大的问题是“一次性画完之后再也不更新”。为了避免这个问题可以把架构图生成过程接进 GitHub Actions。下面是一个工作流示例文件路径为.github/workflows/arch-docs.ymlname: Generate Architecture Docs on: push: branches: [main] paths: - src/** jobs: generate-arch: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkoutv4 - name: Setup Node.js uses: actions/setup-nodev4 with: node-version: 20 cache: npm - name: Install CLI run: npm install -g code-to-arch - name: Generate Architecture Diagram run: code2arch generate --config arch-gen.config.json env: AI_MODEL_API_KEY: ${{ secrets.AI_MODEL_API_KEY }} - name: Upload Artifact uses: actions/upload-artifactv4 with: name: architecture-diagram path: docs/architecture.png这样做的好处每次源码变更后架构图自动重新生成。团队可以在 GitHub Actions 页面直接下载最新图。避免“代码和文档分叉”的经典问题。注意这里用到了secrets.AI_MODEL_API_KEY密钥要配置在 GitHub 仓库的 Settings - Secrets and variables - Actions 中绝对不能直接写在 YAML 文件里。4.7 结果说明预期完成效果如下生成了architecture.dsl和architecture.png。图中清晰展示 Controller、Service、Repository、MySQL 的分层关系。后续代码结构变化时可以重新执行命令更新图。5. 常见问题与排查思路AI 生成架构图看起来“全自动”但实际应用中会遇到不少问题。下面汇总常见问题、原因和解决方案。问题现象常见原因解决思路生成的架构图只有目录树没有业务模块关系工具没有提取 import/依赖信息检查 sourceDirs 配置确认代码目录没有被排除AI 把 Controller 和 Service 识别成同一层代码命名不规范或者模型上下文不足在配置中补充架构提示词说明分层规则生成的图太复杂节点和连线过多扫描范围太大包含了测试代码和工具类配置 ignorePaths先聚焦核心模块网络超时 / API 报错AI 服务不稳定或 key 配置不对检查 env 变量切换备用模型或本地模型DSL 生成正确但渲染报错环境缺少 Graphviz 等渲染依赖安装对应渲染组件或使用在线渲染服务分析 Java 项目时某些依赖识别不到Maven 依赖未下载IDE 构建缓存导致 AST 不全先执行 mvn clean compile再重新分析生成的架构描述遗漏了消息队列代码中只有配置类使用 MQ 注解未实际调用人工在 DSL 中补充或调整提示词强调中间件识别中文字符在 PNG 中显示为方块渲染环境缺少中文字体安装 fonts-noto-cjk或使用 SVG 输出5.1 “AI 漏掉模块”怎么处理这是比较常见且影响较大的问题。如果 AI 生成的架构图漏掉了某些业务模块首先确认这些模块是否在扫描目录范围内。比如某个工具模块在common/目录但配置文件只写了src/main/java自然就扫不到。其次检查模块之间是否存在真实的代码依赖。如果模块 A 只是通过反射或动态配置调用模块 BAST 静态分析可能抓不到依赖AI 自然就会忽略。5.2 “架构图太乱”怎么优化架构图不是越全越好。一个包含几百个节点的架构图信息量虽然大但对阅读者来说基本没有意义。工程上的做法是分层呈现系统上下文图只画用户、外部系统、当前系统三个层级。容器图画应用、数据库、消息队列等运行单元。组件图只画某一个容器内部的组件。你可以在配置中开启“按分层导出”功能或者手动把 DSL 里的视图拆分成多个 view。5.3 “AI 生成结果不稳定”怎么办大模型的生成结果天然带有随机性。同一个仓库跑两次可能得到不同的架构描述。为了减少这种差异可以尝试把 temperature 调到 0。在提示词中固定架构风格比如“必须按照 Controller/Service/Repository 三层结构输出”。使用代码分析器输出依赖关系作为“强制约束”让 AI 在此基础上做语义归纳而不是让 AI 自己从零推断依赖。6. 最佳实践与工程建议6.1 从小项目开始验证不建议一上来就把整个几十万行代码的仓库丢给 AI。架构图生成工具对大仓库的处理可能比较慢而且 AI 上下文有限代码一多反而抓不住重点。建议先拿一个新模块或者小服务实验跑通流程后再逐步扩大到核心系统。6.2 保持代码分层清晰AI 能生成的架构图质量本质上取决于代码本身的结构质量。如果代码里所有类都堆在一个 package 下类名都是 Test1、Test2依赖关系混乱再强的模型也画不出清晰的架构图。所以这类工具不是用来“美化烂代码”的而是用来“反映代码现状”的。如果生成的图看起来不行先想想代码结构是不是也需要优化。6.3 人工审核 DSL 后再出图这是整个流程中最重要的一道防线。AI 生成的内容必须经过人工确认架构分层是否符合团队约定。依赖图中是否有异常调用链。是否存在 AI 幻觉比如根本不存在的模块。建议在 CI 流程中设置一个审批环节AI 先生成 DSL提交 PR架构师 review 通过后才渲染并发布文档。6.4 保护密钥和隐私如果你的项目需要保密要格外注意API Key 不要提交到 Git 仓库。大仓库不要直接发送给外部 AI 服务建议只发送依赖摘要不发送完整源码。有条件的团队可以部署本地模型或者选择支持私有化部署的工具。6.5 把架构图看成“活的文档”架构图不是画完就归档的交付物而是应该持续更新的“活文档”。接入 CI 之后每次代码变更只要在配置范围内架构图都会自动更新。团队可以在文档站点中引用这张图而不是让每个新人都来看同一个“陈旧”的 PPT。6.6 不要忽视性能问题代码分析工具在大型仓库上性能差异很大。如果项目规模较大建议只分析核心模块排除业务代码之外的构建产物。分模块生成架构图再组合成一张总览图。在 CI 中设置缓存避免每次全量重新分析。7. 总结与学习路线把代码交给 AI 自动生成架构图本质上是把“代码解析”和“架构表达”两边都自动化。静态分析负责精确提取依赖AI 负责语义理解和架构归纳DSL 中间层负责让人能低成本审查和修改最后再渲染成图。这样一个链路能够有效缓解架构文档长期过期的问题。这篇文章涵盖了从概念到落地的完整过程。你可以先从一个小项目开始尝试跑通后加入团队文档流程。需要重点掌握的关键点有三个第一个是配置文件里 sourceDirs 和 ignorePaths 很重要直接决定工具能不能拿到有效代码。第二个是 AI 生成的 DSL 一定要有人工审核环节不要无脑发布。第三个是可以把生成流程接入 CI让架构图随代码一起演进。如果在这个基础上继续深入学习可以关注 C4 Model、领域驱动设计DDD、事件风暴这些架构设计方法它们会帮助你更好地理解代码结构也能让你在审核 AI 生成的架构描述时更有判断力。动手跑一遍比看十篇教程都有效果。找一个小项目配好环境用本文的流程生成一张架构图然后对比一下 AI 的理解和自己的设计是否一致。如果不一致试着调整提示词或补充架构风格很快就能掌握这套工具的用法。
