做系统重构或技术方案评审时画架构图几乎是每项工作的第一步。但架构图在工作中经常遇到一个尴尬问题它画完之后很容易变成一张“一次性图表”。需求一变代码一改图就过期业务一扩展模块之间的关系就被覆盖。团队虽然规定了“架构文档必须维护”最后靠人工比对代码与架构图既费时间又容易漏。如果架构图能直接从代码仓库里“长”出来AI 负责梳理依赖、生成结构视图同时保留从业务描述到代码实现之间的追踪链路这种“可验证、能追路径”的方案显然更贴近研发日常。Archify 正是这个方向上一个很受关注的开源项目社区热度很高GitHub 仓库已经积累了 3.5 万 Star。本文将围绕 Archify 展开介绍它的核心概念、安装方式、基础用法并给出一个从微服务工程生成架构图的完整示例。同时会讨论架构描述文件的写法、怎样与 AI 协作迭代以及实际工程中的常见坑和最佳实践。这篇文章适合以下读者想用 AI 自动生成架构图、降低手工绘图成本的后端开发者和架构师正在建设技术文档体系希望架构图能跟上代码变化的团队对“可验证架构图”和“AI 辅助设计工具”方向感兴趣想了解这类工具思路的技术人员。1. 背景为什么需要 AI 架构图工具1.1 传统架构图维护的真实痛点过去画架构图主流方式是人手画先用 Visio、draw.io、ProcessOn 等工具拖拽方块和箭头。把服务名、数据库名、调用关系挨个画上去。画完导出图片粘贴到文档或 Wiki。后续代码变化后再手工打开原图修改。这套流程在项目早期还撑得住。一旦服务数量超过 10 个或者团队并行迭代速度很快就会遇到几个明显问题信息滞后架构图通常落后于代码实现有些图甚至从上线那天起就没有更新过。验证困难读者不知道图上画的依赖关系是真是假也不知道这张图对应代码库的哪个版本。颗粒度不一致有人画到服务级有人画到方法级团队内没有统一规范。沟通成本高评审时经常围绕“这个箭头到底代表 HTTP 调用还是消息队列”这类问题反复解释。这些问题集中起来本质上是一件事架构图没有与代码建立可验证的绑定关系。图只是图代码只是代码二者靠人去记忆和同步。1.2 Archify 是什么Archify 是一个利用 AI 辅助生成、校验和追踪软件架构图的开源工具。它可以看作“架构图领域的自动化助手”主要解决“架构图从哪来、怎么更新、如何保证与代码一致”的问题。它的工作方式并不复杂以项目源码、架构描述文件、对话指令为输入让 AI 分析服务边界、内外依赖关系和分层结构生成系统架构图、微服务架构图、业务架构图或技术架构图同时提供校验命令将生成结果与真实代码结构做比对找出不一致项。关于 Archify 的定义可以从三个角度理解面向开发者它是一个命令行工具和 IDE 插件安装到本地后即可分析项目。面向架构师它提供了一种结构化的架构描述文件方便团队维护架构资产。面向 AI 应用它把“画图”这件事封装成了可交互、可迭代的 AI Agent 工作流开发者可以用自然语言让 AI 调整架构图。需要区分的是它与传统“自动根据代码生成 UML 图”的工具不同。传统工具大多只是静态扫描代码结构生成类图或调用关系图而 Archify 这类 AI 工具会结合源码内容、配置文件、目录结构甚至开发者的自然语言描述生成语义更完整的架构图并保留追踪信息。1.3 核心特性可验证与可追踪项目标题里有两个关键词一个是“可验证”一个是“能追路径”这两个能力决定了 Archify 与传统绘图工具的本质差异。1.3.1 可验证“可验证”的意思是生成的架构图并不是一次性图片而是可以被工具反复校验的模型。工具会检查图中声明的服务或组件在代码库里是否真实存在图中声明的依赖关系在代码里是否有实际体现图中声明的接口或端点是否能在项目配置中找到对应实现。如果代码改动了而架构描述文件没有更新执行校验命令时就会得到差异报告。这样架构图就从“静态图片资产”变成了“可执行检查的工程资产”。1.3.2 能追路径“能追路径”是指架构图里的每个组件都能追溯到对应的源码目录、配置文件或者接口定义。比如图上画了一个user-service你可以顺着追踪链路直接定位到该服务的代码根目录、入口类、相关 API 列表和依赖数据库配置。这条追踪链路对团队协作很有价值。新同学接手项目时不用再到处问“这个服务代码在哪”代码评审时也可以从架构图上某一节点直接跳转到源码加快理解速度。1.3.3 多类型架构图支持从社区讨论和关键词热度可以看出大家常画的架构图类型并不只有一种。Archify 可以覆盖常见几类架构图类型说明典型使用场景系统架构图展现系统整体分层、服务模块、外部依赖项目文档、汇报材料微服务架构图展现服务注册、服务调用、网关、数据库微服务治理、容量规划业务架构图以业务域划分服务不强调协议细节产品评审、业务梳理技术架构图展现中间件、框架、协议、部署形态技术选型、运维排障组织架构图展现团队、职责、系统归属关系团队协作、故障响应在下面实战中我们主要围绕微服务架构图展开演示思路可以平移到其他类型。2. 环境准备与安装2.1 运行环境Archify 本质上是一个 Node.js 技术栈的开源工具大部分能力通过 CLI 提供。因此在安装之前先确认基础环境Node.js 16 或更高版本具体版本请以项目 README 的要求为准npm 或 yarn 包管理器Git用于克隆示例项目和版本对比开发项目本身建议是 Java、Go、Python、Node.js 等常见后端工程。如果只是在 IDE 里使用也可以不单独安装 CLI直接安装插件后通过界面操作。本文示例以常见环境为例重点演示配置思路。不同版本对 Node 版本要求可能会有变化如果安装过程中提示引擎不兼容按提示调整 Node 版本即可。2.2 安装 Archify CLIArchify 的安装方式以官方发布页为准。以 npm 安装为例典型命令如下# 全局安装 Archify CLI包名和版本以官方发布信息为准 npm install -g archify/cli # 查看安装后的版本号 archify --version安装完成后先查看帮助信息确认当前版本支持哪些子命令archify --help一般会看到init、generate、validate、trace之类的子命令。如果你下载的版本命令名有差异不用着急以archify --help输出为准即可。如果网络环境不适合 npm 全局安装也可以选择下载官方发布的二进制压缩包解压后把可执行文件加入系统 PATH。具体操作路径在项目 Realease 页面都会有说明。2.3 IDE 插件与 Trae 集成Archify 的优势之一是能和现代 IDE 结合让分析结果直接出现在编辑环境里。2.3.1 在 VS Code 中安装打开 VS Code 扩展面板搜索 Archify 相关扩展点击 Install 安装。安装后可以在侧边栏看到架构分析面板。打开一个项目根目录后扩展会自动识别项目类型并提供“分析并生成架构图”按钮。2.3.2 在 Trae 中使用Trae 是近年流行的 AI IDE核心特点是编辑器内直接集成对话式 AI 编程助手。想要在 Trae 里使用 Archify可以在插件市场搜索安装 Archify 插件。安装完成后使用方式比较自然在 Trae 中打开目标项目根目录。打开 AI 对话窗口在输入框内输入类似指令 “分析当前项目的模块结构生成一张系统架构图并在架构图上标注出服务之间的依赖关系。”Trae 中的 AI 助手会调用 Archify 能力对项目进行扫描和分析。分析完成后可以在编辑器内预览架构图也可以生成架构描述文件到项目目录。如果不满意可以继续对话例如 “把用户服务和订单服务之间的调用关系改成异步消息队列方式重新生成。”这种交互方式对日常开发更友好不需要离开 IDE也不需要记忆繁琐的命令行参数直接用写注释的方式就能驱动架构图生成。3. Archify 核心概念与基础用法在进入实战之前先了解 Archify 的几个基础概念否则直接执行命令时容易对结果产生困惑。3.1 架构描述文件架构描述文件是 Archify 的核心输入通常是一个 YAML 或 JSON 文件里面声明了系统的名称、组件、分层、依赖关系等元数据。这个文件可以理解为“架构图的源码”后续所有校验和更新都以它为基础。为了便于理解下面给出一个 YAML 形式的示例。不同版本的 Archify 对字段命名存在细微差别使用时应以当前版本文档为准。重点观察依赖关系是如何声明的。# 文件路径archify/system.yml version: 1.0 system: name: demo-shop description: 电商示例系统 layers: - name: gateway - name: application - name: infrastructure components: api-gateway: type: gateway layer: gateway endpoints: - path: /api/** user-service: type: service layer: application dependsOn: - user-db - order-service order-service: type: service layer: application dependsOn: - order-db - product-service product-service: type: service layer: application dependsOn: - product-db user-db: type: database layer: infrastructure order-db: type: database layer: infrastructure product-db: type: database layer: infrastructure这个文件最大的好处是可读性很强。即使不懂工具团队里的新人也基本能看懂系统里有哪几个组件、谁依赖谁。相比一张图片文本文件更容易做代码评审和版本管理。3.2 从代码导入生成架构视图如果你不想从零手写描述文件也可以先让 Archify 扫描代码自动生成初版架构描述。典型命令如下# 进入项目根目录后执行 archify init # 扫描并生成架构描述文件 archify scan --source . --output archify/system.ymlscan会读取项目中的配置文件、路由声明、服务目录和依赖清单尝试识别服务边界。对于 Spring Cloud 项目它能识别服务名、注册中心和 Feign 调用对于 Go 微服务项目它能识别 HTTP 路由和 RPC 客户端调用。初次生成的描述文件可能不够完善但可以作为一个起点随后由开发者在文本编辑器里补充。3.3 使用 AI 对话生成架构图在支持对话的 IDE 中开发者不需要直接编写上面的 YAML。AI 会根据自然语言指令生成并维护描述文件。下面是一个典型的对话示例开发者为 demo-shop 项目生成微服务架构图突出 user-service、order-service、product-service 之间的依赖关系并把数据库节点放到底层基础设施层。 AI已生成架构描述文件 archify/system.yml并通过代码扫描比对了服务名。当前识别结果包含 api-gateway、user-service、order-service、product-service 三个业务服务和三个数据库节点。你可以运行验证命令确认一致性。这种多轮对话的方式让“画架构图”从一次性的绘图操作变成了可持续的工程协作形式。AI 负责写文件开发者负责审查和确认。4. 完整实战从 Spring Cloud 微服务项目生成可验证架构图下面用一个模拟的电商微服务项目demo-shop演示完整流程。该工程包含网关、用户服务、订单服务、商品服务和对应的数据库模块。你可以不照搬业务代码重点看流程和工具配合方式。4.1 准备示例项目结构demo-shop/ ├── api-gateway/ │ └── src/main/java/com/demo/gateway/GatewayApplication.java ├── user-service/ │ ├── src/main/java/com/demo/user/UserApplication.java │ └── src/main/resources/application.yml ├── order-service/ │ ├── src/main/java/com/demo/order/OrderApplication.java │ └── src/main/resources/application.yml ├── product-service/ │ ├── src/main/java/com/demo/product/ProductApplication.java │ └── src/main/resources/application.yml ├── docker-compose.yml └── archify/ └── system.yml在这个结构中业务代码与架构描述文件分开存放archify/system.yml专门保存架构模型。这样命名清晰也方便 CI 中对架构文件单独执行校验。4.2 编写架构描述文件架构描述文件是整条链路的核心下面给出一份稍微完整的配置。它已经包含description、组件类型、依赖关系、接口映射等信息。# 文件路径archify/system.yml version: 1.0 system: name: demo-shop description: 电商示例系统包含网关、用户、订单、商品四个核心服务 layers: - name: gateway description: 流量入口层 - name: application description: 业务应用层 - name: infrastructure description: 基础设施层 components: api-gateway: type: gateway layer: gateway description: 统一流量入口负责路由和鉴权 endpoints: - path: /api/user/** target: user-service - path: /api/order/** target: order-service - path: /api/product/** target: product-service user-service: type: service layer: application description: 用户服务承载用户信息查询与账号能力 dependsOn: - user-db - order-service sourcePaths: - user-service/src/main/java order-service: type: service layer: application description: 订单服务承载订单创建与查询 dependsOn: - order-db - product-service sourcePaths: - order-service/src/main/java product-service: type: service layer: application description: 商品服务承载商品信息管理 dependsOn: - product-db sourcePaths: - product-service/src/main/java user-db: type: database layer: infrastructure description: 用户库 order-db: type: database layer: infrastructure description: 订单库 product-db: type: database layer: infrastructure description: 商品库这个描述文件定义了三层结构网关层、业务应用层、基础设施层。组件之间的依赖通过dependsOn字段表达源码位置通过sourcePaths绑定。这样后续执行校验和追踪时工具就能把逻辑组件与真实代码对应起来。4.3 生成架构图描述文件准备好之后可以执行生成命令。输出格式通常支持 SVG、PNG、HTML 等具体以工具支持的格式为准。# 生成 SVG 格式架构图 archify generate --input archify/system.yml --output docs/demo-shop.svg # 生成 HTML 格式架构图方便在浏览器中查看 archify generate --input archify/system.yml --output docs/demo-shop.html执行成功后docs/demo-shop.svg就是一张包含服务节点、数据库节点和依赖箭头的架构图。生成的 SVG 可以直接嵌入技术文档也可以放到网页中展示。4.4 校验架构图与代码一致性架构图生成后关键一步是验证它是否和真实代码一致。假设此时有人修改了user-service新增了一个对product-service的 Feign 调用但架构描述文件没有更新。执行校验命令会得到差异提示# 校验架构描述文件与代码仓库的一致性 archify validate --input archify/system.yml --source .预期结果可能是Info : archify/system.yml loaded Error : component [user-service] has undeclared dependency on [product-service] Hint : add product-service to user-service.dependsOn in archify/system.yml这条提示很有价值它把“代码里已经产生的新依赖”和“架构文档里缺失的依赖”之间的差距明确暴露出来。修复方式也很简单在user-service的dependsOn中增加product-service再重新执行校验即可。在真实项目中建议把这条校验命令配置到 CI 流水线里让架构合规性像单元测试一样自动运行。4.5 追踪组件到源码路径架构图如果只能看不能用价值有限。利用trace子命令我们可以从某个架构组件追踪到具体源码位置# 查看 user-service 对应的源码路径和依赖 archify trace --component user-service --source .预期输出可以理解为一张映射表架构组件源码路径类型下游依赖user-serviceuser-service/src/main/javaserviceuser-db, order-service, product-serviceuser-db无外部数据库database-开发者在走读代码时可以根据这张表快速定位到对应模块不需要再通过目录树一层一层猜测。4.6 结果说明经过以上步骤我们从零完成了一次“架构图生成 校验 追踪”的闭环编写结构化架构描述文件。生成 SVG/HTML 架构图。执行校验发现并修复架构漂移问题。通过 trace 命令完成组件到源码的定位。这个流程最关键的一点是架构图不再是一张脆弱的图片而是一个可以在 CI 中持续检查的工程产物。代码变化后架构图是否过期不用靠人肉记忆交给校验命令即可。5. 常见问题与排查思路5.1 扫描结果不完整缺失部分依赖有些项目依赖是通过反射、SPI 机制或动态代理注入的静态扫描工具很难完整识别所有调用关系。建议先用 AI 自动扫描生成初稿再人工核对关键链路。对于无法识别的动态依赖在架构描述文件里显式声明。如果缺失的是跨服务调用优先检查是否有 OpenAPI 文档或 Feign 接口提前配置扫描规则。5.2 validate 提示大量不一致这种情况通常出现在架构描述文件长期未更新、代码已经大范围重构的项目中。不建议一次性把所有服务声明都删掉重来那样会让架构图失去历史参考价值。正确做法是先执行archify trace导出当前代码的依赖矩阵逐层核对差异。优先修复核心服务的依赖关系再处理边缘模块。如果重构范围太大可以分阶段调整架构描述文件。5.3 中文乱码或字体异常生成的 SVG 在浏览器、文档中显示正常但导出 PNG 时出现中文乱码或方框符号通常是因为运行环境缺少中文字体。安装系统字体依赖即可不同系统的处理方式不同# Ubuntu/Debian 系统安装基础中文字体 sudo apt install fonts-noto-cjk如果是 macOS一般自带苹方和宋体基本不需要额外处理。5.4 大型项目生成超时一个仓库里包含几十个服务、大量历史代码时扫描耗时可能较长。建议在生成命令中通过参数控制扫描范围比如只扫描services/目录下的子模块或者排除test/、build/、node_modules/等目录。如果工具提供配置文件可以在其中设置ignorePaths。5.5 常见问题速查表问题现象常见原因解决思路生成图缺失部分依赖动态代理/SPI/反射导致扫描不完整在描述文件中手动声明依赖关系validate 提示不一致代码与架构描述文件不同步对比源码依赖更新描述文件中文乱码系统缺少中文字体安装 fonts-noto-cjk 等字体大型项目生成超时扫描范围过大配置忽略目录或按模块分批生成IDE 插件无法识别项目项目类型不在支持列表确认源码目录结构尝试先安装 CLI命令找不到CLI 未加入 PATH重新安装或手动配置环境变量6. 最佳实践与工程建议6.1 架构描述文件资产化架构描述文件是团队的核心工程资产应该像代码一样进行版本管理。建议做到所有架构文件的变更都通过 Pull Request 评审如果团队使用 monorepo把archify/放在仓库根目录统一管理与代码合并使用同一条 Git 主线避免架构文件和代码在分支上长期分叉。6.2 接入 CI 持续校验架构漂移往往发生在匆忙迭代中人肉检查很容易被忽略。建议把validate命令接入 CI# 示例CI 脚本中的检查步骤 archify validate --input archify/system.yml --source .如果校验失败构建流程直接阻断。这样架构合规性就从“自觉行为”变成了“评审门槛”。团队不用再担心某个服务悄悄引入了不合理的跨层依赖。6.3 控制描述文件的粒度描述文件不是越细越好。如果建模粒度细到类级别会导致维护成本极高很难长期坚持。建议根据团队需要选择层级系统级关注服务节点、数据库、外部依赖模块级关注服务内部的主要子模块接口级只有在对关键链路做专项分析时才需要。核心原则是“够用即可”让团队大多数人愿意维护比追求理论上的完整性更重要。6.4 AI 生成结果必须人工评审AI 工具能提供初稿但并不代表结果百分百正确。尤其是微服务之间的调用关系、异步消息流向AI 可能会根据代码关键词产生误判。建议在使用流程中加一步“人工评审确认”AI 生成描述文件后由熟悉系统的人检查一遍确认后再生成正式架构图。6.5 注意敏感代码与数据安全Archify 这类 AI 工具在工作时可能将部分代码片段发送到云端模型进行语义分析。如果你的项目包含核心加密逻辑、用户隐私数据或商业机密需要特别注意优先使用离线模式或自部署模型在扫描前配置.gitignore或忽略规则排除含敏感信息的目录使用内部化工具前向团队同步数据流向与权限边界。6.6 与项目文档体系整合架构图生成后可以嵌入到团队知识库、技术方案文档和新人手册中。每次架构调整时更新描述文件并重新生成图确保文档中的图片始终与代码一致。这样文档维护成本会明显降低新人也能更快理解系统全貌。7. 总结与下一步通过本文我们了解了 Archify 的核心思路不再将架构图当作一次性图片而是把架构模型变成可校验、可追踪的工程资产。它利用 AI 降低初稿生成成本再通过validate和trace等命令将架构图与现实代码绑定形成闭环。实际开发中建议先从以下三步开始在新项目里使用archify init或 AI 对话生成首版架构描述文件。把archify validate配置到 CI让架构检查自动运行。定期用archify trace做架构走读结合评审一起维护描述文件。下一步可以根据团队需求继续探索更复杂的建模维度比如加入消息队列、缓存组件、外部系统依赖或者结合代码生成工具逆向恢复历史项目架构。如果你正好需要一个能跟上代码变化的架构图方案Archify 值得在项目中实际跑一遍试试。