第16讲｜API 联调时怎么把 AI 用到位

专栏：AI 编程提效实战 30 讲

标签：AI编程 / API联调 / 接口调试 / 后端开发 / 程序员效率

先说结论

API 联调最耗时间的地方，往往不是写一段请求代码，而是这些细碎问题：

• 文档里的字段和真实返回不一致
• 前端、后端、网关、第三方服务各说各的
• 报错只有一串状态码，不知道该查哪一层
• 复现步骤靠口头描述，换个人就跑不通
• 试了很多次请求，但没有沉淀成可复用用例

这类场景很适合把 AI 用起来。但用法不是让 AI "帮我看看接口为什么不通"，而是让它帮你整理上下文、生成请求样例、对比预期和实际、设计排查顺序、沉淀联调用例。

这篇给你一套可复制的 API 联调工作流：先把接口上下文说清楚，再让 AI 生成可运行请求，最后用响应差异反推排查路径。目标不是替你猜 Bug，而是减少无效试错。

为什么 API 联调适合用 AI

联调本质上是一个"信息对齐"问题。

你要同时确认：

1. 请求路径是否正确
2. 请求方法是否正确
3. Header、Token、Cookie 是否正确
4. Query、Body、Path 参数是否正确
5. 服务端实际收到的请求是否和你以为的一致
6. 返回结构是否符合约定
7. 错误码、日志、链路追踪能否对应起来

这些信息分散在接口文档、代码、抓包记录、日志、Postman、curl、前后端沟通记录里。AI 的价值，是把这些碎片重新整理成一个可检查的联调包。

你给 AI 的信息越接近真实联调现场，它越能帮你缩小范围；你只给一句"接口 500 了"，它只能泛泛建议"检查日志"。

第 1 步：把接口背景一次性说清楚

低效问法通常是：

这个接口为什么调不通？

这句话缺少最关键的上下文：接口是什么、谁调谁、预期是什么、实际是什么、环境是什么。

更稳的问法是先给一份联调上下文：

我在联调一个订单创建接口，请你帮我整理排查思路。

接口信息：
- 环境：test
- 方法：POST
- 路径：/api/orders
- 调用方：前端 Web
- 服务方：order-service
- 鉴权方式：Bearer Token

预期结果：
- 创建订单成功
- 返回 orderId、status、createdAt

实际结果：
- HTTP 400
- 返回：{"code":"INVALID_ARGUMENT","message":"skuId is required"}

我已经确认：
- Token 有效
- 请求能到达 order-service
- 同一账号调用查询接口正常

这一步不是让 AI 直接下结论，而是先让它知道你已经确认了什么、还没有确认什么。

第 2 步：让 AI 生成可复现请求

API 联调里，一个很实用的动作是让 AI 把口头描述转成 curl、Postman 参数或测试代码。

比如你可以这样要求：

请根据上面的接口信息，生成一个可直接运行的 curl 请求。

要求：
- Header、Query、Body 分开写清楚
- Body 使用 JSON
- 对每个字段补一句用途说明
- 如果有缺失字段，请列出需要我补充的信息

AI 生成请求后，不要急着复制执行。先检查 4 件事：

1. URL 是否对应正确环境
2. Method 是否和文档一致
3. Header 是否漏了鉴权、租户、Content-Type
4. Body 字段名是否和接口真实参数一致

很多联调问题，就是在这一步暴露的：文档写的是 sku_id，代码里接收的是 skuId；前端传了字符串，后端要求数字；调用方漏了租户 ID。

第 3 步：用"预期 vs 实际"让 AI 缩小范围

不要只把报错扔给 AI。更有效的是把预期和实际并排给它。

可以这样问：

请对比这个接口的预期和实际结果，帮我判断最可能的问题层级。

预期：
- HTTP 200
- 返回 orderId、status、createdAt

实际：
- HTTP 400
- code: INVALID_ARGUMENT
- message: skuId is required

请求 Body：
{
  "sku_id": "10001",
  "count": 2
}

接口文档字段：
- skuId: string，必填
- count: number，必填

请输出：
1. 最可能原因
2. 还需要验证的证据
3. 下一步最小验证动作
4. 不要泛泛建议"检查日志"

这时 AI 大概率会指出：请求字段使用了 sku_id，但文档要求 skuId。下一步最小动作不是通读所有代码，而是改字段名后重试，并确认服务端日志里的入参。

第 4 步：让 AI 给出排查顺序

联调最怕的是乱查：一会看前端，一会改网关，一会怀疑数据库，一会又去找第三方。

更好的方式是让 AI 按"成本低、证据强、影响小"的顺序安排排查。

提示词可以这样写：

请把这个接口问题拆成排查顺序。

排序原则：
1. 先查最容易验证的输入问题
2. 再查调用链路和鉴权问题
3. 再查服务端参数解析和业务校验
4. 最后再查依赖服务和数据问题

每一步请给出：
- 要验证的问题
- 怎么验证
- 需要看什么证据
- 验证通过后下一步是什么

这类输出对协作也很有用。你可以把它贴到群里，明确"我已经验证了 A、B，下一步需要后端确认 C"，减少来回扯皮。

第 5 步：把联调结果沉淀成用例

一次联调结束后，不要只留下聊天记录。

最好沉淀 3 类东西：

1. 一个能跑通的 curl 或 Postman 用例
2. 一份字段说明和常见错误
3. 一段最小自动化测试或接口冒烟脚本

可以让 AI 帮你整理：

请把这次联调结果整理成接口用例文档。

包含：
- 接口用途
- 请求方法和路径
- 必填 Header
- 请求 Body 示例
- 成功响应示例
- 常见错误码
- 这次踩坑点
- 可直接复制的 curl
- 后续可加入自动化测试的断言

这样做的好处是，下次同事接手、测试复现、线上问题回溯时，不需要重新问一遍"当时怎么调通的"。

可直接复制的完整提示词

你现在是我的 API 联调助手。

目标：帮我把接口联调问题拆成可验证、可复现、可沉淀的排查流程。

请不要直接猜原因，先整理上下文，再输出排查顺序。

接口背景：
- 环境：
- 调用方：
- 服务方：
- 方法：
- 路径：
- 鉴权方式：
- 相关 Header：

请求信息：
- Query：
- Path 参数：
- Body：

预期结果：
- HTTP 状态码：
- 响应字段：
- 业务状态：

实际结果：
- HTTP 状态码：
- 错误码：
- 错误信息：
- 响应体：

已验证事实：
- 

请按以下结构输出：

1. 上下文整理
- 哪些信息已经明确
- 哪些关键信息缺失

2. 可复现请求
- 生成 curl
- 标注 Header、Query、Body
- 指出可能缺失或不一致的字段

3. 预期 vs 实际对比
- 最可能的问题层级
- 支撑这个判断的证据
- 还需要补充的证据

4. 排查顺序
- 每一步验证什么
- 怎么验证
- 看什么日志、响应或链路信息
- 下一步动作是什么

5. 沉淀材料
- 成功请求样例
- 常见错误码
- 这次踩坑点
- 可加入自动化测试的断言

最后总结

API 联调时，AI 最有价值的地方不是"猜接口为什么不通"，而是帮你把信息整理成证据链。

记住这 5 步：

1. 先给完整接口背景
2. 生成可复现请求
3. 对比预期和实际
4. 按证据安排排查顺序
5. 把调通结果沉淀成用例

下一讲我们继续聊更偏排查的场景：用 AI 做日志分析的高效套路。