接手屎山代码时，我让 AI 把接口逻辑和业务语义自动填进了文档

Q: AI 分析调用链时遇到动态代理或反射调用怎么办？

这是实际使用中最常见的断链场景。如果代码里用 ApplicationContext.getBean() 或反射来调用，AI 无法静态追踪。我的处理方式是：在第一步建立项目地图时，专门要求 AI 列出所有使用反射和动态代理的位置，这些位置的接口分析改为人工补充调用链，其他部分仍由 AI 完成。

接手一个没有任何文档、只有几千行 Controller 的老项目，最头疼的不是代码看不懂，而是每个接口背后那层“为什么这么写”的业务含义根本无从追溯。我最近的做法是：直接把整个项目仓库交给 AI，让它按接口逐个分析调用链，自动生成一份带业务语义的接口文档。效果出奇地好——一个 37 个接口的支付回调模块，从零文档到完整可交付的接口说明，只用了不到 40 分钟。

这件事的核心不在于“AI 帮你读代码”，而在于你如何约束它的输出格式和分析路径，让它产出的不是泛泛的代码解释，而是直接能贴进 wiki 的正式文档。下面拆解我实际操作的完整流程。

第一步：建立项目级的上下文认知

AI 分析单个接口时最容易犯的错误是“就代码论代码”——看到一个 updateStatus 方法就写“更新状态”，但实际那是风控审核通过后的状态流转，业务含义完全不同。所以不能让 AI 一上来就钻到某个 Controller 文件里，必须先建立全局认知。

我的做法是先用一个 Prompt 让 AI 扫描整个项目结构，输出一份“项目地图”。具体要求它做三件事：

识别技术栈和分层结构（哪些目录是 Controller 层、Service 层、DAO 层）
列出所有配置文件并提取关键配置项（数据源、中间件、第三方服务）
从包名、类名前缀、注释中推断业务领域划分

实际用的 Prompt 大致是这样的：

你是一个资深 Java 后端工程师。请分析这个代码仓库的整体结构：

1. 列出项目使用的技术栈（框架、ORM、中间件等）
2. 描述分层结构和各层的职责
3. 识别出所有的业务模块，按包名或目录分组
4. 对每个模块，用一句话概括它大概负责什么业务
5. 找出所有外部接口定义（Controller 或 API 入口），列出它们的类名和所在路径

不要展开具体代码逻辑，先建立全局视图。

这一步产出的结果让我对整个项目有了清晰的骨架认知。比如我那个支付模块的项目，AI 识别出了 payment-callback、refund-process、settlement-batch 三个核心模块，还从 application.yml 里提取出了对接的三方支付渠道列表。这些信息在后续分析单个接口时会反复用到，我会把它们作为上下文传给下一轮的 AI。

第二步：逐接口分析调用链，而非只看入口代码

很多人让 AI 写接口文档时，只把 Controller 的方法体扔进去，得到的自然是一份“代码翻译”——把 Java 代码用中文复述一遍，没有任何业务价值。

我改进了做法：让 AI 沿着调用链往下追踪，一直追到数据库操作或外部 API 调用为止，然后从“数据从哪里来、经过什么处理、到哪里去”这个角度来描述接口逻辑。

具体操作时，我一次喂给 AI 3-5 个接口（太少效率低，太多分析质量下降），要求它按固定结构输出。Prompt 的核心约束：

请分析以下接口方法，追踪完整的调用链（一直追到 DAO 操作或外部 HTTP 调用）：

{粘贴 Controller 方法的完整代码，以及它调用的 Service 方法签名}

对于每个接口，按以下结构输出分析结果：

1. 接口路径和方法：从注解中提取
2. 入参说明：字段名、类型、是否必填、业务含义（不是代码含义）
3. 核心调用链：用缩进列表展示 A -> B -> C 的调用关系，每一步标注类名和方法名
4. 数据库操作：涉及哪些表、操作类型（INSERT/UPDATE/SELECT/DELETE）、关键字段
5. 外部调用：调用了哪些第三方接口或中间件
6. 业务逻辑摘要：用 3-5 句话描述这个接口在业务流程中的位置和作用
7. 异常和边界情况：代码里显式处理的异常、返回的特殊状态码

这里有个关键细节：“业务含义”和“代码含义”必须明确区分。比如入参里有个 status 字段，代码含义是“Integer 类型的状态值”，但业务含义应该是“1-待审核 2-审核通过 3-审核拒绝”。我会在 Prompt 里特别强调这一点，并且要求 AI 从枚举类、常量类或注释中寻找业务含义的线索，如果实在找不到，就标注“[需人工确认]”。

第三步：用多轮对话补全业务语义

调用链分析完成后，得到的是“技术视角”的接口说明——知道这个接口查了哪些表、调了哪些三方接口，但“为什么这么设计”“这个接口在前端什么操作时触发”这些业务语义仍然缺失。

这时候我不再让 AI 自己推断（推断准确率太低），而是采用“AI 提问、我回答”的方式。具体操作：

把上一步生成的调用链分析结果贴回对话，然后追加 Prompt：

基于上面的调用链分析，列出你需要我确认的业务问题，帮助完善文档中的业务语义描述。问题应该聚焦于：

- 这个接口的调用时机（用户做了什么操作、或哪个定时任务触发）
- 关键状态值的业务含义（不要代码枚举值，要业务方理解的语义）
- 与其他接口的前后调用关系（调用本接口前通常先调哪个、之后会调哪个）
- 特殊业务规则（比如金额限制、时间窗口、幂等处理的原因）

每个问题一行，尽量具体，不要问“这个接口是做什么的”这种笼统问题。

AI 列出的问题通常非常具体，比如“POST /payment/callback/alipay 接口中，notify_type 为 batch_trans 时，是否表示批量转账到多张银行卡的回调？还是其他含义？”这种问题我只需要用一两句话回答，然后让 AI 把答案整合进文档。

这一轮走完，文档的业务语义就丰满了。从“接收到支付宝回调后更新订单状态”变成了“用户在支付宝收银台完成支付后，支付宝以 POST 方式回调本接口通知支付结果；接口验签后根据 trade_status 判断支付是否成功，成功则流转订单状态为‘已支付’并触发发货流程，失败则记录异常日志并发送告警”。

第四步：生成正式文档并格式化输出

最后一步是让 AI 把分析结果整理成正式的接口文档格式。我习惯用 Markdown 表格形式，每个接口一个表格块，方便直接贴到 Confluence 或语雀。

Prompt 要求 AI 严格按照我指定的字段顺序输出，并且对每个字段有明确的填写规则：

将以上所有接口的分析结果整理为正式文档，使用以下格式。

每个接口一个二级标题（接口名称），然后是一个表格，表格的列依次为：

| 属性 | 说明 |
| 接口路径 | /api/xxx |
| 请求方式 | POST/GET/PUT/DELETE |
| 请求参数 | 表格嵌套，列出参数名、类型、必填、业务说明 |
| 响应参数 | 表格嵌套，列出字段名、类型、业务说明 |
| 业务描述 | 完整的业务流程描述，包含调用时机、前置条件、后置动作 |
| 错误码 | 列出该接口可能返回的所有错误码及说明 |

要求：
- 业务描述部分要包含具体的业务场景，不要只写技术操作
- 如果某个字段有枚举值，列出所有枚举值和对应的业务含义
- 错误码从代码中的异常处理和返回语句中提取

这里有个容易忽略的点：响应参数的字段要覆盖所有可能的返回场景。很多接口文档只写了正常返回的结构，但实际代码里 catch 块返回的错误结构完全不同。我会在 Prompt 里特别要求 AI 检查 ExceptionHandler 和 ControllerAdvice 中的全局异常处理，把统一的错误响应格式也纳入文档。

为什么这个流程比人工写更可靠

传统的人工读代码写文档，最大的问题是“选择性忽略”——开发者会下意识地跳过自己认为不重要的分支逻辑和边界处理，而这些恰恰是后续维护时最容易踩坑的地方。

AI 没有这种惯性思维。它逐行分析代码时，每个 if-else 分支、每个 catch 块都会被平等对待。我在实际使用中发现，AI 至少三次标注出了“接口在金额超过 5000 元时会走额外的风控审核分支”，而这行逻辑藏在 Service 层一个 300 行方法的最深处，代码 review 时从来没人注意到过。

另一个优势是效率。37 个接口，人工梳理加写文档至少需要 3-4 个工作日，用这个流程压缩到了 40 分钟（项目扫描 5 分钟 + 分批分析接口 25 分钟 + 业务确认 5 分钟 + 格式化输出 5 分钟）。而且产出的文档格式统一，不会出现不同接口的文档详略程度差异巨大的问题。

局限和适用场景

这个流程不是万能的。它有几个明确的前提条件：

代码本身的结构必须相对清晰——如果整个项目只有一个 3000 行的 Service 类，方法之间互相调用形成网状依赖，AI 的分析质量会大幅下降
项目使用的框架和库必须是 AI 训练数据中常见的，如果是自研框架或冷门框架，AI 无法理解注解和配置的含义
业务语义的补全依赖于人的输入，AI 只能从代码中提取技术逻辑，无法无中生有地理解业务背景

最适合的场景是：基于 Spring Boot / Django / Rails 等主流框架的 Web 项目，有明确的分层结构，代码本身质量尚可（至少没有过度耦合），但缺少文档或文档严重过时。这类项目在企业里存量巨大，这个流程能直接产生价值。

常见问题

这个流程对非 Java 项目也适用吗？

适用。核心思路是通用的——先建全局视图，再逐接口追踪调用链，最后补业务语义。我主要在 Spring Boot 项目上用这个流程，但同事在 Django 和 Express 项目上复现过类似效果。唯一需要调整的是第一步中“识别框架和分层结构”的 Prompt，要针对具体语言和框架的描述做适配。

AI 分析调用链时遇到动态代理或反射调用怎么办？

这是实际使用中最常见的断链场景。如果代码里用 ApplicationContext.getBean() 或反射来调用，AI 无法静态追踪。我的处理方式是：在第一步建立项目地图时，专门要求 AI 列出所有使用反射和动态代理的位置，这些位置的接口分析改为人工补充调用链，其他部分仍由 AI 完成。

生成的文档准确率有多高？需要人工逐条复核吗？

调用链追踪的准确率在 90% 左右，主要错误集中在重载方法的匹配上（AI 有时会选错同名方法的不同重载版本）。业务语义描述的准确率取决于代码中注释和枚举定义的完整度。我的建议是：对核心交易链路接口逐条复核，非核心的查询类接口可以抽查。整体复核时间大约是纯人工编写文档的 1/5。