前后端联调，我现在用一份文档管着

做 AI 产品的时候，前后端联调是个老问题。但加上 AI 编辑器之后，问题变得更复杂了。

踩过的坑

之前的流程是这样：前端写页面，后端写接口，联调的时候对一下。听起来没问题。

实际情况是：

• 后端改了字段名，没告诉前端
• 前端以为某个字段一定有值，结果后端返回 null
• AI 编辑器帮我「优化」了接口调用，把字段名改了
• 联调的时候发现对不上，互相甩锅

最后一个最坑。我用 Cursor 写代码，它有时候会「好心」帮我改接口结构，改完我还没注意到。等联调的时候才发现，前后端对的是两套东西。

现在的做法

我搞了一份接口文档，放在 docs/api-requirements.md，前后端都用这一份。

核心是三层状态标记：

状态	含义
🟦 FE Ready	前端页面写完了，依赖这个接口结构
🟨 BE Ready	后端实现了，结构和文档一致
🟩 Integrated	真实联调通过，线上能用

一个接口从定义到上线，必须经过这三个状态。不能跳。

为什么要这么麻烦

因为我发现，接口问题 90% 出在「谁先改、谁后知道」。

以前后端改了字段，可能发个消息说一声，也可能忘了。前端不知道，代码还是老的，联调就炸。

现在的规则是：先改文档，再改代码。

后端想改字段？先在文档里加一行「⚠️ 后端建议」，前端确认了再改。改完标记 🟨 BE Ready。

前端想加字段？先在文档里写清楚，标记 🟦 FE Ready，后端照着实现。

这样至少有个地方能追溯：谁改的、什么时候改的、为什么改。

给 AI 编辑器的约束

这个是我后来加的。

AI 编辑器（Cursor、Copilot 这些）有时候会自作主张。比如它觉得某个字段名不够「语义化」，就帮你改了。或者它觉得某个接口结构可以「优化」，就重构了。

我在文档里专门写了一段：

AI 严禁行为：

• ❌ 修改前端代码以适配错误接口
• ❌ 擅自修改已标记 🟩 Integrated 的接口
• ❌ 自动「优化」字段或结构

这段话不是写给人看的，是写给 AI 看的。把文档放进项目的 steering 规则里，AI 编辑器读到这段，就知道哪些东西不能动。

当然，AI 不是每次都听话。但至少有个明确的边界。

强依赖字段

还有一个细节：有些字段前端是「强依赖」的，不能为空、不能异步补充。

比如商品卡片的价格，前端必须拿到才能渲染。如果后端返回 null，页面就挂了。

我在文档里给这类字段打标记：

字段	类型	前端用途	强依赖
price	number	显示价格	✅

标了强依赖的字段，后端不能返回 null。如果做不到，接口就不能标 🟩 Integrated。

AI 接口的特殊处理

AI 接口和普通接口不一样。它可能要跑几秒甚至几十秒，不能用普通的请求-响应模式。

我在文档模板里加了几个字段：

项目	示例
是否 AI 接口	是
预期耗时	5s
是否异步	是
查询方式	polling

这样前端一看就知道，这个接口要做 loading 状态、要轮询、要处理超时。

用了一段时间的感受

这套流程跑了两个月，联调效率确实提高了。

最明显的变化是：出问题的时候不用互相猜了。打开文档一看，状态是什么、谁改的、什么时候改的，都有记录。

当然也有麻烦的地方。每次改接口都要先改文档，多了一步。有时候赶进度，会想跳过这步。

但我后来发现，跳过这步省下的时间，联调的时候都会加倍还回来。

文档模板

最后贴一下我用的模板，有需要的可以参考：

#### X.X.X 接口名称

| 属性 | 值 |
|---|---|
| 接口标识 | functionName |
| 所属页面 | /path |
| 请求方式 | POST |
| 请求路径 | /api/xxx |
| 接口状态 | 🟦 FE Ready |

**请求参数**

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|

**响应数据**

| 字段 | 类型 | 前端用途 | 强依赖 |
|---|---|---|---|

**⚠️ 待确认 / 变更记录**
- 2026-01-28：初始定义

核心就一句话：接口文档不是注释，是契约。前端、后端、AI 都得照着来。