旧接口代码丢给 AI，反向整理出 3 张字段说明表

一句话结论

把旧接口代码和一段脱敏请求样例交给 AI，让它分别整理出请求参数、响应字段、错误码三张说明表，一个老模块通常一天内能理完。

这篇解决什么问题

接手一个跑了六七年的老服务，接口文档要么压根没有，要么停在两年前的 wiki 页面上。改一个字段之前得翻三层代码，还不一定找得到谁在调它。这篇讲的就是把这个活干完：不搭文档站，只产出三张能直接贴进 wiki 的字段表。

适用：有源码可读、接口还在线上跑、近期要做交接或对外开放的模块。不适用：手上只有编译后的包，或者这套接口本来就准备推倒重写。

开始前要准备什么

• Cursor：能读整个仓库，免费额度够跑一个小模块，长期用要开会员
• Claude 网页版：适合贴单个文件问结构，免费版有次数限制
• 代码素材：Controller、DTO、返回包装类这三个文件
• 请求素材：一段脱敏后的请求 JSON 和一段响应 JSON
• 时间：单接口出第一版通常 10 分钟内，整个模块按半天准备
• 一个约定：字段中文名先跟调用方对一遍，AI 猜的要人工过

具体怎么做

第 1 步 · 先让 AI 摸清有哪些接口

别急着写表。先让它把 Controller 读一遍，把所有对外入口列出来。这一步的产出只是一张范围清单，用来确认你别漏掉隐藏的接口。

你是一位做接口文档的资深后端。下面是我从旧项目里贴出来的 Controller 代码，请不要修改代码，只做阅读分析。
任务：列出这份代码里所有对外暴露的 HTTP 接口。
对每个接口给出：请求路径、HTTP 方法、Controller 类名与方法名、入参类型、返回类型。
输出格式：一张 markdown 表格，四列——路径 / 方法 / 处理方法 / 入参→返回。
如果路径是从类上的 @RequestMapping 拼接出来的，请在表格下方单独说明拼接规则。
不要推测代码里没有的接口，宁缺毋滥。
代码：
（把 Controller 文件整段贴在这里）

预期产出：一张接口清单表，能看出这个模块对外暴露了几个入口、每个入口的入参出参类型。范围清楚之后再逐个往下做，比一上来就铺开省事得多。

第 2 步 · 请求参数拆成第一张表

挑清单里调用量最大的那个接口先做。只贴 DTO 不够用，我试过，AI 会把 status 猜成“订单状态”，实际它是支付状态。补一段真实请求 JSON 之后，备注的准确度肉眼可见地变好。

接着上面的接口：POST /api/order/query。
下面是两部分内容：一是该接口入参 DTO 的定义代码，二是一段线上真实请求的 JSON（已脱敏，字段名未改）。
请输出一张“请求参数说明表”，markdown 表格，列固定为：
字段名 | 类型 | 是否必填 | 示例值 | 含义 | 备注
要求：
1. 类型写 JSON 类型（string / integer / number / boolean / array / object），不要写 Java 类型。
2. 是否必填以代码里的校验注解为准；没有注解就写“未校验”，不要猜。
3. 含义一栏用一句中文说明业务含义，参考代码注释和变量名；拿不准就写“待确认”。
4. 嵌套对象请用 parent.child 的形式展开成独立行。
5. 表后附一段不超过 5 行的说明，写清楚哪些字段是这次从样例里没能确认的。
DTO 代码：
（贴 OrderQueryReq 的字段部分）
请求样例：
（贴一段脱敏后的 JSON）

预期产出：第一张《请求参数说明表》，列固定六项，嵌套字段已经展开成独立行，末尾带一小段“待确认”清单。

第 3 步 · 响应字段拆成第二张表

响应比请求麻烦，嵌套多、数组多。我的做法是按 JSON 的实际结构走，代码里定义但样例里没出现的字段单独标出来，这类字段往往就是线上踩坑的来源。

同一个接口，这次看响应。
下面是返回体包装类 Result 的定义、OrderQueryResp 的定义，以及一段真实响应 JSON（脱敏，结构未改）。
请输出“响应字段说明表”，markdown 表格，列固定为：
字段名 | 类型 | 是否一定返回 | 示例值 | 含义 | 备注
要求：
1. 以响应 JSON 的实际结构为主线；代码里定义但样例中没出现的字段也要列出，在“是否一定返回”里写“代码有、样例无”。
2. 数组字段在字段名后标 []，并在表下面单独用一个小节说明数组元素的字段结构。
3. 三层以上的嵌套，每层用缩进的 parent.child 表达，不要合并成一行。
4. 时间、金额、枚举这三类字段，在备注里写清格式（如 yyyy-MM-dd HH:mm:ss、单位分）。
5. 不要编造枚举值；代码里是魔法数字的，备注写“枚举含义待确认”。
代码：
（贴 Result 和 OrderQueryResp）
响应样例：
（贴一段脱敏后的 JSON）

预期产出：第二张《响应字段说明表》，含数组元素子表和“代码有、样例无”的标注行。

第 4 步 · 错误码补成第三张表

错误码是最容易被跳过的一张，也是接入方问得最多的。别让 AI 自己编号，只认代码里真实存在的常量，那些只返回 message 的地方就老实写“无码”。

还是这个接口。下面贴的是全局异常处理器、业务异常类，以及这个接口里所有 throw 和 return error 的位置。
请输出“错误码说明表”，markdown 表格，列为：
错误码 | 触发条件 | 返回文案 | 调用方建议处理方式 | 出处（类名或方法名）
要求：
1. 错误码以代码里实际出现的常量为准，不要自己编号。
2. 触发条件写成“什么情况下会返回”，用业务语言，不要照抄 if 条件。
3. 调用方建议处理方式，只写三种之一：重试、提示用户、上报排查。
4. 没有错误码、只返回 message 的地方，错误码一栏写“无码”。
5. 表格按 HTTP 状态码分组，每组一个小标题。
代码：
（贴异常处理器和接口实现里的校验分支）

预期产出：第三张《错误码说明表》，按 HTTP 状态码分组，每条都能对应到具体的类或方法。

第 5 步 · 回头做一次交叉校对

三张表都出来之后，让 AI 拿原始代码回头对一遍。这一轮只让它挑毛病、不许重写表格，不然它会把本来改对的地方又改回去，白折腾一轮。

做一次校对。我给你三张已经写好的表（请求参数、响应字段、错误码），以及原始代码。
请只做检查，不要重写表格。逐项核对并输出一份问题清单，格式：
问题类型 | 位置 | 问题描述 | 建议改法
检查这几件事：
1. 代码里有、表里没有的字段。
2. 表里有、代码里找不到出处的字段（可能是上一轮编的）。
3. 类型对不上的，比如代码是 BigDecimal，表里写 string 但备注没写精度和单位。
4. 必填标记和校验注解不一致的。
5. 错误码表里触发条件写得含糊、看不出什么场景会触发的。
清单按严重程度排序，最多列 15 条。没问题就输出“未发现明显问题”。
三张表：
（贴表）
代码：
（贴对应文件）

预期产出：一份问题清单，通常十条上下，按严重程度排好。照着改完，三张表就可以发出去了。

实测记录

拿一个跑了六七年的订单模块试的，十来个对外接口，Java + Spring，注释稀薄，wiki 停在两年前。下面这些时间都是那一次的记录。

最容易错的 3 个地方

1. 只贴 DTO 不给样例。AI 只能按变量名猜含义，备注多是废话；补一段脱敏 JSON 就好。
2. 一次喂全部接口。喂到第五六个，AI 开始凭空补字段；一次一个，做完再换。
3. 嵌套和数组被略过。子字段最容易漏，让它单独列一层子对象再核。

可复用的东西

把五段提示词按顺序存成一个文本片段，下次换个接口只改中间贴的代码和 JSON，其余不动。第 1 步和第 5 步跟具体接口无关，可以固定下来；第 2 到第 4 步的列名建议保持一致，三张表贴在一起才像一份文档。

这套流程没什么技巧，本质是逼 AI 一次只干一件事，再回头自己查一遍。慢一点，但产出的东西敢直接发给对接方。你们手上那套老接口，文档停在哪个年份了？

如果你也经常要做这件事，欢迎在评论区说说你的卡点和做法；也可以留言告诉我，你想看哪个岗位的哪件活怎么用 AI 拆。

admin 普通

收藏 海报 链接