从前端联调到 Agent 回归测试：Mocktail 4 如何把可控 API、流量观察与 MCP 放在同一台本机
接口依赖还没就绪，往往不是“先写几个 JSON 文件”那么简单。前端需要稳定的成功响应，测试还要覆盖超时、401、429、500 与特定响应头；当契约不断修改，散落在代码里的临时 mock 又很难被团队复用。更麻烦的是，AI 编码 Agent 即使能改页面，也未必知道该怎样搭出一组能让它自行验证错误分支的接口。
Mocktail 是一个 MIT 许可的自托管 mock API 服务：它把接口目录、响应编辑、请求测试和流量查看放在本地 dashboard 中，也可以用二进制或 Docker 运行。2026 年 8 月发布的 4.0 系列将默认端口从 4000 改为 6625，加入内置助手、响应头和 Live traffic 视图，并保留了 MCP 服务端。它的关键不在于“让模型替你猜接口”，而在于把一套可控的测试替身留在本机，供人和 Agent 都能读写。
本文以一个订单页面为例，说明何时该用 Mocktail、如何把它接入本地联调，以及把 MCP 接进 Claude Code 时要守住哪些边界。
先定义问题：测试替身也应是可观察的
一个只会返回固定 200 JSON 的 mock 很快会失去价值。真实 UI 经常依赖三类细节：
- 协议细节：状态码、
Content-Type、认证头和路径是否匹配； - 时间细节：加载态、网络延迟、失败重试和取消请求是否正确；
- 运行证据：页面实际请求了什么路径、命中了哪条 mock、服务端究竟回了什么。
Mocktail 的 dashboard 可为 GET、POST、PUT、PATCH、DELETE 定义 endpoint；响应可配置状态码、延迟和自定义 headers，并支持固定响应或按字段生成数据。它还把数据存到 SQLite：本地二进制默认使用操作系统的应用数据目录，Docker 场景则可挂载卷。也就是说，关闭进程不会自动让接口目录消失；需要共享时可导出为 JSON，再导入另一台机器。
这使 mock 不再只是测试代码中的一段字符串，而更像一份可运行、可检查的接口测试资产。对于不想为临时联调启动完整后端的项目，这种“本地服务器 + 可视化目录 + 持久化数据”的组合很合适。它也降低了新成员理解测试前提的成本：与其在聊天记录里寻找“今天该返回什么”，不如让 endpoint 配置、导出文件和页面断言共同说明这个前提。
最小启动：先让服务与数据落点明确
macOS 或 Linux 可以通过项目提供的 Homebrew cask 安装；启动 mocktail 后，dashboard 默认监听在 http://localhost:6625。如果团队已使用容器，README 给出的 Docker 方式如下：
docker run -p 6625:6625 -v "$(pwd)/db:/db" -d hhaluk/mocktail:4.0.2
这里有两个容易忽略的取舍。第一，-v "$(pwd)/db:/db" 是为了把容器里的数据库持久化到当前目录；若删掉挂载，重建容器时很可能丢掉这套 mock。第二，示例镜像标签是文档中的 4.0.2；发布时应按项目的 release 或镜像标签策略确认你准备固定的版本，而不要把“latest”当作可复现测试环境。
启动后打开 dashboard，创建一个 GET /orders/42 endpoint：返回一个订单对象，并为失败路径再创建一个同路径或相关场景的 endpoint。实际接口如何按方法、路径与配置匹配，应以 dashboard 的请求测试结果为准。不要只因为页面显示了假数据，就假定页面真的走到了预期 URL。
用延迟、状态码和响应头测试页面的难分支
Mocktail 4 支持每个 mock 自定义 HTTP status、0–30000ms 响应延迟和 headers。一个实用做法是按“用户可见状态”组织接口，而不是只按资源名组织：
| 要验证的页面状态 | mock 应刻意制造的条件 | 应观察的行为 |
| — | — | — |
| 首次加载 | 正常 200 与固定订单 JSON | 骨架屏结束，关键字段出现 |
| 慢网络 | 为响应增加数秒延迟 | 加载态存在，重复点击不会产生错误状态 |
| 无权限 | 返回 401 或 403 | 登录提示或权限提示出现，敏感内容不闪现 |
| 限流/服务异常 | 返回 429 或 500 | 可理解的错误文案、重试入口或降级逻辑生效 |
| 特殊媒体类型 | 设置 Content-Type: application/problem+json 等 header | 客户端的错误解析走到预期分支 |
这种设计的重点是“可控地制造失败”，不是用随机数据掩盖问题。字段随机化适合发现列表渲染、空值与格式化假设；而回归测试中需要稳定断言的对象，应保持固定。两者混用时，建议把稳定的核心字段冻结，避免每次页面测试都因无关字段变化而抖动。
Mocktail 的 Live traffic 视图可查看命中请求的方法、状态和路径，以及已服务的响应与 headers。每次改完前端代理、base URL 或认证逻辑后，先从这里确认请求是否到达本地服务，再去排查组件状态。这样能避免把“请求根本没发出”误判成“mock 数据不对”。
把 endpoint 目录交给 Agent，但不给它无限权限
Mocktail 提供 npm 包 mocktail-mcp，并在 README 中列出五个 MCP 工具：list_mocks、create_mock、update_mock、delete_mock 和 import_mocks。它们分别对应查看、创建、更新、删除与批量导入 endpoint；这意味着 Agent 可以在本地接口目录内完成准备测试数据的工作。
项目文档给出的 Claude Code 接入方式如下。示例用环境变量保存实例地址和服务 mock 所需的 API key：
claude mcp add mocktail \
-e MOCKTAIL_URL=http://localhost:6625 \
-e MOCKTAIL_API_KEY="${MOCKTAIL_API_KEY}" \
-- npx mocktail-mcp
接入后，更可靠的工作流不是直接让 Agent “创建一批接口然后测试页面”，而是分成四步：
- 先让 Agent 调用
list_mocks，把现有 endpoint 当作当前事实； - 用自然语言明确需要的 method、path、状态码、延迟和响应结构；
- 让它创建或更新后，再次列出目录，确认变更确实存在；
- 运行页面测试，同时在 Live traffic 中核对请求路径与返回状态。
MCP 只负责管理 Mocktail 的接口目录，不会替你验证前端真实行为。因此“Agent 已调用 create_mock”不能作为测试通过的证据。至少还要有浏览器测试、HTTP 请求或应用日志中的一项证据，证明客户端真的消费了预期响应。
认证配置：区分被 mock 的接口与管理接口
Mocktail 有两类不同的保护边界。MOCKTAIL_API_KEY 用于保护被服务的 mock endpoint；MCP 的 MOCKTAIL_API_KEY 会作为 X-API-Key 发送。MOCKTAIL_ADMIN_KEY 则保护 dashboard/管理 API 的 /core/v1/*，也会限制涉及付费模型调用的 AI 功能。dashboard 根路径和 /health 保持开放，便于本地页面加载与健康检查。
这一区分很重要。若你只是让前端模拟“业务 API 需要认证”，设置 MOCKTAIL_API_KEY 即可；若 Mocktail 被部署到共享网络，管理接口也应使用 MOCKTAIL_ADMIN_KEY，避免任何能访问实例的人修改或删除测试接口。不要把 key 写进项目仓库、浏览器代码或截图；容器或远程部署可通过环境变量注入。
内置 AI assistant 的定位也应保持克制：它可在 dashboard 中针对 mock 目录回答问题或创建、更新、删除 endpoint，但依赖你提供的模型 key。项目说明称，桌面/本地模式的 key 存放于操作系统 keychain，且提供商调用由服务端执行；远程或容器部署则需要按文档配置环境变量。无论哪种模式，都应把它当成提高录入效率的工具，而不是替代接口契约审查的权威来源。
从一次性 mock 到可维护的本地契约
Mocktail 最适合的场景是：后端尚未可用、需要稳定复现失败分支、演示环境不应依赖外部 API，或希望 AI Agent 在本机准备测试替身。它不适合替代真实服务的集成测试：数据库约束、鉴权链路、异步任务和第三方服务行为，仍需要在更接近生产的环境中验证。
一个可维护的实践是将 endpoint 导出 JSON 与前端测试用例一起评审：修改接口路径、字段或错误格式时，同时改 mock 与断言；合并前用 Live traffic 复查关键页面的请求；升级到 v4 时特别检查默认端口是否仍指向 6625。这样，mock 从“为了让页面跑起来的临时补丁”变成明确表达客户端假设的开发资产。
Mocktail 的价值最终不是它有多少生成器或按钮，而是让接口假设、失败条件和访问证据在开发者与 Agent 之间共享。先固定边界，再自动化生成；先观察真实请求，再判断 UI 是否正确，联调才不会被一份看似真实的假数据带偏。