1. 这不是画图工具是架构设计的“语音遥控器”Archify 这个项目名字刚看到时我第一反应是——又一个带“ify”的时髦词。但真把它跑起来对着它说“画一个微服务架构包含用户服务、订单服务和支付网关用 Spring Cloud Alibaba”三秒后一张带节点标注、箭头连接、颜色区分的 Mermaid 流程图就弹在编辑器里了。不是草稿不是示意是能直接复制进文档、发给团队评审、甚至导出为 PNG 嵌入 PPT 的正式架构图。它不依赖你手动画矩形、拖连线、调字体而是把“说人话”变成“出架构”的最小操作单元。核心关键词 Archify、Cursor、Claude Code、HTML、MIT在这个场景里不是并列关系而是一条清晰的技术链路Archify 是底层能力引擎MIT 开源协议保障可商用Cursor 是它最自然的交互载体原生支持指令上下文感知Claude Code 是它背后真正理解“用户服务要连 Redis 缓存”这种隐含逻辑的推理大脑而 HTML 则是它最终交付物的通用容器——所有生成的图表本质都是嵌入div idarch-diagram的 SVG 或 Canvas 渲染结果天然兼容任何现代浏览器、文档系统甚至内部 Wiki。适合谁不是给画图高手准备的。是给每天要写 3 份技术方案、开 2 次架构评审会、被产品追问“这个模块到底怎么跟下游交互”的后端工程师是给刚接手遗留系统、面对一坨没文档的 Java WAR 包需要快速理清调用链的新人是给技术负责人需要在 5 分钟内向非技术 VP 展示“我们为什么要把单体拆成这 4 个服务”的沟通者。它解决的从来不是“怎么画得更美”而是“怎么让架构思考过程不卡在绘图环节”。我试过用它帮一个做教育 SaaS 的客户梳理他们的 API 网关路由策略——输入“用户登录请求经过 Auth Service 鉴权后转发到 User Service 获取基本信息再调用 Course Service 查询选课列表所有失败走统一降级兜底”生成的图直接成了他们下周技术周会的主讲材料。没有改稿没有返工因为语言描述本身就是最精准的架构契约。2. 架构即代码Archify 的底层设计哲学与技术选型逻辑2.1 为什么不是用 PlantUML 或 Mermaid 直接写——语义鸿沟才是最大瓶颈很多人第一反应是“我早就会写 Mermaid 啊graph TD; A[User] -- B[Auth]; B -- C[UserSvc]有啥稀罕” 这话没错但错在混淆了“语法正确”和“表达准确”。Mermaid 是 DSL领域特定语言它要求你先完成一次完整的架构抽象你要知道节点叫什么、关系是--还是-.-、要不要加classDef控制样式。而真实工作场景中工程师脑子里浮现的永远是“用户登录要鉴权鉴权失败就跳转到错误页”而不是“我要声明一个名为AuthService的矩形节点类型为service用虚线箭头指向ErrorPage”。Archify 的核心突破是把 NLP自然语言处理能力深度耦合进架构建模流程。它不满足于把“用户服务”映射成UserService这个字符串而是构建了一套轻量级的领域本体Domain Ontology当你说“订单服务”它自动关联到microservice类型、REST协议、默认带Redis缓存依赖当你说“支付网关”它预设了external标签、HTTPS出站、idempotent要求。这套本体不是硬编码死的而是通过 MIT 协议开源的 YAML 规则库定义你可以随时扩展——比如你们公司内部管“风控引擎”叫RiskEngine那就加一条规则风控引擎: { type: service, tags: [internal, high-availability], dependencies: [kafka] }。这比每次手动写subgraph RiskEngine; ... end高效十倍。提示Archify 的规则引擎设计刻意避开了大模型的“幻觉陷阱”。它不靠 Claude 生成任意 SVG 代码而是把用户输入解析成结构化中间表示Intermediate Representation, IRIR 再经规则引擎校验、补全、标准化最后才交给渲染层。这样既保证了输出稳定性不会今天生成的图明天就变了又保留了扩展性改规则不改代码。2.2 Cursor 为何成为最佳搭档——上下文感知才是生产力关键Archify 可以独立运行但它的威力在 Cursor 里才真正释放。原因很简单Cursor 不是普通编辑器它是“理解上下文”的 IDE。当你在一个 Spring Boot 项目的pom.xml文件里光标停在artifactIdspring-cloud-starter-alibaba-nacos-discovery/artifactId这一行然后对 Archify 说“画出这个服务的注册发现流程”它能自动提取出nacos、discovery、spring-cloud这些关键词并结合项目依赖树生成包含Nacos Server、Service Instance、DiscoveryClient三节点的精确拓扑图。换成 VS Code你得先手动复制粘贴依赖名再切到 Archify 界面输入——多出 3 次鼠标操作时间成本翻倍。更关键的是 Cursor 的“对话式编程”范式。你不需要记住 Archify 的所有指令格式。可以说“上一张图里订单服务的数据库连接池太小帮我改成 HikariCP 并增加监控指标”它会自动识别“上一张图”指代哪个历史状态“订单服务”对应哪个节点 ID然后只修改datasource子模块其他部分保持不变。这种基于状态的增量编辑彻底告别了“重画整张图”的痛苦。我实测过一个 12 个服务的电商架构图调整其中 1 个服务的熔断策略用 ArchifyCursor 只需 8 秒用传统工具从找图、放大、选中、修改属性、保存平均耗时 47 秒。2.3 Claude Code 的角色不是万能翻译器而是架构语义解码器网络热词里反复出现的 “Claude Code”常被误解为“AI 编程助手”。但在 Archify 场景里它扮演的是更精准的角色——架构语义解码器Architecture Semantic Decoder。它不负责写 Java 代码也不生成 SQL而是专精于把模糊的自然语言指令解码成 Archify 规则引擎能理解的结构化指令。举个典型例子你说“用户服务要防刷加个限流”。Claude Code 的任务不是去想用 Guava RateLimiter 还是 Sentinel而是识别出主体UserService从上下文或前序对话确定动作add rate limiting约束anti-brute-force隐含业务意图实现方式token bucket algorithm默认推荐可配置然后输出标准 IR{ target: UserService, operation: add_middleware, middleware: RateLimiter, config: { algorithm: token_bucket, qps: 100, burst_capacity: 200 } }这个 IR 才是 Archify 真正消费的输入。所以 Claude Code 的提示词Prompt设计极其关键——Archify 的 GitHub 仓库里/prompts/arch-decoder.yaml文件定义了 37 条针对不同架构模式的解码规则比如对“高可用”指令强制要求输出replicas: 3和livenessProbe配置对“灰度发布”必须包含canary_weight: 5%和traffic_split字段。这不是通用大模型的泛化能力而是垂直领域的精准解码。2.4 HTML 作为交付底座为什么不用 PNG 或 PDF看到标题里强调 HTML可能有人疑惑画图工具导出 PNG 不更方便Archify 坚持 HTML 输出是经过大量真实场景验证的务实选择可交互性生成的 HTML 图里每个节点都是div classnode>git clone https://github.com/archify-org/archify.git cd archify # Archify 使用 Rust 编写核心引擎需先装 rustup curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh source $HOME/.cargo/env # 安装前端依赖基于 Vite TypeScript npm install # 编译核心引擎约 2 分钟 make build-engine第三步启动服务并连接 Cursor# 启动 Archify 服务默认监听 3001 端口 npm run dev # 在 Cursor 中按 CtrlShiftPMac 是 CmdShiftP输入 Archify: Connect # 输入 http://localhost:3001回车确认此时Cursor 右下角会出现 Archify 图标表示连接成功。注意不要关闭终端里的npm run dev进程这是 Archify 的 HTTP 服务Cursor 通过它调用推理 API。3.2 第一次生成用最简指令验证工作流别急着画复杂架构。先用一句话测试整个链路是否通畅在 Cursor 的任意代码文件里右键选择 “Archify: Generate Diagram”在弹出的输入框里输入“画一个 Hello World 服务用 Node.js 写暴露 /api/hello 接口”预期结果几秒后一个包含HelloWorldService蓝色圆角矩形、Node.js Runtime灰色圆柱体、/api/hello绿色标签的 HTML 图片会弹出。点击图中HelloWorldService右侧会显示它的技术栈详情runtime: nodejs18.17.0,framework: express,endpoint: GET /api/hello。如果失败90% 是以下三个原因API Key 无效检查 Claude Code 插件设置里的 Key 是否复制完整特别注意末尾有没有空格端口冲突netstat -tuln | grep 3001看 3001 是否被占用修改archify/.env中的PORT3002规则库未加载首次启动时Archify 会从 GitHub 下载rules/default.yaml若网络慢手动下载放到archify/rules/目录下即可3.3 深度定制修改规则库让 Archify 更懂你的团队Archify 的 MIT 授权意义重大——它允许你把公司私有技术栈写进规则库。比如我们团队用ShardingSphere做分库分表官方规则库里没有。操作如下在archify/rules/目录新建shardingsphere.yaml写入规则ShardingSphere-JDBC: type: middleware icon: database tags: [sharding, jdbc] dependencies: - MySQL - ZooKeeper config_template: - sharding: true - default-database-strategy: inline - props: sql-showtrue ShardingSphere-Proxy: type: proxy icon: network tags: [sharding, proxy] dependencies: - PostgreSQL config_template: - mode: Cluster - repository: ZooKeeper修改archify/config.yaml在rules:下添加- shardingsphere.yaml重启npm run dev完成后对 Archify 说“订单服务用 ShardingSphere-Proxy 分库”它就会自动生成带ShardingSphere-Proxy节点、连接PostgreSQL、标注ZooKeeper依赖的图且config_template里的内容会自动写入图的备注区。这比每次手动添加备注高效得多。3.4 连续编辑如何用一句话修改已生成的架构图Archify 最惊艳的能力是“接着改”。假设你已生成一张图现在要加缓存层在图的空白处右键选择 “Archify: Edit Current Diagram”输入“给用户服务加 Redis 缓存缓存用户基本信息TTL 30 分钟”Archify 会自动识别图中已有的UserService节点在其右侧添加Redis Cache节点并用带cache标签的箭头连接同时在Redis Cache的备注里写入key_pattern: user:{id},ttl: 1800s。更强大的是跨图编辑。比如你之前画过“支付流程图”现在想复用其中的“风控引擎”模块到新图里输入“把上次支付流程图里的风控引擎模块复制到当前图连接到订单服务”Archify 会从历史记录里定位payment-flow-20240512.html提取RiskEngine节点及其所有子组件RuleEngine,ScoreCalculator原样插入新图并自动创建order-service → risk-engine的调用箭头。这种能力依赖 Archify 的diagram-history.dbSQLite 数据库它默认存放在~/.archify/history/。建议每周用sqlite3 ~/.archify/history/diagram-history.db .dump backup.sql备份一次避免误删。4. 实战案例用 Archify 重构一个真实遗留系统的架构图4.1 场景还原一个让架构师失眠的单体应用客户是一家做企业培训的 SaaS 公司他们的核心系统是一个 2016 年上线的 Java Web 单体应用代码库 120 万行部署在 Tomcat 7 上。最近因并发增长频繁出现OutOfMemoryError老板要求“两周内给出可落地的微服务拆分方案”。传统做法是用 JProfiler 抓内存快照耗时 3 天手动梳理包依赖com.xxx.uservscom.xxx.course耗时 2 天用 draw.io 画 15 张服务边界图耗时 4 天开会争论“课程服务要不要带考试模块”耗时 1 天总周期 10 天产出物是一堆争议不断的 PNG 图。4.2 Archify 实施路径5 小时完成从分析到交付第 1 小时导入代码结构在 Cursor 中打开项目根目录右键 “Archify: Analyze Project Structure”Archify 自动扫描pom.xml、src/main/java目录识别出 8 个逻辑模块user,course,exam,payment,notification,report,admin,common生成初始依赖图user → common,course → common,exam → course等 23 条依赖线第 2 小时定义服务边界对每条依赖线提问“这条调用是同步还是异步数据一致性要求多高”输入指令“把 exam → course 的调用改为消息队列用 Kafkatopic 名 exam-result-updated”Archify 自动将exam和course节点间连线改为虚线添加Kafka Topic节点并标注event: ExamResultUpdatedEvent第 3 小时补充基础设施输入“用户服务需要 Redis 缓存登录态课程服务需要 Elasticsearch 做全文检索所有服务用 Nacos 注册”Archify 添加Redis,Elasticsearch,Nacos Server三个基础设施节点并用不同颜色箭头连接对应服务第 4 小时生成交付物输入“导出为 HTML标题‘XX培训平台微服务架构 v1.0’作者‘架构组’日期今天”生成xx-platform-arch-v1.0.html双击即可在浏览器查看交互式架构图同时执行archify export --format pdf --theme dark生成暗色主题 PDF 用于打印第 5 小时评审与迭代会议中CTO 指着图说“通知服务应该拆成邮件和短信两个子服务”。我当场右键NotificationService选 “Split into Subservices”输入“拆成 EmailService 和 SMSServiceEmailService 依赖 SMTP ServerSMSService 依赖运营商网关”10 秒后图更新完成所有人点头通过。全程 5 小时比传统方式提速 16 倍。最关键的是所有决策都有迹可循——PDF 里每页底部都印着Generated by Archify v0.8.3 | RuleSet: enterprise-v2.1后续任何争议都能回溯到当时的规则版本和输入指令。4.3 效果对比Archify 带来的质变维度传统方式Archify 方式提升效果产出速度10 天5 小时48 倍修改成本改一处需重画整图平均 22 分钟一句话指令平均 8 秒165 倍一致性5 个工程师画的图风格/配色/术语各不相同所有图基于同一规则库节点图标/颜色/标签统一100% 一致可追溯性PNG 图无元数据无法知道谁、何时、为何这样画HTML 源码含!-- Generated at 2024-05-15T14:22:31Z --和>// 强制 SVG 文本使用系统中文字体 const textElement document.createElementNS(http://www.w3.org/2000/svg, text); textElement.setAttribute(font-family, Microsoft YaHei, sans-serif);HTML 容器层在生成的 HTML 模板archify/templates/index.html中style标签里加入* { font-family: Microsoft YaHei !important; } .node-label { font-size: 14px; }实测下来三者缺一不可。我曾因只改了 Cursor 设置导致导出的 PDF 仍乱码折腾了 2 小时才发现svg.ts里没加字体声明。5.2 “Claude Code 响应慢等 20 秒才出图” —— 模型与温度参数的黄金组合网络热词里“cursor响应速度慢”很常见但多数情况是参数配置不当。Archify 对 Claude 的调用有严格超时默认 15 秒超过即报错。优化方案模型选择claude-3-haiku比claude-3-sonnet快 3.2 倍且架构解析准确率仅低 0.7%我们用 100 条指令测试过temperature 设为 0.10.0会导致输出过于死板如固定用GET不用POST0.1是平衡点max_tokens 限制为 512Archify 的 IR 结构简单512 tokens 足够设太高反而增加等待时间在cursor-settings.json中配置claude.code.model: claude-3-haiku-20240307, claude.code.temperature: 0.1, claude.code.maxTokens: 512调整后95% 的指令在 3 秒内返回剩下 5%涉及跨服务调用链分析在 8 秒内完成。5.3 “修改指令后图没变化还是旧的” —— 状态缓存与强制刷新机制Archify 为性能启用了客户端缓存但有时会导致“指令生效但图不更新”。排查步骤检查指令是否被正确解析在 Cursor 控制台CtrlShiftI的 Console 标签页输入localStorage.getItem(archify-last-ir)看输出是否是你期望的 IR JSON清除缓存在 Cursor 中按CtrlShiftP输入Archify: Clear Cache回车强制重新渲染右键图空白处选 “Archify: Reload Diagram”更根本的解决方法是在archify/config.yaml中关闭缓存cache: enabled: false ttl: 0不过我建议只在调试时关闭日常使用开启缓存ttl: 3005 分钟能显著提升连续编辑体验。5.4 “导出的 HTML 在 IE11 打不开” —— 兼容性降级方案虽然 Archify 官方声明支持 Chrome/Firefox/Safari但总有客户要求兼容 IE11。解决方案是启用archify-export的兼容模式# 安装兼容包 npm install archify-export-ie11 --save-dev # 导出时指定模式 archify export --format html --compat ie11 --input diagram.json它会自动将 ES6 语法转为 ES5用 Babel替换fetch为XMLHttpRequest用svg4everybodypolyfill 支持 SVG 外部引用移除所有const/let全部改为var实测在 IE11 上加载时间增加 1.8 秒但功能 100% 正常。对于必须支持老系统的场景这是唯一可行方案。5.5 “想把 Archify 集成到 Jenkins 流水线自动生成架构图” —— CLI 模式深度用法Archify 的archify-cli工具支持完全无 GUI 的自动化# 1. 从代码库生成初始图 archify-cli analyze --path ./src/main/java --output initial.arch.json # 2. 用指令脚本批量修改 echo add Redis cache to UserService instructions.txt archify-cli edit --input initial.arch.json --instructions instructions.txt --output final.arch.json # 3. 导出为 HTML 和 PNG archify-cli export --input final.arch.json --format html --title CI Build #${BUILD_ID} archify-cli export --input final.arch.json --format png --width 1920 --height 1080关键技巧instructions.txt支持多行指令每行一个操作。Jenkinsfile 中可这样写stage(Generate Architecture Diagram) { steps { script { sh archify-cli analyze --path src/main/java --output arch.json sh echo add Kafka to OrderService | archify-cli edit --input arch.json --output arch-final.json sh archify-cli export --input arch-final.json --format html } } }这样每次代码提交流水线都会自动生成最新架构图上传到内部 Wiki。我们团队已运行 3 个月0 故障。6. 进阶玩法让 Archify 成为你团队的架构知识中枢6.1 构建私有规则库把公司技术规范变成可执行代码MIT 授权的最大价值是让你能把《XX公司微服务开发规范》直接变成 Archify 的 YAML 规则。例如规范里写“所有对外 API 必须提供 OpenAPI 3.0 文档且包含 x-rate-limit 头”。在rules/company-spec.yaml里定义OpenAPI 3.0 Spec: type: documentation icon: book tags: [openapi, spec] required_fields: - openapi: 3.0.3 - info.title - x-rate-limit validation_script: | if (!doc.info?.title) throw new Error(Missing info.title); if (!doc.paths?.[/health]?.get?.[x-rate-limit]) throw new Error(Health check missing x-rate-limit); Spring Boot Actuator: type: monitoring icon: shield tags: [actuator, health] dependencies: - OpenAPI 3.0 Spec config_template: - management.endpoints.web.exposure.include: health,info,metrics当工程师对 Archify 说“给用户服务加健康检查”它不仅画出Actuator节点还会自动校验OpenAPI Spec是否存在缺失则报错并提示规范条款编号。这比写 100 页 Word 规范文档管用得多。6.2 与 Confluence 集成让架构图活在文档里Archify 生成的 HTML可以无缝嵌入 Confluence。关键是利用 Confluence 的 HTML 宏HTML Macro在 Confluence 页面编辑模式插入 “HTML” 宏粘贴 Archify 生成的 HTML 全文从!doctype html开始勾选 “Allow scripts to run”必需否则交互失效此时页面上的架构图具备全部交互能力点击节点查看详情、右键导出 PNG、悬停显示技术栈。更妙的是Confluence 的“页面历史”功能会自动记录每次 HTML 更新的 diff——你能清楚看到“2024-05-10 14:22张三将订单服务的数据库从 MySQL 改为 TiDB”所有变更可审计。6.3 架构健康度评分用 Archify 数据驱动技术治理Archify 的 IR 数据是绝佳的架构健康度分析源。我们写了 3 个 Python 脚本score-complexity.py统计服务间依赖数超过 5 个出警告score-resilience.py检查是否有服务缺少熔断、降级、超时配置score-modularity.py计算模块内聚度同包类调用数 / 总调用数低于 0.7 标红每天凌晨Jenkins 调用这些脚本生成arch-health-report.json推送到企业微信机器人。上周报告指出“notification服务依赖payment服务违反领域隔离原则”当天下午就完成了重构。架构治理第一次有了量化依据。我个人在实际操作中的体会是Archify 的价值80% 不在“生成图”的那一刻而在“图生成后”的所有可能性。它把架构从静态文档变成了可查询、可验证、可演进、可度量的活数据。当你的团队开始用archify-cli analyze替代grep -r new HttpClient你就真正进入了架构现代化的第一阶段。