当 AI 同时持有前后端上下文，接口设计就不再是口头约定

当 AI 同时持有前后端上下文，接口设计就不再是口头约定

前后端分离开发里，接口设计一直靠"口头约定 + 文档记录"维持。约定在沟通里流转，文档在版本里过期，接口不一致就成了联调期最常见的坑。Workspace 多项目支持带来一个本质变化：AI 同时持有前后端上下文，接口设计从"人传人的约定"变成"同一份上下文里的自洽产物"。这篇文章聊聊这个变化为什么重要，以及它改变了哪些工作习惯。

一、接口约定为什么总容易出问题

先承认一个现实：接口不一致，不是前端的错，也不是后端的错，是信息传递结构的错。

前后端分离的架构下，接口信息天生在两份代码之外：

• 后端知道接口的"供给侧"——路径、参数、返回结构，都在 Controller 里；
• 前端知道接口的"消费侧"——调用方式、参数组装、字段使用，都在请求封装里；
• 两端之间没有"共享的事实"，只有口头约定、接口文档、或者一份没人及时更新的 Swagger。

这种结构下，不一致是必然的，只是早晚问题。常见翻车现场：

1. 后端改了参数名忘同步，前端还按老参数传；
2. 前端按驼峰传参，后端按下划线接收；
3. 返回结构调整，前端取字段直接 undefined，页面白屏。

每次都靠联调 Debug 兜底。Debug 能修一次，但修不了"约定会过期"这个结构性问题。

文档为什么会过期：信息衰减的三个环节

说"文档会过期"之前，先说清楚它到底是从哪个环节开始坏掉的。接口信息从产生到被前端使用，要经过三次传递，每一次都在衰减：

第一次衰减：从代码到文档。后端改完接口，先在心里记着，等手头活干完才想起来更新文档。这中间隔的时间越长，漏更新的概率越大。很多人都有过这种经历：文档里写的接口和老代码对不上，只能对着 Controller 反推真实定义——因为文档已经不可信了。

第二次衰减：从文档到前端理解。文档写清楚了，前端读的时候还会"翻译"一次：文档里status的枚举写在表格里，前端把它抄进代码时漏了REFUNDED这一行。不是前端不仔细，是人读文本再转代码，中间天然有认知损耗。

第三次衰减：从约定到记忆。即使一次对齐成功，三个月后这个接口要加字段，后端改完代码，突然想起"这个接口前端还有两个页面在用"——但哪两个页面，自己也想不全了。约定的有效性，绑定在每个人的记忆里，而记忆是最不可靠的载体。

三次衰减，每次都是"人工转译"。Workspace 多项目上下文绕开的正是这三层转译：代码、前端调用、AI 上下文是同一份信息，中间没有人手抄、没有文档传递、没有记忆存储。这不是"文档写得更好"，而是"文档这个环节被取消了一部分职责"。

二、多项目上下文：接口契约长在代码里

Workspace 多项目支持的思路，不是"改进文档流程"，而是改变信息传递结构：让 AI 在同一个上下文里同时看到前端的调用方式和后端的接口定义。

这样接口契约不再依赖人传人：

• 前端项目挂在 Workspace 里，AI 生成后端接口时能看见前端怎么调用；
• 后端项目挂在 Workspace 里，AI 生成前端调用时能看见后端定义了什么；
• 两端代码是同一推理过程的产物，而不是两份经过转译的独立实现。

接口约定从"写在文档里的约定"变成"长在代码里的自洽约束"。文档会过期，代码不会——只要两端都在同一个上下文里，生成的那一刻它们就是一致的。

三、实测一个典型的"约定失效"场景还原

为了说清楚差异，还原一个我自己真实踩过的坑，两端代码都不长，但信息传递结构很典型。

场景：给用户模块加"修改密码"接口。

传统模式下，后端同学定义接口：

// 后端定义（传统方式）@PostMapping("/user/change-password")publicResult<Void>changePassword(@RequestBodyChangePasswordReqreq){// req { oldPassword, newPassword }}

口头同步给前端时，重点说了一句"新密码字段叫 newPassword"。前端同学记下了，但一周后写代码时，记成了：

// 前端调用（传统方式，字段记错）awaitrequest.post('/user/change-password',{oldPwd:form.oldPassword,// 后端要 oldPasswordnewPwd:form.newPassword,// 后端要 newPassword})

联调报错：oldPwd 不是有效字段。前端翻了两层封装才找到类型定义，改了字段名，通过了。但从"口头约定"到"Debug 修复"，中间浪费了一个下午，而真正的问题不是谁记性差，是约定靠口头传递，中途必然衰减。

Workspace 模式下同样的需求：你在智能会话里说"加修改密码接口，前端在个人中心页放表单和后端一起改"。

执行后——后端生成oldPassword/newPassword字段，前端表单字段、请求体、字段名一次对齐。不需要人工同步，因为模型生成两边时用的是同一份上下文。端点测完参数名直接对上了。

这不是模型"猜得准"，是结构上它根本不需要猜：前端字段的生成逻辑里，后端定义就是它的输入。

一次接口变更的两种传播路径

把"约定失效"放到更常见的场景里看：接口要加一个字段。这个动作在两种模式下各自的传播路径是：

传统模式： 后端改代码 → 更新文档 → @前端记得看 → 前端查文档 → 改成代码 ↑ 任何一环断了，前面的都白做，最终靠联调兜底 多项目模式： 需求描述"订单列表加支付渠道字段，前后端一起改" → AI 生成后端新字段 → AI 同步生成前端展示/请求 → 一次变更两端落地

传统模式里，加一个字段要经过六步、两个交接人，任何一步断了就得靠联调 Debug 兜底；多项目模式里，一次变更在模型内部就完成了两端传播。

这里要补充一个诚实的边界：多项目模式解决的是"代码生长时的对齐"，不解决"代码历史里的遗漏"。存量接口已经写好的老代码，AI 不会自动去改——你要主动发起变更（“把这个接口加个字段，两端一起改”），它才会顺着上下文把两端同步掉。但即便如此，它的传播路径也比"人传人"短得多。

四、这个变化到底改变了什么

把"接口约定靠口头"和"接口约定长在代码里"放在一起对比：

维度	口头约定 + 文档	多项目上下文生成
信息载体	文档、聊天记录	两端代码 + AI 上下文
同步成本	每次变更人工同步	变更时重新生成即对齐
失效条件	文档不更新就失效	上下文一致就自洽
出错环节	转译、记忆、文档滞后	生成推理，可审可改
检验时机	联调期才发现	生成期已对齐

最重要的一行是最后一行：传统模式的接口不一致，要到联调期才暴露；Workspace 模式下，生成时就已对齐，检验从"事后 Debug"变成"事中审查"。

审查生成接口时的检查清单

"事中审查"这个动作要落地，得有可执行的清单。我在每次生成接口后，固定对照四类问题过一遍：

第一类·契约完整性：路径、方法、必填参数、返回结构、错误码，有没有缺项。特别容易漏的是错误码——接口正常返回定义了，异常返回（参数非法、无权限、资源不存在）往往空白，前端拿到非 200 的响应就无分支可走。

第二类·命名一致性：新接口的命名风格和现有代码一致吗？老接口叫list、detail，新接口叫query、getInfo，一眼就看得出不是同一个团队写的。让模型照着项目里的现有命名习惯生成，通常差不到哪去，但要人眼确认。

第三类·兼容性：新增参数有没有默认值？老调用方不传新参数会不会报错？返回结构有没有改类型、删字段？这三条是"上线即事故"的高发区，多项目上下文能对上前端调用方，但管不到外部系统。

第四类·语义正确性：接口的行为和需求一致吗？“导出全部数据"还是"导出当前筛选结果”、“按创建时间排序"还是"按更新时间排序”——这类语义问题模型可能从需求描述里得到，也可能自己推断，必须人对一遍需求逐条打勾。

这份清单四类过完，接口这层的审查就闭环了。它替代的不是"写文档"，而是"等你发现错了"。

五、你的工作习惯要做三个调整

结构变了，人的动作也要跟着变。三个实际调整建议：

调整1：接口设计从"写下来"变成"审一遍"。

以前你花时间"写接口文档、同步给前端"；现在省下同步时间，把省下的时间花在审查生成的接口设计——命名是否规范、参数是否完备、返回结构是否可扩展。审查的动作替代了同步的动作。

调整2：需求描述里写清楚"约束条件"。

既然接口由模型在上下文里生成，你的需求描述里就要把不可谈判的约束写进去。比如：“status 参数必须与现有 OrderStatus 枚举一致”“返回结构保持现有 Result 包装格式”。约束写得越显式，生成结果越稳。

调整3：把"联调期"的定义改成"回归期"。

以前联调是"两端对齐参数"，现在两端生成时已对齐，联调环节变成了纯粹的回归验证：老功能没坏、边界场景覆盖、性能没问题。你安排时间的重心从"Debug 对齐"挪到"回归验收"。

调整4：把"接口变更"当成一次显式事件。

传统模式里，“改个接口"是日常动作，改完顺手同步就行；多项目模式下，接口变更影响范围更大（它会触发前端调用方同步改），所以要把它当成一次显式事件来管理：变更前想清楚影响哪些消费方，变更时让 AI 把两端一起改，变更后按上面的四类清单验收。把"顺手改"升级成"显式变更”，多项目上下文的价值才能完整释放——否则你只用了它的一半能力。

六、什么时候仍然要"口头约定"

多说一句公道话：AI 上下文能解决"接口实现层的一致"，但解决不了"接口设计层"的决策——这个接口到底要不要做、拆几个、合并还是拆分、谁来消费，这些依然是人的决策，仍然要在人和人之间约定。

所以精确的边界是：

• 接口实现的一致性（字段名、类型、路径、返回结构能否对齐）——AI 上下文可以兜底；
• 接口设计的目的性（为什么这么设计、适不适合业务场景）——必须人来约定。

把"约定"留给设计，把"对齐"交给 AI。这才是"大模型解决代码问题，AI 编程工具解决工程问题"在接口这件事上的准确含义。

接口设计层的四个决策点，仍然要人

既然设计还是要人做，干脆把"设计层的决策点"列清楚，让大家知道该在哪儿下功夫：

1. 要不要新接口：复用现有接口加参数，还是新建独立接口？影响的是接口膨胀度和调用方数量，这是架构判断；
2. 拆还是合：两个场景各自要字段，是拆成两个接口还是合并一个带可选参数？合了简单但耦合，拆了清晰但冗余，这是取舍判断；
3. 字段怎么命名：虽然多项目模式会"对齐"，但对齐的前提是你先定了语义。status、state、payStatus哪个更符合业务语言？这是业务判断；
4. 返回结构怎么组织：扁平还是嵌套、直接返回数据还是包一层 envelope？影响所有调用方，这是兼容性判断。

这四个决策点，AI 可以给你候选，但拍板要人。想清楚这层，你就明白"口头约定"不会消失——它只是从"约定字段怎么拼"上升到了"约定接口怎么设计"。

七、总结：接口约定从此有了"代码级"的兜底

一句话收束：当 AI 同时持有前后端上下文，接口设计就不再是口头约定，而是生成时自洽的代码事实。

它不消灭接口设计本身——设计永远是人的事；它消灭的是"设计完成后靠人转译传递"这个最容易出错的环节。文档可以迟到，沟通可以有损耗，但两端代码在同一个上下文里生成的那一刻，它们已经对上了。

如果你还在被联调期"参数对不上"折磨，先把 Workspace 搭起来，让 AI 的程序员看一眼你的前端调用，再改一次后端接口试试——大概率是：生成即对齐，联调变验收。