1. 当AI开始画架构图我们到底在信什么前阵子团队里来了个新同学第一次参加系统评审就甩出一张AI生成的微服务架构图节点齐全、连线漂亮、分层清晰会议室里安静了三秒然后有人问了一句“这个调用关系你从哪段代码里看出来的”他愣了一下说“AI根据项目描述推的”。那一刻我就知道这张图再好看也只是一张“看起来像架构图”的图。这两年AI生成架构图这件事热度是真的高。你把一段需求描述丢进去或者把几个模块名贴进去几秒钟就能吐出一张系统架构图、微服务架构图甚至还能给你配上数据流向。工具层面从架构图软件自带的AI能力到通用大模型直接出图再到各种“架构图 skill”插件门槛低到几乎为零。但问题也随之而来AI生成的架构图可信吗这个问题不是抬杠而是每一个要拿这张图去做评审、做交接、做技术决策的人都必须先回答的问题。我自己在几个项目里反复试过这条路让AI根据源码生成架构图、根据接口文档生成数据契约、根据模块依赖生成Birdview。踩过的坑不少也慢慢摸出了一套校验边界。这篇就围绕三个核心概念展开——源码证据、数据契约、Birdview讲清楚AI画的图哪些部分可以信哪些部分必须人工兜底以及怎么用一套可复现的流程把“AI幻觉”挡在架构决策之外。适合正在用AI辅助架构梳理的开发和架构师也适合刚接触这块、想知道边界在哪的同学。2. 先搞清楚AI画架构图的三种输入姿势2.1 从自然语言描述生成最省事也最不可信这是大多数人第一次接触AI架构图的方式。你写一段话比如“这是一个电商系统包含用户服务、订单服务、支付服务、库存服务通过消息队列异步通信”AI就给你画出来。快是真快但这里有个根本问题AI画的是你描述里的架构不是你系统里真实存在的架构。我做过一个对比实验。同一个项目我分别用“需求文档描述”和“真实源码依赖”作为输入让AI生成架构图。结果两张图在服务数量上差不多但调用关系差了将近40%。描述里写的“订单服务调用库存服务”实际代码里是订单服务发消息到MQ库存服务消费中间还隔了一层事件总线。AI不知道这个细节它只会按最符合常识的方式连线。所以这种姿势的定位很明确用于早期方案讨论和草图沟通不能作为架构事实的依据。你可以拿它来快速对齐“我们大概要做哪几块”但一旦进入详细设计或者交接文档必须换输入源。2.2 从源码依赖生成有证据但证据有噪声这是目前相对靠谱的一条路。思路是让AI读取代码里的import关系、注解、配置文件推导出模块之间的依赖再渲染成架构图。很多“架构图 skill”和IDE插件走的就是这条路比如在PyCharm里装个AI插件它能根据项目结构给你画一张模块依赖图。它的优势在于每个连线背后都能追溯到具体的代码位置这就是所谓的“源码证据”。但噪声也在这里代码里的依赖不等于架构上的依赖。举几个我实际遇到的例子一个工具类被十几个模块importAI会画出一堆指向它的箭头但架构上它只是个公共库不该出现在业务架构图的主视图里。通过反射或者字符串拼接调用的关系静态分析根本抓不到AI会漏掉。循环依赖在代码里可能存在但架构上是要消除的AI会如实画出来反而误导。所以源码证据的价值不是“直接出图”而是“提供可核对的线索”。你得把AI的输出当成一份待验证的依赖清单而不是最终架构图。2.3 从数据契约生成最容易被忽略却最关键数据契约这个词很多人第一反应是API文档或者数据库表结构。但在架构图语境下它指的是服务之间交换的数据结构、字段含义、版本约定。为什么它关键因为架构图里最容易画错的就是“谁给谁传了什么”。我见过一张AI生成的微服务架构图服务划分没问题调用方向也没问题但数据流向全错了——它把“订单创建事件”画成了订单服务直接同步调用库存服务扣减。实际上两者之间是异步的而且传递的是一个包含订单号、商品列表、时间戳的复合事件对象。这个错误如果没被发现拿去给新人做交接后果可想而知。数据契约作为输入的价值在于它能约束AI对“调用语义”的猜测。当你把接口定义、消息schema、事件结构一起喂给AI时它推导出的数据流向会靠谱很多。这也是我后来固定下来的做法源码依赖 数据契约两个输入一起给缺一不可。3. 源码证据到底能证明什么不能证明什么3.1 能证明的静态依赖、模块边界、调用方向先说能证明的部分这块是AI的强项也是它比人快的地方。静态依赖是最直接的。A模块import了B模块这个事实是确定的AI抓取准确率很高。基于这个它能推导出模块之间的编译期依赖关系进而画出分层结构。我实测下来对于一个中等规模的Java项目AI从import关系推导出的模块依赖图和人工梳理的结果重合度能到85%以上。模块边界也能推个大概。通过包结构、命名空间、目录层级AI能识别出哪些代码属于同一个逻辑模块。比如com.xxx.order下面全是订单相关它就会归为一类。这个能力在项目结构规范的前提下很好用。调用方向在同步调用场景下比较准。方法A里调用了方法B静态分析能抓到AI据此画出A指向B的箭头。对于RPC框架如果注解和接口定义清晰也能识别。但注意我说的都是“静态”和“同步”场景。一旦涉及运行时行为AI的证据链就断了。3.2 不能证明的运行时调用、异步链路、动态路由这部分是坑最多的地方我一个个说。运行时调用代码里写了if (condition) serviceA.call()静态分析只能看到“可能调用”但实际跑起来走不走这条路AI不知道。我遇到过AI把一堆条件分支里的调用全画成实线箭头图看起来密不透风实际上大部分路径在正常流程里根本不触发。异步链路这是重灾区。消息队列、事件总线、定时任务这些在代码里往往是通过字符串topic或者配置项关联的静态分析很难串起来。AI要么漏画要么按“最可能的顺序”瞎连。我见过最离谱的一张图把Kafka的producer和consumer画成了直接调用中间的消息中间件完全消失。动态路由网关、服务发现、负载均衡这些代码里通常只有配置没有硬编码的调用关系。AI读不到运行时的路由表画出来的就是理想化的“A调用B”实际可能是“A调用网关网关按规则转发到B或C”。提示判断一张AI架构图能不能用先看它有没有区分“静态依赖”和“运行时调用”。如果两者混在一张图里且没有标注基本可以直接打回。3.3 一个实用的证据分级方法踩了几次坑之后我给自己定了一套证据分级用来判断AI给出的每条连线可信度有多高证据等级来源可信度处理方式A级接口定义、消息schema、配置文件中的显式声明高可直接采用标注来源B级源码import、方法调用、注解中需人工确认语义C级AI根据命名和常识推断低必须人工验证或删除D级无来源AI“脑补”极低直接删除这套分级我后来固化成了一个检查清单每次AI出图后逐条过一遍。A级和B级保留C级标记待确认D级直接删。实测下来一张AI生成的图里D级连线能占到20%到30%删完之后图才勉强能看。4. 数据契约给AI的架构推理上一道锁4.1 为什么数据契约比调用关系更重要很多人梳理架构时盯着“谁调用谁”但真正决定系统耦合度的是“谁依赖谁的数据结构”。调用关系可以改数据结构一改就是连锁反应。AI在生成架构图时如果只看到调用关系它会按“最合理”的方式组织数据流而这个“合理”往往是错的。举个我亲身经历的例子。一个订单系统和风控系统之间代码里是订单服务调用风控服务的接口。AI据此画了一条“订单 - 风控”的同步调用线。但实际上这个接口传的是一个包含订单全量信息的DTO风控系统拿到之后会做异步分析结果通过另一个通道回写。如果只看调用关系你会以为风控是同步阻塞的看了数据契约才知道它是异步的、有状态的。所以我的做法是把接口的请求和响应结构、消息的payload schema、数据库的关键表结构一起作为输入给AI。这样它推导数据流向时有实际的字段作为锚点而不是靠猜。4.2 怎么整理一份AI能读懂的数据契约数据契约不是把整个数据库DDL丢给AI就完事那样噪声太大。我一般整理成三个部分第一部分是服务间接口清单。每个接口列出调用方、被调用方、接口名、请求字段、响应字段、同步还是异步。这个清单不用很细但字段名和类型要有。第二部分是消息契约。所有通过消息队列传递的事件列出topic、生产者、消费者、消息体结构。这块最容易漏但恰恰是架构图里数据流向的关键。第三部分是核心数据实体。比如订单、用户、商品这些跨服务共享的实体列出它们的归属服务和关键字段。这能帮AI判断哪些数据是“主数据”哪些是“副本”。整理完之后我会把这份契约和源码依赖一起喂给AI并明确告诉它数据流向必须以契约为准调用关系以源码为准两者冲突时以契约为准。这个优先级设定很关键能挡掉很多AI的“合理推断”。4.3 契约缺失时怎么办标注不确定而不是让AI填空现实项目里数据契约往往是不完整的。老系统没文档新系统还没定稿这时候怎么办我的原则是宁可图上留白不让AI填空。具体做法是在给AI的输入里明确标注“以下部分契约缺失”并要求它在生成时用虚线或者问号标注不确定的数据流向。这样出来的图虽然不完美但至少你知道哪里需要人工补。我试过让AI“根据经验补全”缺失的契约结果它补出来的字段和实际差了十万八千里。后来我就学乖了缺失就是缺失图上标出来评审的时候大家一起补比AI瞎猜强得多。5. Birdview的校验边界全局视角下的可信度分层5.1 Birdview是什么为什么需要它Birdview我理解就是“鸟瞰图”——站在系统全局的高度看各个模块、服务、数据流之间的关系。它和普通的架构图的区别在于视角的高度和广度普通架构图可能只画一个子系统Birdview要画整个系统版图。为什么需要单独讨论Birdview的校验因为视角越高AI的推断越容易失真。在一个小模块内AI靠源码依赖能推得比较准但放到全局跨团队、跨技术栈、跨数据域的依赖源码证据往往覆盖不到AI就开始“合理想象”了。我做过一个实验同一个系统分别让AI生成“单服务详细架构图”和“全局Birdview”然后人工核对。详细图的准确率能到80%左右Birdview的准确率掉到了50%出头。差距主要出在跨系统的数据流和边界划分上。5.2 三层校验源码层、契约层、语义层基于这个观察我总结了一套Birdview的三层校验方法第一层是源码层校验。把Birdview里每条连线对应的源码证据找出来。找得到的标记为“有据”找不到的标记为“待查”。这一层能筛掉大部分AI脑补的连线。第二层是契约层校验。检查跨系统的数据流是否符合数据契约。比如Birdview里画了“订单系统 - 数据仓库”的数据流就要去契约里找对应的数据同步任务或者消息topic。找不到的要么是漏了契约要么是AI画错了。第三层是语义层校验。这一层最依赖人的判断。检查图的语义是否合理分层的依据是什么边界的划分是否符合团队结构数据流向是否符合业务逻辑这一层AI帮不上忙必须人工过。三层过完一张Birdview的可信度就清晰了源码层和契约层都过的可以直接用只过一层的标注待确认一层都不过的基本可以判定是AI幻觉。5.3 边界之外哪些东西AI永远画不对有些东西不管你怎么喂数据AI都画不对这是由它的能力边界决定的。我列几个我确认过的组织架构和团队边界。架构图上的服务边界往往和团队边界对齐康威定律但AI不知道你们团队怎么分的。它只能按代码结构画画出来的边界可能和实际团队职责完全不符。技术选型的权衡理由。为什么用消息队列而不是RPC为什么这个服务独立部署这些决策背后的权衡AI看不到也画不出来。图上的连线是结果不是原因。历史遗留和演进路径。系统里总有一些“不该存在但存在”的东西AI会如实画出来但不知道它是历史包袱。Birdview如果不标注这些新人看了会以为这是设计意图。非功能性约束。性能、安全、合规这些约束往往决定了架构的关键形状但它们在代码里是隐性的。AI画不出“这个服务必须独立因为要过等保”这种信息。所以我的结论是AI可以画Birdview的骨架但骨架之上的血肉——边界、理由、历史、约束——必须人工补。把AI的输出当成一张待注释的底图而不是最终交付物。6. 一套可复现的AI架构图校验流程6.1 准备阶段输入整理与优先级设定这套流程我用了大半年迭代了几版现在相对稳定。第一步是准备输入分三块源码依赖清单。用工具导出模块间的import关系和调用关系格式化成AI能读的列表。不用很细到模块级别就行。数据契约文档。按前面说的三部分整理接口清单、消息契约、核心实体。缺失的部分明确标注。校验规则说明。这是给AI的“系统提示”明确告诉它数据流向以契约为准调用关系以源码为准冲突时以契约为准不确定的用虚线标注。这三块准备好之后再让AI生成图。顺序很重要先给规则再给数据最后出图。我试过反过来先出图再补规则AI会固执地坚持它最初的推断改起来很费劲。6.2 生成阶段分步生成不要一步到位很多人喜欢一次性让AI生成完整架构图我不建议。我的做法是分三步第一步只生成模块清单和分层。让AI根据源码结构列出所有模块并给出分层建议。这一步先不画连线只确认“有哪些块”。第二步生成模块间的调用关系。基于源码依赖画出调用箭头并标注证据等级A/B/C/D。第三步叠加数据流向。基于数据契约在调用关系之上叠加数据流用不同线型区分同步和异步。分步的好处是每一步都可以单独校验出错了好定位。一步到位的话图出来了你都不知道从哪查起。6.3 校验阶段逐条过证据标注不确定生成完之后进入校验。我一般打印出来拿支笔逐条过每条连线问一句“证据在哪”。找不到证据的标红。每个模块边界问一句“和团队职责对得上吗”。对不上的标黄。每个数据流向问一句“契约里有吗”。没有的标问号。过完之后红黄问号三类分别处理红色删除或补证据黄色人工确认问号补契约或标注待定。这个过程很枯燥但这是AI架构图从“能看”到“能用”的必经之路。跳过这一步图就是自欺欺人。6.4 交付阶段图上标注可信度而不是假装完美最后交付的时候我不会把标注全删掉假装图很完美。相反我会在图上保留可信度标注实线A级证据可直接采用虚线B级证据已人工确认点线C级证据待确认问号契约缺失待补这样看图的人一眼就知道哪些地方可以信哪些地方要留个心眼。评审的时候也有的放矢不会在已经确认的地方浪费时间。提示交付物里附一份“证据索引”每条连线对应到具体的源码文件或契约条目。这样别人质疑的时候你能立刻翻出证据而不是说“AI画的”。7. 常见问题与排查技巧实录7.1 AI把工具类画成了核心服务怎么处理这是最高频的问题。项目里总有几个被到处import的工具类AI会把它画成中心节点一堆箭头指向它。排查思路看这个节点的入度。如果入度极高且来自各个不相关的模块基本可以判定是工具类。再去看它的代码如果全是静态方法、没有状态、没有外部依赖那就是工具类无疑。处理方式从主架构图里移除放到“公共依赖”的附注里。如果它确实承担了某些架构职责比如统一日志、统一鉴权那就提升为“基础设施层”而不是业务服务。我一般会在给AI的规则里提前说明“入度超过5且无状态的模块归类为工具库不进入业务架构主视图。”这样能挡掉大部分误画。7.2 异步链路被画成同步调用怎么发现和修正这个坑很隐蔽因为图看起来很正常。发现的方法是对照数据契约里的消息定义。如果契约里某个交互是“发消息”而图上画的是实线箭头那就是错了。修正的时候我会把异步链路单独抽出来画一张“事件流图”和“调用关系图”分开。两张图各司其职比混在一起清楚得多。另外排查的时候可以搜代码里的send、publish、emit、produce这些关键词看看哪些交互是异步的然后逐一核对图上的线型。7.3 Birdview里跨系统数据流对不上怎么办跨系统的数据流是Birdview最容易出错的地方。对不上的时候我按这个顺序查先查契约里有没有这条数据流的定义。没有的话可能是漏了契约也可能是AI画错了。再查代码里有没有对应的数据同步任务或者消息topic。有的话补契约没有的话删连线。最后查业务逻辑上这条数据流是否合理。如果业务上就不该有这条流那AI就是纯幻觉。查完之后如果确认是AI画错了我会在规则里补充一条约束防止下次再犯。比如“订单系统和数据仓库之间只有T1的批量同步没有实时流”写进规则里AI下次就不会画实时连线了。7.4 一张速查表AI架构图常见错误与对策常见错误典型表现排查方法对策工具类当核心服务中心节点入度极高查代码是否无状态移入公共依赖层异步画成同步消息交互画成实线对照消息契约拆分事件流图条件调用画成必然箭头密不透风查代码条件分支标注条件或删除跨系统流对不上Birdview连线无据查契约和同步任务补契约或删线边界与团队不符服务划分奇怪对照团队职责人工调整边界历史包袱未标注存在不合理模块查代码提交历史标注“遗留”这张表我贴在工位上每次校验的时候对着过一遍能省不少事。7.5 几个我踩过的坑和对应的经验坑一太信任AI的“常识”。早期我让AI根据模块名推断职责结果它把“account”模块当成了用户账户实际那是财务对账模块。经验模块职责必须从代码和文档里确认不能靠名字猜。坑二忽略了配置文件的证据。很多调用关系藏在配置文件里比如Spring的XML、YAML里的路由规则。AI如果只读Java代码会漏掉这些。经验把配置文件也纳入输入范围。坑三一次性喂太多数据。有次我把整个项目的代码和文档全丢给AI结果它抓不住重点画出来的图又乱又错。经验输入要精炼模块级依赖 核心契约就够了不要贪多。坑四没有版本管理。AI生成的图改了几版之后自己都忘了哪版对应哪个代码版本。经验每版图都标注对应的代码commit和契约版本方便追溯。8. 我个人在实际操作中的体会这套流程跑下来最大的感受是AI架构图的价值不在于“生成”而在于“校验”。它帮你快速拉出一张底图把显性的依赖关系可视化省掉了手工画图的时间。但真正决定这张图能不能用的是后面那套证据校验的功夫。我现在的工作流是AI出初稿我过证据团队评审补语义。三步下来一张Birdview从生成到可用大概半天时间。比纯手工快但也没快到“一键出图”那么夸张。那些宣称AI能直接生成可信架构图的说法我是不信的——至少在我经手的项目里没有一次是不校验就能用的。另外一点体会是数据契约的整理本身就是一次架构梳理。很多时候把接口和消息契约整理清楚的过程中就发现了架构上的问题比如循环依赖、职责不清、数据冗余。这些问题AI发现不了但整理契约的时候会自己冒出来。所以我现在把“整理契约”当成架构工作的常规动作而不是为了喂AI才做。最后分享一个小技巧让AI生成图的时候要求它同时输出一份“证据清单”每条连线对应到具体的源码位置或契约条目。这样校验的时候直接对着清单过效率高很多。如果AI给不出证据那这条线基本可以判定是幻觉直接删。这个方向后续还可以往“自动化校验”走比如写个脚本自动比对AI生成的连线和源码依赖把不一致的标出来。我试过一版能筛掉大部分低级错误但语义层面的校验还是得靠人。工具能帮的忙有限关键还是那套证据分级的思路——信什么不信什么边界在哪心里得有数。
