1. AI画架构图到底差在哪了先说个我自己的真实感受。去年开始团队里越来越多同事习惯让AI直接生成架构图一开始确实惊艳prompt一敲Mermaid或者PlantUML的代码马上就出来拓扑关系、分层结构都有模有样。但用着用着就发现问题了AI画出来的图看着对实际上经不起推敲。举几个我这半年里反复踩的坑。第一个是命名不一致AI在service层叫OrderService到了数据访问层就变成了OrderRepositoryImpl排查了半天发现是AI上下文窗口丢了早期信息。第二个是依赖关系方向画反明明A模块调用B模块图上箭头却从B指向A这种错误如果不逐行核对代码光看图根本发现不了。第三个更隐蔽AI会自动“脑补”不存在的组件比如某个缓存中间件代码里压根没引入但因为prompt里写了“高可用架构”它就自作主张加进去了。这些问题的本质是什么我自己的结论是架构图的核心价值不在“画”而在“验收”。让AI画图只是第一步怎么证明这张图跟代码库的真实结构对得上才是真正的难点。一份架构图如果不能反映系统的真实情况那它只是张漂亮壁纸连文档都算不上。这也是我后来认真研究archify的原因。它做的事情简单说就是给AI生成架构图这件事加了一条验收流水线。不是让AI画完就完而是画完之后自动去跟代码库进行比对、校验、反馈不合格就打回重来。这思路听起来不复杂但真做起来里面的细节比你想象的多得多。先说清楚一个区分。市面上画架构图的工具很多有纯手绘的比如draw.io、Excalidraw有靠代码生成图的比如Mermaid、Graphviz也有从代码反向解析的比如Structure101、jQAssistant。archify的定位跟这些都不太一样它更像是一个AI Agent 静态分析校验器的组合体AI负责“画”静态分析引擎负责“验”两者通过一条流水线串起来。这套设计解决了几个实际问题。第一它不需要你去维护一套“标准架构图”作为对照基准而是直接从代码仓库拉取真实结构作为事实来源。第二校验失败时它能给出具体的差异报告而不是笼统说一句“图不对”。第三它把整个流程固化下来放到CI里跑也行本地跑也行反正是可重复的。接下来我把我实际使用archify的过程、踩过的坑、调参的心得全部拆开来讲。如果你也正在为“AI画图不靠谱”头疼这篇文章应该能帮你省下不少时间。2. archify的验收流水线到底是怎么设计的2.1 从画图到验收一条流水线怎么串起来的先用一句话概括archify的核心工作流AI根据prompt生成架构图草稿然后自动从代码库提取真实架构信息两者做结构比对生成一致性与合理性报告根据需要自动修正或标记异常。整个过程分四个阶段生成、提取、比对、反馈。这四个阶段不是串行跑一遍就结束。archify支持多轮迭代比如第一次比对发现OrderService没对上它会带着这个差异信息重新生成一版图再比对一次。所以严格来说它的流水线是带反馈回路的有点类似AI编程工具里的“测试驱动生成”思路——先用测试在这里是结构校验约束AI的输出再让AI根据失败结果自我修正。这里有一个很关键的细节校验标准和生成过程是解耦的。也就是说AI生成模块和架构验证模块是两套独立的东西AI可以替换成不同厂商的大模型校验引擎也可以替换成自己公司内部的静态分析规范。archify本身不强绑定某个模型或某种语言这个设计我觉得是它能落地的关键。2.2 架构图生成AI画图也有“提示词工程”先聊生成端。archify支持用自然语言描述架构需求比如“这是一个基于Spring Boot的微服务系统包含网关、认证中心、订单服务、商品服务服务间通过OpenFeign调用使用Nacos做注册中心Redis做缓存MySQL做持久化”。然后它会基于这套描述生成一版架构图格式是Mermaid、PlantUML还是SVG都可以配置。但如果你以为随便写两句就能得到完美架构图那失望是必然的。我自己试下来archify对prompt的要求其实比普通AI绘图工具更高因为它要把自然语言描述拆解成可校验的结构化元素。比如你说“订单服务调用商品服务”它需要明确是HTTP调用、RPC调用还是消息队列因为这三者在架构图里的表示方式不同在代码里的校验逻辑也不同。所以archify的prompt里关系语义比节点描述更重要。我自己的经验是描述节点时尽量带上技术栈标注比如OrderService (Java 21, Spring Boot 3.x)描述关系时明确通信方式同步/异步、协议类型描述数据流时标明存储介质。信息越完整后面校验的准确率越高。2.3 架构真值提取不靠AI猜靠代码扫描接下来是archify最核心也最硬核的部分——从代码库提取“真实架构”。这一步决定了后续所有校验结论的可靠性如果这一步有偏差后面全是白干。archify的提取引擎做的工作大致分三层语言层它内置了多语言解析器目前主流的Spring BootJava/Kotlin、Go、PythonFastAPI/Django、Node.jsExpress/NestJS、TypeScript等项目结构都能识别。框架层它不只是扫描文件和类而是理解框架语义。比如看到RestController就知道这是HTTP接口层看到FeignClient就知道这是一个服务调用客户端看到KafkaListener就知道这是消息消费者。这一步很关键因为它能区分“代码里的依赖”和“真实的调用关系”。运行时推断层有一些调用关系在代码里是看不出来的比如通过配置文件动态路由的调用、SPI机制加载的实现、反射调用的类。archify会结合配置文件、注解、约定式命名做推断并且标注出“推断关系”和“静态关系”两种可信度。这一层提取出来的东西本质上是一个架构事实模型——包含组件清单、依赖矩阵、层间调用关系、外部依赖清单等。这跟我们人工画图时脑子里构建的模型是同一个东西只是它用代码扫描的方式自动完成了。2.4 一致性校验图上的每一个框都有人盯着提取出真实架构之后就是和AI生成图进行比对了。archify的校验不是“图片对比”这种像素级的验证而是两层结构的比对元素存在性图上的每个节点在真实架构中是否存在。多画了节点AI脑补会被标记为“冗余元素”漏画了节点会被标记为“缺失元素”。关系正确性图上每一条连线在真实调用关系里是否存在、方向是否正确。这里特别注意archify会把“应该存在的真实关系但图上没有”和“图上画了但实际上不存在的虚拟关系”区分开分别用不同级别的告警标识。我实际用下来这个比对的结果不只是告诉你“对”或“不对”而是给出一份带权重的差异报告。比如“缺失服务端接口OrderService 缺少/api/order/query端点定义”再比如“依赖方向不匹配代码中 InventoryService 依赖 ProductService图中方向相反权重高”。权重高的项会直接判定校验不通过权重低的项则作为提醒。2.5 反馈闭环AI画的图也能“有错就改”校验不通过之后archify不是简单地亮红灯而是把这些校验错误反馈给AI生成器让它针对性修改。说白了就是把架构校验器当成AI的“考试老师”老师指出哪里错了学生根据意见重新作答。这里有个有趣的细节archify在反馈时并不是把整个差异报告原样塞给AI而是做了“优先级排序 人类可读化”的处理。比如标记为P0的问题如“服务间实际调用关系和图不一致”会强制要求AI重画标记为P1/P2的问题则作为建议项由用户自行决定是否处理。这样可以避免AI因为纠缠细节问题而忽略大方向也控制住了多轮迭代的次数。我在实际使用中用了一个比较省心的配置P0差异超过1个就自动触发重绘P1差异超过5个触发重绘P2只报告不重绘。这样整个流水线在大多数情况下只需要两三轮迭代就能稳定通过不太会出现无限循环的情况。3. 从0到1我实际跑通archify的完整过程3.1 安装与初始化比你想象的要轻archify的安装方式分两种本地CLI和CI插件支持主流CI系统。我本地用的是Docker方式直接拉镜像跑一个交互式终端就行。它不需要独立的数据库状态存储默认用本地的SQLite文件这也让整个工具非常轻量完全不会污染你的项目仓库。装完之后第一步是初始化。archify会问你几个问题项目语言、构建工具、主框架类型、是否需要识别Spring Cloud组件等。我建议这里别偷懒把选项都认真选一遍因为它直接决定后面提取引擎用哪个解析器。比如我的项目是Spring Boot Maven Java 21如果初识化时选了“Java通用项目”而没选“Spring Boot”那后面FeignClient、RestController这类语义就都不会被识别。初始化完成后会生成一个archify.yaml配置文件核心内容如下project: name: demo-order-service language: java framework: spring-boot build: maven model: provider: openai model-name: gpt-4o-mini validation: element-existence: missing-element-level: error # 缺失元素按 error 级别 redundant-element-level: warning # 冗余元素按 warning 级别 relation-check: direction-level: error # 方向错误按 error 级别 hallucinated-relation-level: error # AI脑补的关系按 error 级别这里我特意把“AI脑补关系”的级别调成了error因为这是AI画架构图最容易犯的错误而且也是最让架构评审头疼的问题。宁可多报错也不能让一张虚假的图混进文档库。3.2 第一次画图预期管理很重要配置好之后我用了一个比较典型的prompt测试生成一个订单中台系统的架构图要求包含接入层API Gateway、业务层订单服务、支付服务、库存服务、数据层MySQL集群、Redis缓存。服务间通过OpenFeign同步调用支付完成后通过RocketMQ通知库存服务。请使用Mermaid格式输出。第一次生成的图说实话看上去挺漂亮。分层清晰、颜色标注也规范节点之间的箭头方向大体符合我的描述。但archify的验收结果就没那么友好了一轮校验下来报告里列了4个P0问题、7个P1问题P0-1代码库中OrderFacade实际是业务层对网关层暴露的门面类但图中未体现。P0-2PaymentCallbackHandler实际通过RocketMQ消费消息并非通过OpenFeign调用图中依赖方向错误。P0-3代码中InventoryService通过InventoryDeductFacade对外提供接口但图中直接标注为InventoryService名称不一致。P1-1P1-7包括若干“具有真实关系但图未覆盖”的提醒项。看到这个结果我第一反应是“这也太严格了吧”但冷静下来细看人家说得每条都对而且对项目理解的程度已经不亚于一个熟悉代码库的人肉架构师了。特别有意思的是P0-1和P0-3这类问题如果靠人工评审至少要拉上两三个熟悉系统的人才看得出来archify扫一遍就完事了。3.3 人工介入调整给AI一点“项目背景知识”第一轮校验失败后我面临两个选择让AI自动再画一版还是我手动改prompt。我推荐的做法是先手动补背景知识再让AI重跑而不是直接让它“根据错误修改”。原因很简单AI在第一次生成时缺失的是对代码库的事实认知而不是绘图能力。如果你只是把错误报告丢给它让它改它仍然没有“订单中台真实结构是什么样”的背景信息改出来的图大概率是东拼西凑地补几个节点错误报告里的问题可能解决了一部分却新增了其他幻觉。所以我在prompt里追加了这样一段补充约束业务层真实模块包括 order-facade、order-core、payment-core、payment-callback、inventory-facade、inventory-core。网关层通过 OrderFacade 访问订单域而不是直接访问 OrderService。支付结果回调通过 RocketMQ 异步处理不通过 Feign 同步调用。数据层仅包括 MySQLorder_db、payment_db、inventory_db与 Redis缓存热点商品信息。重新跑了一轮这次P0问题全部清零P1还剩两条——主要是漏画了某个外部依赖比如短信通知服务。我看了看觉得可以接受就手动在图上补了两行就正式通过了。这里我总结出一个规律AI画架构图本质上跟带新人一样你给的上下文越准确它画出来的图越靠谱。你不能指望它看一眼代码仓库就自己理解业务全貌即便archify能从代码提取真实的类结构但“这些类在业务上是什么角色”这种知识还是要靠prompt补充进去。3.4 把验收流水线接进CI团队协作的关键一步本地跑通只是第一步真正让archify发挥作用的地方是把它接进CI流水线。我这边用的是Jenkins配置上其实很简单——在代码合入或者发版前触发一次archify校验校验失败就阻断构建。stage(Architecture Validate) { steps { sh archify validate --config archify.yaml --ci-mode true } }接入CI之后的效果说实话比我预期的要好。以前团队画架构图全靠PPT而且往往只在项目启动时画一次三个月后代码跟图完全对不上。现在每次合入代码都会自动校验一遍架构图跟代码是否一致不一致就打回等于给架构图设了一个“保质期”每过一天它都会自动过期逼着你持续维护。这里分享一个小的实用配置我设置了两个校验档位。主干分支develop校验级别设到strict任何P0/P1问题都阻断功能分支feature校验级别设到moderate只阻断P0问题P1报告出来给开发参考。这样既保证了主干质量又不在开发阶段过度打扰大家。4. 说说它的局限性这些问题现在还绕不开archify不是万能的这一点我用了两个月后深有体会。以下几类场景它现在还处理得不太好。第一多语言混合项目。我有个项目是Java Python Go三种语言混编中间通过gRPC通信。archify目前对单语言的提取质量很高但跨语言调用链路的分析还是弱一些特别是一个服务用Java写、另一个用Python写两者之间的调用关系它往往只能识别到“存在未解析的外部依赖”这个级别没法细到具体方法。第二动态创建的拓扑。有些系统依赖运行时服务发现比如Kubernetes环境里的Pod自动伸缩服务间的调用关系会动态变化。archify基于静态代码和配置文件做分析是“跑不了真实流量”的所以对这种动态拓扑捕捉不到全貌。如果你需要的是“运行时真实调用链”那还得配合链路追踪系统比如SkyWalking、Zipkin。第三prompt的敏感性。这个我前面提过archify对prompt质量非常敏感。同样是让它画一张架构图写详细了它能生成接近生产水平的图写笼统了它能画出一张“逻辑正确但毫无用处”的图。而且这种区分往往是不可预测的有时候你以为自己写清楚了它还是理解偏了。这个东西没法根治只能通过多迭代来提高稳定性。第四不是“架构治理平台”。archify的定位很明确就是“架构图生成 一致性校验”它不会给你做架构健康度评分也不会帮你识别循环依赖、扇入扇出异常这类架构坏味道。如果你想做的是更系统的架构治理那可能需要跟其他工具配合使用。这些局限有些是工具本身发展阶段的问题有些是技术原理上绕不过去的坎。我自己的建议是把archify当作“架构图的自动化审校员”来用而不是“架构师的替代品”。它能把重复性、机械性的校验工作自动化但架构决策、演进方向这些东西还是得靠人来判断。5. 我的实操心得与踩坑记录最后一部分把这两个月用下来的实操心得整理一下有些是文档里不会写的有些是我自己踩坑换来的教训。5.1 关于prompt的几个小技巧prompt这块我说三个高频踩坑点。第一个是别把“描述需求”和“描述结构”混在一起。一开始我喜欢在prompt里写一大堆业务背景、非功能需求希望AI“理解”系统而后画图结果它经常把性能需求画成部署架构徒增冗余节点。后来我学乖了prompt里只写两件事有哪些模块、模块之间的关系是什么其余一概不写准确率反而高了。第二个是命名必须精确。前面说了archify会对图上节点名和代码中的类名做精确匹配。如果你在图上写OrderService代码里实际是OrderFacade它就会判为不一致。所以prompt里节点命名一定要用真实类名或模块名别用业务别名。我甚至见过一个同事把UserService写成用户服务结果整个校验全错位了。第三个是关系描述要明确上下文。一句“订单服务依赖库存服务”在不同语境下可能是Feign调用也可能是消息队列订阅。archify提取的代码信息里这两种依赖关系是不同的。所以我在prompt里会明确写“通过OpenFeign同步调用”或“通过RocketMQ异步订阅”这样比对的时候分的清清楚楚。5.2 多轮迭代不是循环越多越好archify支持自动迭代但我不建议无限循环。我实测下来三轮迭代之内解决不了的问题再来十轮也大概率解决不了。原因很简单每次迭代的反馈信息是有限的AI本身的能力天花板也就那样多跑几轮只是在同样的错误里打转。我现在的策略是最多迭代三轮第三轮仍不合格就停下来人肉介入。要么补充prompt背景知识要么手动改图。记住这个工具的目标是帮你省时间不是让它变成一个新的时间黑洞。5.3 验收报告怎么用才有价值archify生成的验收报告不只是一张“对/不对”的判决书它里面包含的信息非常丰富——缺失的类、冗余的节点、方向相反的关系、外部未解析依赖这些其实都是很好的架构评审输入。我现在的做法是让每个服务owner每周看一次自己服务的archify报告重点关注“AI脑补元素”和“外部依赖未解析”这两类内容。前者说明AI生成时的幻觉程度如果持续出现高比例的脑补说明prompt或者项目的模块划分可能有问题后者往往是文档盲区比如某个服务到底依赖了多少外部系统很多开发其实自己都不完全清楚。5.4 性能与项目规模注意这几点用在大规模项目上有几个性能点需要留个心眼。我第一次用在一个中大型项目上代码量大概80万行模块200多个直接跑校验时内存占用到了将近8GB跑完耗时小十分钟。后来发现可以配置增量分析模式只分析最近变更的模块效率提升非常明显。另外archify在分析时会生成一些中间文件包括提取出来的架构模型、校验快照这些会占用磁盘空间。如果你在CI里频繁跑建议定期清理缓存不然积少成多也是几个GB。最后提一句archify支持的IDEA插件我已经用上了效果比命令行舒服不少。写完代码直接在IDE里就能看到当前架构图和实际代码的差异提示相当于把验收流水线从“事后跑一次”变成了“边写边看”。如果你日常用IntelliJ系列开发这个插件值得一试。