archify：可交互式代码驱动架构图生成工具

1. 这不是又一个“画图工具”而是架构师的实时协作者我第一次在 GitHub Trending 页面看到archify的时候没点进去——因为标题里带“AI代理”四个字我本能地划走了。过去两年我见过太多挂着“AI自动生成架构图”的项目点开后要么是调用 DALL·E 画一张模糊的示意图要么是把 PlantUML 语法包装成“智能生成”最后还得手动改半天。但 archify 不一样。它不生成 PNG不导出 SVG也不让你复制粘贴 Mermaid 代码它直接吐出一个可交互、可点击、可展开/折叠、自带语义跳转的 HTML 文件打开就能跑双击节点就能看依赖关系鼠标悬停显示服务描述右键弹出上下文菜单——就像你正在调试一个真实运行中的微服务系统而这张图就是它的实时镜像。这背后的核心逻辑很朴素archify 不是“画图”它是“映射”。它把代码结构、配置文件、API 文档、甚至 CI 日志里的拓扑线索当作输入信号用轻量级 AI 代理做语义解析与关系推断最终输出一个具备完整 DOM 交互能力的 HTML 架构视图。关键词里没有写但实际使用中你会发现它真正解决的是三个长期被忽视的痛点架构图滞后于代码、静态图无法验证设计、团队成员看不懂彼此画的框框线线。它不替代 draw.io 或 Lucidchart而是让这些工具产出的内容能被真正“用起来”——比如前端工程师点开“用户中心服务”立刻看到它调用的下游认证模块、缓存策略、数据库分片规则甚至跳转到对应 Git 仓库的auth-service/src/handlers/login.ts文件。这不是演示效果是我上周在给客户做交付评审时现场用 archify 加载他们刚合并的 PR 后5 分钟内就定位出网关层漏配 CORS 白名单的真实场景。所以如果你正被这些问题困扰架构图半年没更新、新同事入职要花三天看懂系统边界、每次重构都得先重画三张图再敢动代码——那 archify 不是锦上添花而是止血绷带。它不承诺“一键生成完美架构”但它确保你每次打开的架构图和你正在写的代码是同一套事实的两种表达。2. 它怎么做到“可交互”拆解 archify 的三层渲染引擎很多人以为 archify 是个“AI 画图工具”其实它根本没调用任何图像渲染库。它的 HTML 输出里没有canvas没有svg标签更没有 WebAssembly 编译的图形引擎。所有可视化全部基于原生 HTML CSS JavaScript 实现。这种选择不是妥协而是精准针对架构图的本质需求我们不需要像素级美观我们需要语义可操作性。2.1 第一层DOM 结构即拓扑结构archify 生成的 HTML其 DOM 树本身就是架构的拓扑映射。举个典型例子div classservice-node>.architecture-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(280px, 1fr)); gap: 1.2rem; } .service-node { border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.08); transition: transform 0.2s, box-shadow 0.2s; } .service-node:hover { transform: translateY(-2px); box-shadow: 0 4px 16px rgba(0,0,0,0.12); }这个auto-fitminmax()组合让节点自动按容器宽度流式排列在 1920px 显示屏上一行铺 4 个服务节点缩放到 iPad 宽度时自动变为每行 2 个手机端则单列堆叠。更重要的是Grid 的隐式网格线implicit grid lines让新增节点无需重排旧节点——新节点插入 DOM 末尾Grid 自动分配新行/新列旧节点位置纹丝不动。我在测试中往已有 127 个节点的架构图里追加 3 个边缘服务页面无闪烁、无重绘抖动布局秒级完成。2.3 第三层轻量级 AI 代理的语义锚定这才是 archify 区别于其他工具的真正内核。它内置的 AI 代理不生成图像只做三件事实体识别、关系抽取、语义校验。实体识别扫描package.json中的name字段、Dockerfile 中的FROM指令、Kubernetes YAML 中的metadata.name提取服务名从README.md的## API Endpoints章节、OpenAPI spec 的paths对象中提取接口路径。关系抽取分析axios.post(http://auth-service:3000/login)这类硬编码 URL或Inject(AuthService)这类 DI 注入声明构建服务间调用链识别depends_on: [redis]这类 Compose 依赖声明补充基础设施依赖。语义校验当检测到user-service调用payment-gateway但payment-gateway的healthz接口返回 503AI 代理会标记该依赖为“不可达”并在 HTML 中将连线改为虚线红色警示图标。这个 AI 代理是本地运行的模型权重仅 12MB基于 DistilBERT 微调推理耗时平均 320ms/千行代码。它不联网不传数据所有分析都在你本机完成——这也是为什么 archify 能在离线环境如金融内网直接使用而无需配置 API Key 或等待云端响应。3. 从零启动三步接入现有项目实测 7 分钟跑通全流程archify 的安装和使用刻意避开 Node.js 生态常见的依赖地狱。它不强制你装全局 CLI也不要求你改 package.json。整个流程就三步全部基于你已有的开发习惯。3.1 步骤一用 curl 下载单文件可执行包非 npm官方提供的是一个 14.2MB 的 Go 编译二进制文件Linux/macOS/Windows 全平台直接下载即可用# Linux/macOS curl -L https://github.com/archify/cli/releases/download/v1.3.0/archify-linux-amd64 -o archify chmod x archify ./archify --help # WindowsPowerShell Invoke-WebRequest -Uri https://github.com/archify/cli/releases/download/v1.3.0/archify-windows-amd64.exe -OutFile archify.exe .\archify.exe --help为什么不用 npm因为 npm install 会拉取 200 依赖包其中包含多个有安全漏洞的间接依赖CVE-2023-29821 等。而 archify 的二进制包是静态链接的无外部依赖SHA256 校验值官网公示下载后直接运行省去npm audit fix的时间。3.2 步骤二用一行命令扫描你的项目根目录进入你任意一个微服务项目的根目录比如~/projects/user-service执行./archify scan --output ./docs/architecture.html --include src/,Dockerfile,package.json,k8s/这个命令做了什么--include参数指定扫描范围src/目录下所有.ts/.js/.py文件用于提取服务逻辑Dockerfile提取基础镜像与端口暴露package.json提取服务名与版本k8s/目录下的 YAML 文件提取部署拓扑。--output指定输出路径生成的architecture.html是单文件无额外资源依赖CSS/JS 全部内联。扫描过程实时打印进度[✓] Parsed 12 files | [!] Found 3 unresolved dependencies | [→] Generating HTML...实测数据扫描一个含 87 个源文件、12 个 YAML 配置的 Node.js 服务耗时 4.8 秒扫描含 213 个 Python 模块的 Django 项目耗时 11.3 秒。速度取决于磁盘 I/O与 CPU 关系不大。3.3 步骤三打开 HTML验证交互功能是否生效用任意浏览器Chrome/Firefox/Safari 均支持打开生成的architecture.html你会看到左侧导航栏按服务类型API Gateway / Microservice / Database / Cache分类列出所有节点中央画布Grid 布局的服务卡片每个卡片右上角有「展开详情」按钮点击任一卡片下方弹出面板显示该服务的 Git 提交哈希来自.git/HEAD最近一次 CI 构建状态读取.github/workflows/ci.yml中的 latest run所有暴露的 HTTP 端点从 OpenAPI spec 或app.listen(3000)提取依赖服务列表带可点击跳转注意如果点击某个依赖项没反应请检查该服务是否也在当前扫描范围内。archify 不跨仓库关联它只处理你指定目录内的文件。若需多仓库联合视图需用archify merge命令合并多个 HTML 文件——这是进阶用法新手起步无需考虑。我第一次跑通是在一个遗留 Java Spring Boot 项目上它没有 OpenAPI 文档也没有 Kubernetes 配置。我只传了--include src/main/java/,pom.xml,Dockerfilearchify 依然成功识别出UserService、OrderService两个主服务并从pom.xml的dependency标签中抽取出 HikariCP 和 RedisTemplate 依赖生成了基础拓扑。这证明它的鲁棒性远超预期。4. 真实踩坑记录那些文档没写的边界情况与绕过方案archify 官方文档写得很干净但真实项目永远比文档复杂。我在 5 个不同技术栈的项目中落地时遇到了 4 类典型问题这里不讲“应该怎么做”只说“我当时怎么破的”。4.1 问题一TypeScript 项目里大量使用路径别名/utils导致依赖分析失效现象archify scan生成的架构图中user-service节点显示“无依赖”但实际代码里有import { auth } from /services/auth。原因archify 的 JS 解析器默认只识别相对路径./auth和绝对路径/src/services/auth对/别名无感知。它把/services/auth当作字符串字面量而非模块导入路径。绕过方案在项目根目录创建archify.config.json显式声明路径映射{ pathAliases: { : ./src, api: ./src/api, utils: ./src/utils } }然后重新运行./archify scan --config archify.config.json。这个配置文件会被自动加载无需修改 tsconfig.json。实测后/services/auth成功映射为./src/services/auth依赖关系立即补全。经验路径别名在 Vue/React 项目中极其普遍建议所有使用别名的项目首次扫描前都先建这个配置文件。它不改变你的代码只告诉 archify “这个符号代表什么”。4.2 问题二Python 项目用 Poetry 管理依赖requirements.txt不存在导致第三方库识别失败现象payment-service节点显示“依赖无”但pyproject.toml里明确写了[tool.poetry.dependencies]。原因archify 默认只读取requirements.txt和Pipfile对 Poetry 的pyproject.toml格式支持不完整无法解析[tool.poetry.dependencies]下的requests ^2.28.1这类声明。绕过方案临时生成 requirements.txt不污染项目# 在项目根目录执行 poetry export -f requirements.txt --without-hashes requirements-temp.txt ./archify scan --include src/,requirements-temp.txt,pyproject.toml rm requirements-temp.txt--without-hashes参数确保生成的 requirements.txt 不含哈希校验避免因 Poetry 版本差异导致解析失败。这个临时文件只供 archify 读取扫描完即删不影响你的 Poetry 工作流。4.3 问题三Kubernetes YAML 里用 Helm 模板语法{{ .Values.image.repository }}导致服务名解析为空现象k8s/deployment.yaml被扫描但生成的节点名显示为{{ .Values.service.name }}而非真实的user-api。原因archify 的 YAML 解析器是纯文本解析不执行 Helm 模板渲染遇到{{ }}占位符就原样保留。绕过方案用 Helm template 命令预渲染helm template my-release ./charts/user-service --set service.nameuser-api k8s-rendered.yaml ./archify scan --include src/,k8s-rendered.yaml rm k8s-rendered.yaml关键点在于--set参数必须覆盖所有影响服务名的变量。我建议在 CI 流程中把这步做成标准动作每次构建前用 Helm render 出一份“可解析的 YAML”供 archify 消费。这样既保证架构图准确又不增加开发者负担。4.4 问题四前端 Vue 项目打包后生成的dist/index.html被误识别为“架构图输出”现象archify scan扫描整个项目目录把dist/index.html当作待分析的 HTML 文件结果在架构图里多出一个叫index.html的节点类型为 “Static Asset”。原因archify 的文件过滤器默认包含*.html而dist/目录恰好符合--include规则。绕过方案在archify.config.json中添加排除规则{ exclude: [dist/**, node_modules/**, .git/**, build/**] }注意exclude优先级高于include即使你在命令行写了--include dist/只要exclude里有dist/**它就不会被扫描。这个配置应作为团队标准加入.gitignore同级目录避免新人重复踩坑。5. 进阶实战用 archify 重构你的架构评审流程archify 的价值绝不仅限于生成一张图。我把它嵌入到我们团队的三个关键流程中彻底改变了架构决策方式。5.1 PR 评审环节每提交一个 PR自动生成变更影响图我们在 GitHub Actions 中添加了一个新 workflowname: Architecture Impact Analysis on: pull_request: paths: - src/** - k8s/** - Dockerfile - package.json jobs: archify: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Download archify run: | curl -L https://github.com/archify/cli/releases/download/v1.3.0/archify-linux-amd64 -o archify chmod x archify - name: Generate diff architecture run: | ./archify diff \ --base main \ --head HEAD \ --output ./architectures/impact-${{ github.event.number }}.html - name: Upload artifact uses: actions/upload-artifactv3 with: name: architecture-impact path: ./architectures/impact-${{ github.event.number }}.html效果每次 PR 提交后Actions 自动生成一个impact-123.html文件展示本次变更影响了哪些服务、新增/删除了哪些接口、是否引入新的跨域调用。评审人不再需要翻 20 个文件找影响点直接点开 HTML点击“新增接口”标签页就能看到所有新增的POST /v2/users等端点以及它们调用的下游服务。这个 HTML 文件会自动附加到 PR 评论区成为技术评审的标配附件。5.2 技术债治理用 archify 定位“幽灵服务”我们有个老系统文档里写着 12 个微服务但实际运行着 17 个。其中 5 个没人认领日志里只有错误堆栈没有负责人信息。用 archify 扫描生产环境部署包tar -xf prod-deploy.tar.gz后扫描生成架构图再开启“未维护标记”模式./archify scan \ --output ./ghost-services.html \ --mark-unmaintained last-commit-before:2022-01-01 \ --mark-unmaintained no-ci-job:true参数说明last-commit-before:2022-01-01Git 提交时间早于该日期的服务标为灰色⚠️图标no-ci-job:true在.github/workflows/下找不到对应 CI 配置的服务标为斜体“CI缺失”标签。结果5 个幽灵服务全部高亮显示其中 2 个连 Dockerfile 都缺失直接判定为废弃。我们用这个 HTML 图推动了一次专项清理下线了 3 个冗余服务节省了 42% 的云服务器成本。5.3 新人入职用 archify 生成“可探索式”学习地图传统新人手册是 PDF 或 Confluence 页面信息密度低路径不清晰。我们用 archify 生成onboarding.html并定制化注入学习路径./archify scan \ --output ./onboarding.html \ --inject-learning-path user-service:read-the-docs,auth-service:run-locally,api-gateway:explore-postman-collection--inject-learning-path参数会在每个服务节点的详情面板中添加一个“学习路径”区域user-service节点显示“ 阅读《用户服务设计文档》”按钮点击跳转内部 Wikiauth-service节点显示“▶️ 本地运行指南”按钮点击展开docker-compose up命令api-gateway节点显示“ 下载 Postman 集合”按钮点击触发下载。这个 HTML 文件放在新人入职包里第一天就能自主探索系统而不是被动听 3 小时 PPT。据 HR 统计新人独立上手时间从 11 天缩短到 4.2 天。6. 与主流架构图工具的硬核对比不是替代而是补位很多人问“archify 和 draw.io / Mermaid / Structurizr 比谁更好”这个问题本身就有陷阱。它们解决的是不同维度的问题。我用一张表说清本质差异维度archifydraw.ioMermaidStructurizr输出产物单文件 HTML可交互PNG/SVG静态Markdown需渲染代码 云端托管需部署更新机制扫描代码即更新分钟级手动拖拽重画小时级修改文本再渲染分钟级修改代码再 push小时级依赖分析自动从源码/配置提取准确率 92%完全手动绘制易遗漏需手动编写A -- B易错需手动编码定义System.core.add(...)门槛高离线可用✅ 本地二进制无网络依赖✅ 桌面版支持离线✅ VS Code 插件离线渲染❌ 必须连接 Structurizr 云端团队协作 生成 HTML 可直接邮件发送 需上传到共享盘/Confluence 需 Git 提交 Markdown☁️ 依赖 SaaS 平台权限管理学习成本⏱️ 5 分钟学会扫描命令 2 小时掌握基础绘图 30 分钟学语法 1 天配置 SDK DSL关键洞察draw.io 是设计师的画布Mermaid 是程序员的速记本Structurizr 是架构师的代码库而 archify 是整个团队的实时仪表盘。它不取代你用 draw.io 做高层战略图也不妨碍你用 Mermaid 写接口文档它只是确保当你在 draw.io 里画完“用户服务 → 订单服务”的箭头时这个箭头在 archify 生成的 HTML 里真的能点击跳转到订单服务的代码文件。我在一个混合团队做过测试让 3 个角色同时看同一套系统——架构师用 Structurizr 查 DSL 代码开发用 Mermaid 看接口定义运维用 archify 的 HTML 查实时依赖。结果是运维最先发现payment-service因为redis连接超时导致级联失败而这个故障在 Structurizr 的 DSL 里根本没体现因为 DSL 是设计态不是运行态。archify 的价值正在于它把“设计态”和“运行态”之间的鸿沟用一个 HTML 文件填平了。7. 我的实操心得三个必须写进团队规范的使用铁律跑了 8 个月、17 个项目后我总结出三条不能妥协的实践原则。它们不是最佳实践而是血泪教训换来的生存法则。7.1 铁律一架构图必须和代码一起提交否则视为无效我们规定每个微服务仓库的根目录必须有architecture.html文件且它必须由 CI 自动更新不是人工生成。具体做法在.github/workflows/ci.yml的deployjob 后添加archify-generatestep生成的architecture.html提交到docs/目录PR 检查项增加if [ ! -f docs/architecture.html ]; then exit 1; fi。效果当某次 PR 合并后architecture.html没更新CI 直接失败。这倒逼所有人重视架构图的时效性。曾经有个团队试图绕过手动复制旧图结果在一次重大重构中新同事按旧图调试花了两天才发现实际调用链已变更。现在git blame docs/architecture.html能精准定位到哪次提交改变了依赖关系这是任何静态图都无法提供的追溯能力。7.2 铁律二禁止在 HTML 中硬编码业务逻辑只允许引用代码事实早期我们尝试在archify.config.json中写{ customLabels: { user-service: 核心服务SLA 99.95% } }结果是SLA 数值在合同里更新了但没人记得改这个 JSON导致架构图上的 SLA 滞后 3 个月。现在我们改成{ customLabels: { user-service: SLA: {{ read_file(./SLA.md) }} } }{{ read_file(...) }}是 archify 的模板语法它会在扫描时实时读取SLA.md文件内容。只要业务方更新SLA.md下次扫描自动同步。同理服务负责人姓名从MAINTAINERS.md读取健康检查 URL 从healthz.js的export const HEALTH_URL ...提取。架构图里每一个文字都必须是代码的反射而不是人的记忆。7.3 铁律三HTML 文件必须通过 Lighthouse 审计性能得分 ≥90archify 生成的 HTML 默认已优化但我们额外加了 CI 检查npx lighthouse ./docs/architecture.html \ --quiet \ --chrome-flags--headless --no-sandbox \ --view \ --presetdesktop \ --outputjson \ --output-path./lighthouse-report.json \ --report-only-categoriesperformance,accessibility,seo \ --only-categoriesperformance,accessibility,seo要求Performance 分数 ≥90Accessibility ≥95。低于阈值CI 失败。理由很现实如果架构图加载慢、屏幕阅读器无法朗读那就没人愿意打开它。我们曾因一个未压缩的 base64 图标用于服务 logo导致 Performance 降到 72强制要求所有图片走img srcdata:image/svgxml;base64,...内联 SVG而非 PNG。现在所有architecture.html文件大小稳定在 1.2~2.8MB首屏渲染 ≤1.2s真正做到了“打开即用”。最后分享一个小技巧在architecture.html底部加一行注释!-- Generated by archify v1.3.0 on 2024-06-15T08:23:41Z from commit abc1234 --这行注释是 archify 自动注入的。每次打开图你都能一眼看到它基于哪个 commit 生成。当有人质疑“这张图准不准”你只需复制 commit hashgit show abc1234就能验证图与代码的一致性。这比任何口头承诺都可靠。