企业官网建设流程全解析

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 Boot（Java/Kotlin）、Go、Python（FastAPI/Django）、Node.js（Express/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-2：PaymentCallbackHandler实际通过RocketMQ消费消息，并非通过OpenFeign调用，图中依赖方向错误。
• P0-3：代码中InventoryService通过InventoryDeductFacade对外提供接口，但图中直接标注为InventoryService，名称不一致。
• P1-1～P1-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 同步调用。数据层仅包括 MySQL（order_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系列开发，这个插件值得一试。