Vibe Coding Mock 到真实服务切换：让替身按契约退出

Mock 最擅长回答“界面流程是否说得通”，却很容易被误当成后端的提前实现。它通常立即返回固定成功值，没有 cookie、权限、超时、并发冲突、分页变化和部分失败。等真实服务接入时，组件已经直接依赖 fixture 字段和 Mock 函数，替换一个 URL 无法解决语义差异，团队只好边联调边重写。

正确边界是把 Mock 定义为某个版本契约的替身，而不是产品真相。API Mock 与 Fixture 漂移门禁治理长期一致性；本文聚焦原型阶段如何设计替换接缝和执行切换。

先冻结协议，再制作场景

在写 Mock handler 前，定义操作、请求、响应、认证方式、错误类别、幂等要求和取消语义。HTTP API 可以用 OpenAPI 3.1 描述结构，并用 JSON Schema 表达类型与约束；业务规则仍需单独写出，例如“版本冲突不覆盖已保存内容”“重复幂等键返回同一业务结果”。规范的有效性不等于业务正确，但它提供共同可解析的边界。

每个 fixture 使用稳定 scenarioId，至少覆盖成功、空结果、字段错误、未认证、无权限、冲突、限流或暂时失败，以及连接中断。只有服务确实声明的错误才进入正式场景，不凭想象发明状态码。动态 ID 与时间通过确定性生成器产生，测试能固定 seed；客户数据和真实 token 不进入 fixture。

Mock 返回值必须通过同一响应解析器，不能因为是本地对象就绕开 JSON 序列化、缺失字段和未知枚举。前端发送的请求也要被 schema 与业务 oracle 检查，避免 Mock 接受真实服务会拒绝的多余字段。REST API 版本控制可帮助安排字段演进，Agent API 契约兼容门则验证旧新消费者组合。

组件依赖用例端口，不依赖 Mock

界面只调用 ArticleService.submit(input, signal) 这类应用端口，Mock 与 HTTP client 分别实现该端口。组件看到统一的领域结果，例如 accepted、field-error、conflict、temporarily-unavailable，而不是直接判断 response.status === 409。HTTP adapter 负责认证头、编码、响应解析和传输错误映射，Mock adapter 负责按场景产生同样结果。

不要把所有失败折叠成一条字符串。字段错误要关联字段，未认证触发重新登录，权限不足不能无限重试，冲突需要重新读取，网络未知结果要区分操作是否可能已经成功。写操作携带服务支持的幂等键；如果服务不提供幂等保证，UI 不能仅靠禁用按钮声称解决重复提交。

Fetch 在收到 HTTP 错误状态时通常仍会正常解析为 Response，代码必须显式检查状态；网络失败才会拒绝 Promise。页面卸载、用户取消或新请求取代旧请求时，通过 AbortController 传播取消，并确保迟到结果不会覆盖新状态。React 数据获取模式可以组织界面订阅，但真正的可替换性来自这里的端口与结果语义。

分四步接入真实服务

第一步在 CI 对规范、Mock 与 HTTP adapter 做静态和契约校验。使用同一请求样本分别验证序列化结果，确保字段名、可空/缺失、枚举和错误映射一致。不要让生成 Mock 的同一个工具单独验证自己。

第二步在隔离环境对真实服务运行消费者场景。环境使用合成账号、独立数据和受控邮件/队列 sink；每个场景清理自己创建的数据。真实服务缺少某个声明场景时，记录 UNVERIFIED 并阻止默认切换，不能让 Mock 绿灯代替服务证据。

第三步可对只读、无敏感数据的请求做影子比较：用户仍看到旧路径结果，后台把规范化请求发给真实服务，比较响应结构和业务不变量。禁止影子执行有副作用的创建、支付或发信操作；若必须验证写路径，应使用隔离租户和明确 sink，而不是双写生产。比较时只能忽略已声明的请求 ID、时间等非语义字段，不能把金额、排序或空值差异归一化掉。

第四步按稳定 cohort 切换 adapter，保留旧实现和匹配契约作为短期回滚点。切换配置绑定发布版本，不能由浏览器随意选择。监测解析失败、未知枚举、业务错误、取消和重试结果；出现契约不符时回到 Mock 或旧服务只适合尚未产生真实副作用的环境。生产写请求的回滚必须依据服务端幂等与数据兼容策略，不能简单重发。

以替身删除作为完成标准

切换完成要证明产品路径不再导入 Mock、构建产物不打包 fixture、运行配置没有隐式 fallback，且真实服务覆盖全部批准场景。测试目录可以保留 Mock，但必须从当前规范生成或持续校验，并明确 owner。若真实服务不可用时产品静默回到成功 fixture，这是数据造假，不是降级。

最终检查至少包含：请求与响应契约通过；关键错误场景在真实服务可复现；鉴权在服务端执行；取消与迟到结果经过测试；未知字段策略明确；Mock 和生产 adapter 的共享用例测试一致；回滚不会重复副作用。再将结果交给编程 Agent 的改动验证门。

Mock 的价值是让团队提前讨论交互和契约。只有从第一天就准备好替换端口、失败语义和删除条件，它才能按时退出，而不是成为永远比真实系统更乐观的第二套后端。