无文档遗留系统逆向梳理：静态扫描+动态观测+AI辅助生成架构视图

接手一套跑了好多年的老系统，代码几百万行，文档约等于零，唯一“可靠”的说明就是运维群里流传的口头禅——“这块别动，动了就挂”。这时候如果老板突然让你梳理架构、画张图出来，给审计看，给新人讲，给重构铺路，怎么办？我经历过不止一次这种场面。实话说，靠人肉一行行读代码，别说几百万行，几十万行就能把人看废。我的做法是，把“逆向梳理”这件事拆成一条流水线：静态扫描搭骨架，动态观测找真身，最后用AI把那些藏在代码里的隐晦逻辑翻译成能看懂的文字和视图。这篇文章就完整聊聊这套方法怎么落地。

这套做法适合谁？如果你是刚接手遗留系统的开发者、需要做技术尽调或系统评估的架构师、想给老项目补文档的技术负责人，或者单纯被“无文档”三个字折磨得头疼的人，本文可以给你一条能直接上手的路径。我会把每一步怎么操作、工具怎么选、AI在哪个环节真正有用、哪些坑我替你先踩过，一次性说清楚。

1. 逆向梳理的整体思路与方案选型

先明确一个认知：无文档遗留系统的痛点，从来不是“没有文档”本身，而是“系统现状与任何人脑中的模型都不一致”。有的人知道某几个模块的内部细节，有的人知道部署结构，但没有人掌握完整的、准确的架构全貌。逆向梳理的目标，就是把这颗“散落的珍珠”串成一条清晰的线条，最终产出你需要的架构视图。

1.1 为什么不能直接人肉读代码

很多人接到这类任务的第一反应，是打开代码仓库开始从头读。我的经验是，这条路基本走不通。原因有三：

第一，体量问题。业务系统动辄几十万行起步，加上历史遗留的重复代码、死代码、注释与实现严重不符的模块，靠人眼过滤信息的效率极低。你花两周读完一个核心模块，很可能发现它已经是过时逻辑，真正的流量早走了另一条分支。

第二，依赖问题。现代系统几乎不可能完全自包含，外部服务、消息队列、定时任务、共享数据库都是架构的一部分。代码仓库里看不到的东西，往往才是运行时的真实依赖。只读代码不观运行，画出来的图是“纸面架构”，不是“真实架构”。

第三，信任问题。代码本身不会说谎，但它会过时。一段注释写着“这里兼容某旧接口”，实际可能早已无人调用。人肉阅读时，很难区分哪些是历史包袱、哪些是当前主干，容易把噪声当信号。

所以，我建议的路径是三层叠加：静态扫描建立代码拓扑，动态观测确认运行时真相，AI辅助完成语义理解和视图生成。三者不是替代关系，而是互相校验。

1.2 方案选型：三层各司其职

这套流水线里，每一层都有明确分工：

• 静态扫描负责“全量覆盖”。它能把所有源码文件、模块依赖、接口定义通通扫一遍，生成客观的代码结构拓扑。这是人力做不到的，也是后续分析的基础。
• 动态观测负责“确认真相”。通过日志、调用链、接口监控、数据库访问记录，搞清楚哪些代码在真实运行、模块间实际调用关系是什么。静态看到“可能”，动态确认“一定”。
• AI负责“语义翻译”。静态和动态工具能告诉我们“类A调用了类B”，但很难告诉我们“这个调用是为了实现账期自动对账”。AI擅长从代码片段和调用关系中推断业务意图，把技术事实翻译成业务语言。

选型顺序很重要。我习惯先做静态扫描和动态观测，把机器能干的粗活先干完，拿到结构化事实清单之后，再上AI做理解和视图生成。反过来，如果一开始就让AI直接读整个项目，它会被海量无关代码淹没，输出质量会大打折扣。

提示：如果你所在团队已经有代码规范与持续集成的记录，可以把CI流水线里的构建日志、测试报告也纳入动态观测的素材来源。这些日志能反映构建期依赖与测试覆盖范围，对理解模块边界很有帮助。

2. 核心细节解析与实操要点

方案定了，接下来就是具体干活。这一节把三层里每个环节的关键操作拆开，重点说明我踩过的坑和验证过的有效手段。

2.1 静态扫描：搭建代码拓扑的技术细节

静态扫描工具的选择可以结合团队已有的技术栈。我只说通用的原则：优先选能输出可计算结构化数据的工具，比如JSON、XML或SQLite格式的扫描结果，而不是只输出图形或PDF。因为后续AI梳理时，我们需要把结构化数据作为上下文直接灌进去。

实操上，我会分三步走：

第一步，扫依赖。先把构建文件解析掉，整理出一个完整的依赖清单，包括直接依赖和传递依赖。这类信息能帮你快速判断系统用了哪些重量级组件、是否存在版本冲突、有没有已经无人维护的老旧库。依赖清单也是画部署视图的基础。

第二步，扫模块与调用关系。这一步产出项目内部的包结构、类依赖和函数调用关系。很多工具能生成调用图，但我更关注的是“按业务模块聚类的依赖矩阵”，即模块A依赖模块B的哪些接口、有没有循环依赖、分层是否清晰。这个矩阵是后续画架构图的骨架。

第三步，扫接口与配置。把所有对外暴露的接口（HTTP API、消息消费者、定时任务入口、RPC服务）全部提取出来，和配置文件、路由定义逐一对应。这批信息决定了系统的“对外边界”，是架构视图里最容易被忽略却最关键的图层。

静态扫描执行时，有几个细节值得多说两句：

• 如果项目是多仓库结构，不要只扫主仓库，要把所有仓库统一纳入扫描范围，然后按“目录前缀”或“服务名”做归类合并。否则你画出来的依赖图天然缺失。
• 扫描结果要先过滤测试代码。测试目录会引入大量与生产逻辑无关的依赖和调用关系，不排除的话会让模块依赖图失真。
• 不要只看最新的分支。如果可能，把最近几个发布标签也扫一遍，对比依赖和模块边界的变化，能帮你快速识别哪些模块近年一直在演进、哪些已经停滞。演进中的模块往往就是当前架构的核心主干。

2.2 动态观测：确认运行时真相的几种手段

静态扫描解决的是“代码里有什么”，动态观测解决的是“系统里到底跑什么”。两者缺一不可。

我常用的手段有四种，大家可以按投入成本从低到高选用：

第一种，日志分析。把生产环境的访问日志、应用日志、错误日志集中起来，按接口、服务、用户端做聚合统计。日志里的真实流量分布能直接告诉你：哪些接口是高频核心、哪些模块根本没什么人用。后端日志和网关日志配对，还能还原出一条完整的用户请求链路。

第二种，链路追踪。如果系统已经接入了APM工具，直接拿调用链数据和依赖拓扑图。没有接也没关系，往往可以在网关层临时加一层访问日志中间件，把请求路径和耗时记录下来，再靠时间戳和调用关系拼出链路。这个方法侵入性小，效果也比较直接。

第三种，数据库与中间件观测。分析数据库慢查询日志、连接池状态、消息队列积压量，能反推系统的数据流向和模块间的异步依赖。比如某个定时任务每天凌晨批量把数据从库A同步到库B，静态扫描里可能只是一个不起眼的类，但动态观测能发现它其实是系统里最重要的数据管道之一。

第四种，部署与配置盘点。把各个环境（测试、预发、生产）的部署拓扑、配置中心、环境变量、域名与路由规则全部整理成表单。这个信息直接影响你最终画出的“物理架构视图”——哪些服务部署在哪台机器、依赖哪些外部系统、通过什么协议通信，都要在这里面找答案。

动态观测阶段，我有一条很深的体会：先跟着请求走一遍，再跟着数据走一遍。跟着请求走，能知道用户流量打通了哪些模块；跟着数据走，能知道最终落库和对外输出的链路是什么样的。这两条线交叉，基本就能还原出运行时的真实骨架。

2.3 AI在逆向梳理中的角色定位

AI不是魔法，它没办法替你从零读懂一个几百万行的项目。但它在三个环节能发挥人力无法替代的作用：一是代码语义理解，二是架构信息抽取与结构化，三是视图描述生成。

AI最有效的工作方式，是“分段投喂+精准提问”。先把大型代码库拆解成功能内聚的模块单元，比如一个限流组件、一个账务核心类、一个消息处理队列。然后按“核心入口类+关键方法+配置项+调用关系”组成一个上下文包，丢给AI分析。提问时目标要非常具体，比如：“这段代码的核心职责是什么？它对外提供了哪些关键能力？它依赖了哪些外部组件？它可能的扩展点在哪里？”

这里有一个非常关键的操作细节：投喂前先用AST解析工具把代码块裁剪过。把无关的import、工具函数、日志代码、注释噪音去掉，只保留核心逻辑骨架，AI的注意力会更集中，输出质量会高出好几个档次。我没试过直接扔几千行原始代码给AI，那样出来的结果往往泛泛而谈，缺少针对性。

AI输出的内容，不管是文字描述还是Mermaid格式的架构图描述，都要被当作初稿而非成品。我把它当作一个高效的“信息整理员”：它能快速把事实清单重组成有逻辑的叙述，把代码语言翻译成业务语言。但它是否准确，必须靠人去验证。后面第3节我会讲怎么搭建一套人机协同的校验流程。

注意：AI分析代码时的上下文窗口有限，哪怕几千行的单文件，全部塞进去也会稀释重点。务必裁剪、分段、聚焦。我的经验是每个上下文包控制在500~2000行核心代码以内，配上对应的配置信息和调用关系说明，效果最好。

3. 实操过程与核心环节实现

理论说完了，这一节按照实操顺序，逐步记录我从零搭建这套流程的完整环节，方便你直接照做。

3.1 第一步：搭建事实基线——先让项目跑起来并摸清家底

拿到一个陌生项目，我做的第一件事永远不是读代码，而是想办法把它在本地或测试环境跑起来。跑不起来的话，所有的静态分析都像是空中楼阁。

如果项目能正常启动，就顺着启动日志、健康检查接口、配置中心拉一遍配置，把关键的端口、中间件地址、依赖的外部服务记录下来。这一步听起来基础，但实操中我发现，很多所谓“无文档系统”其实是有隐性文档的：启动类的注释、Makefile、Dockerfile、启动脚本里的变量名、README里只言片语的架构图，都是金矿。先扎扎实实把这些“碎片文档”收集起来，建立初步认知。

如果项目跑不起来（这在新接手的遗留系统里太常见了），也不要灰心。那就以构建日志为基线，先把编译错误列表当成第一份“体检报告”，分析哪些代码已经严重过期、哪些模块大概率是死代码。这类信息本身对架构判断同样有价值。

在这一个环节结束时，你应该已经拿到三样东西：一份完整的服务/模块清单、一份依赖清单、一份已有的配置与部署信息。这三个清单拼起来，就构成了整个逆向梳理的“事实基线”。

3.2 第二步：静态扫描生成代码地图，把模块边界画出来

有了事实基线，接下来就是重头戏。我用某个静态分析工具扫全仓库，导出JSON格式的模块依赖数据。接着我会花不少时间做数据清洗：

• 去掉测试代码和生成代码的节点；
• 把纯工具类、常量类、DTO类标记出来，不纳入模块依赖主图；
• 按团队既有的包名或命名空间，将类级节点聚合成模块级节点；
• 计算模块间的依赖次数和依赖方向，把权重标注在边上。

清洗完成后，我会做一次“依赖矩阵”检查，重点看三件事：

第一，有没有环状依赖。比如支付模块依赖订单模块，订单模块又反向依赖支付模块，这种循环会让系统在后续演进时越来越难改。

第二，有没有超级大杂烩模块。比如某个common包被几乎全部模块依赖，那它到底是基础工具包还是藏了一堆业务逻辑？如果是后者，架构视图里要单独把它标记成风险点。

第三，有没有孤岛模块。有些模块在静态依赖图上谁都不依赖、也没人依赖它，基本可以判定为死代码或边缘模块。这些信息在后续和业务对焦、做架构瘦身时都很有用。

这一步产出的“代码地图”，是从源码视角完成的第一个完整架构视图初稿。它不一定等于真实运行架构，但它提供了客观的骨架，后续的动态观测和AI分析都在这张图上叠加信息。

3.3 第三步：动态观测校准真实链路，识别运行时依赖

静态地图不够，我会用一套脚本去抓实时或历史的运行时数据。来源包括：网关访问日志、应用性能监控的调用链数据、数据库连接池监控和慢查询日志。

操作上，我会设置一个统计周期，比如最近7天的日志，按小时粒度做聚合。重点关注几个指标：

• 接口维度的调用量Top20：这些是系统的核心流量入口；
• 模块间跨服务调用次数：这个数据能直接修正静态依赖图里的权重——有的模块静态看依赖关系很重，实际流量可能完全没走；
• 异步链路和定时任务触发记录：这些往往在静态代码里埋得很深，但对架构视图还原极其重要；
• 数据库表与接口的对应关系：从慢查询日志或ORM映射文件反推哪些接口到底在访问哪些数据表。

动态观测做完后，我会把结果和代码地图做交叉比对，做出一张“代码地图与运行时链路差异表”。我曾经在两个不同项目里都发现过同一个有趣现象：代码里有个模块看起来庞大且陈旧，但动态数据显示它根本不在任何主链路上——只有历史遗留的定时任务还在调它。这种“僵尸模块”如果只靠静态扫描，很容易被误判成核心模块。

差异表绘制完毕，真实架构的轮廓就已经浮现出来了：核心入口、核心服务、数据存储、外部依赖、异步任务、僵尸模块，每一个都在这个阶段有了明确定位。

3.4 第四步：用AI分段投喂代码，提炼模块语义并生成架构视图描述

现在进入AI发挥价值的核心环节。在拿到前三步的结构化事实的基础上，我会把项目按模块切片，每个模块附上三样东西：该模块的入口类与核心方法摘要、该模块在代码地图上的上下游依赖、该模块在动态观测中的真实调用数据。然后开始投喂AI。

举一个我常用的Prompt模板，结构如下：

我现在要理解一个遗留系统中的模块语义。请基于以下信息，帮我梳理这个模块的业务职责和关键交互： 【模块名称】账务结算模块 【核心代码片段】（这里贴入经过AST裁剪的核心类与关键方法，控制在几百行以内） 【依赖关系】该模块上游依赖订单模块、用户模块；下游被对账任务和结算通知任务调用 【运行时数据】该模块每日处理约50万笔结算请求，主要在每日凌晨2点-4点的定时任务中执行 请回答： 1. 这个模块在系统中的核心职责是什么？用不超过200字描述。 2. 它对外提供的关键功能和接口有哪些？ 3. 它依赖的外部组件（数据库表、消息队列、第三方服务）有哪些？ 4. 根据代码中的注释和逻辑推断，有哪些业务规则或状态流转是核心的？ 5. 这个模块有没有明显的代码坏味道或历史包袱？

这个模板的好处在于，它要求AI把所有输出都锚定在“模块职责、对外接口、外部依赖、业务规则、风险点”这五个维度，不会天马行空。我实际用下来的感受，AI对这类聚焦问题的分析质量相当高，尤其是识别代码中的业务规则和状态机流转，比我人肉去翻强得多。

等所有模块的语义分析都出来，我让AI把所有模块按依赖关系和业务内聚度聚类，生成一份“候选架构分层方案”，再让它按这套分层方案输出架构视图的描述文本，包括模块划分、核心依赖关系、数据流向、对外接口。有些AI工具能直接输出图表描述语言，我会拿这个描述作为初稿，再手工调整布局和重点标注。

这里有个心得体会要分享：AI产出的架构分层方案不一定符合团队既有认知，但往往很有参考价值。它不受任何历史包袱影响，纯粹从代码结构和运行事实推断“这套系统实际上是怎么组织的”，这恰恰是遗留系统最需要的外部视角。你可以不同意它，但它的分析视角能帮你看到盲区。

3.5 第五步：人工校验与架构视图成稿，建立可复用文档

AI生成的架构视图初稿，必须经过两轮校验才能成为正式交付物。

第一轮校验是“代码事实校验”。对照静态扫描数据和动态观测记录，逐个核对AI描述中的模块关系是否真实存在。这一步我会建立一个“架构视图问题清单”，把AI可能产生的幻觉、过度推断、遗漏节点全部列出来，然后逐条去代码或者监控数据里找证据。只有找到实证的条目，才能从问题清单转成正式视图的一部分。

第二轮校验是“在岗人员访谈”。找两三位对这个系统最熟悉的后端开发者或运维老手，让他们对照AI生成的架构视图初稿，指出哪里不对、哪里漏了、哪里名不副实。这些老手的经验判断力无可替代，他们往往能在几分钟内指出AI花几小时也发现不了的隐性依赖和业务特例。这一步同时也是对我们梳理成果的实战检验。

两轮校验结束，我才会整理最终的交付物。交付物一般包括：一张完整的分层架构图、一张部署物理视图、一份模块职责说明表、一份核心业务流程时序说明。这些文档沉淀下来后，不只是交差用的“作业”，更是后续任何架构演进、容量评估、人员培训的基础资料。

提示：这个环节里最有价值的动作是把“校验记录”本身保留下来，即什么结论是从代码里来的、什么结论是访谈来的、什么结论没有得到验证。这份校验记录是文档可信度的核心凭证，比最终架构图本身更能赢得团队信任。

4. 工具选型解析与AI能力边界

这套流程涉及到的工具非常多，我不逐一推荐具体产品，只把选型原则和适用场景说清楚，你可以按实际情况组合。

4.1 静态扫描工具怎么选，结果怎么用

静态扫描工具选择，核心看三点：语言覆盖度、数据导出格式、调用图质量。

如果项目是多语言混合架构，优先选支持多种语言的方案；如果项目是单一语言，直接用对应语言社区里最成熟的那套即可。数据导出格式，JSON比图片重要得多，结构化数据才能喂给AI。调用图质量要看它能否准确识别动态分发、反射调用、接口实现类绑定，这直接影响后续依赖矩阵的真实度。

一个往前踩过的坑值得说：很多静态分析工具默认只分析编译单元内的调用关系，对跨进程调用（HTTP、RPC、消息队列）完全无感。所以静态扫描产出的依赖矩阵，必须结合第2.2节的动态观测才能补全跨模块的真实调用。

4.2 动态观测工具与日志分析实操组合

动态观测的选型，取决于你已经有什么。如果系统已经有APM链路追踪，直接导数据就好；如果没有，也不建议为了梳理一次架构去引入整套重型APM体系。更务实的做法是直接分析已有的访问日志和应用日志，写简单的脚本做聚合统计。只要日志保留了接口路径、上游IP、耗时、状态码这些基础字段，就能解决80%的运行时梳理问题。

日志分析有几个细节：时间字段统一转成标准时区；对上游调用方做好归类映射；慢查询日志要和接口日志按“时间窗口+数据表”做关联，判断每个核心接口背后的真实数据访问模式。这一步不需要复杂平台，一套脚本就能跑出价值。

4.3 AI梳理时的上下文工程与幻觉问题应对

AI在逆向梳理里的上限，取决于你给它看的上下文质量。我不是直接把整个仓库喂进去，而是按“事实清单+裁剪代码+定向提问”三层结构来组织。事实清单是关键中的关键，它是AI理解项目背景的锚点。

关于AI幻觉，我的经验是：只要你问它“这段代码里有什么”，它基本准确；只要你问它“这段代码之外可能有什么”，它就开始自由发挥。所以，所有提示词都要锚定在代码事实和运行数据上，凡是问卷涉及“模块外部依赖”“是否被其他模块调用”这类开放性问题，我只会把AI分析当作候选线索，绝不会直接采信，必须回头用代码检索或数据观测验证。

让我用表格把这个边界画得更清楚：

有了这个边界认知，AI在整个流程里的定位就非常清楚了：它是高效的信息压缩器和初稿生成器，而不是最终的架构真相来源。

5. 常见问题与排查技巧实录

做逆向梳理，踩坑是必然的。我把几个真实项目里反复出现的高频问题整理成速查表，附带我的排查思路和避坑技巧。

5.1 识别假线索，防止被带入歧途

第一种常见假线索来自注释。大家写代码时都有过“注释比代码乐观”的时候。注释里写着“该接口已废弃，请使用新接口”，结果一查调用链，旧接口还在高峰期扛着业务。我的处理习惯是：所有注释里的声明，都当作提示而非事实，只有通过代码检索和日志确认过，才算数。

第二种假线索来自类名。有些类名沿用多年，业务早就变了，比如有个名为“用户同步任务”的类，实际早已演化为跨系统的数据分发中心。AI梳理时极其容易轻信类名并产生错误推断。我会在投喂前明确告诉AI：类名和包名只作为参考，必须以代码内部的逻辑和外部调用为准。

第三种假线索来自“假依赖”。有些项目里存在大量“为了保险”而注入但从未使用的服务对象，这些依赖会污染依赖矩阵。处理办法是在静态扫描结果里增加“未使用注入”检测，把这类依赖排除出主图，单独归入“清理候选清单”。

5.2 如何应对体量庞大的“三无”系统（无文档、无测试、无人懂）

这是最困难的一种情况。如果一套系统同时满足这三个条件，直接硬啃大概率会失败。我的经验是改变目标：第一轮逆向梳理的目标不是搞懂一切，而是划出一个可探索的安全边界。

做法分四步：

• 先把部署拓扑弄出来，搞清楚这套系统由哪些运行时组件构成；
• 再通过日志流量，把请求入口和核心出口识别出来；
• 然后单独挑出流量最大的那条链路做一次深度梳理，产出完整的调用链说明；
• 最后把其他模块按“未探索区域”在架构图上打阴影标记，明确说明其状态。

这套“先探索核心链路，阴影标记未知区域”的做法，在“三无”系统上特别实用。它让文档在第一天就能交付，同时诚实地区分了“已验证事实”和“待补充区域”，给后续工作留出了迭代空间。

5.3 复杂依赖关系手工校验的无奈之处

无论AI多强，最终架构图的准确性还是取决于人的判断。AI能生成视图初稿，能提出分层假设，但它无法替代这样一个过程：一个熟悉业务的人，站在代码地图和流量证据面前，说一句“这块不是这样走的，它是我负责的那个老定时任务”。

所以我把“在岗人员访谈”当作标配流程，而且放在AI产出之后、成稿之前。如果你所在的团队连一个熟悉系统的人都找不到，那只能靠加大动态观测力度来补位。比如拉长日志观察周期到30天、把数据库慢查询和任务调度记录全部关联起来、利用系统自身的健康检查做主动探测。机器能提供的证据越充分，对人的依赖就越低。

6. 后续扩展：从架构视图到架构治理

架构视图重建完之后，我可以很负责任地说：这只是一个新起点。很多人做完架构图就归档了，我觉得挺可惜。这份视图的价值远远不止“交差”，它完全可以转化为系统治理的长效工具。

比如，你可以把架构视图中的模块清单和依赖关系反向输出成一份“架构健康度体检清单”：哪些模块有循环依赖要拆、哪些模块是僵尸代码要清、哪些接口的流量已经明显失衡。把这些丢给开发团队，作为技术债清理的候选队列，后续的每一次重构都可以和这份视图比照，看到底有没有往目标架构靠近。

更实用的做法是，把梳理过程中沉淀的代码地图数据接入到CI流水线里。每次构建后自动生成增量架构变更摘要，提交到代码评审流程中。团队每次改动如果都能看到“本次变更会影响哪些模块的上游和下游”，回归测试名单和评审重点就可以动态生成，这个价值是实打实的。

我自己的经验里还有一类很值得做：把交付出出来的架构视图做成新人入职培训的第一课。让新人对系统先建立一张清晰的“地图”再上路，比让他们在几百万行代码里自己摸爬滚打效率高太多了。

关于这个过程，我只想真诚地说一句：做无文档系统的逆向梳理，最大的挑战不是技术工具不够强大，而是信息噪声太多。AI在这个过程中扮演的角色非常微妙——它可以帮助你过滤噪声、找到脉络，但你得有足够的判断力去质疑它。把机器能算的算清楚，把AI能理解的吃透，把人的经验用足，这套组合拳地打下来，你收获的不止是一张架构图，而是对系统真正的掌控感。