API契约测试

前后端协作中的接口漂移问题

前后端分离开发时，最常见的痛点是接口定义不同步：后端改了字段，前端还在用旧结构调接口；或者前端期待某个响应，后端却从未承诺过这个格式。微服务架构下这个问题更严重——一个服务的 schema 变更可能悄悄破坏多个下游消费者。等到联调阶段才发现，修复成本远高于在开发早期拦截。

契约测试的核心思路

契约测试的出发点是把「接口约定」变成可执行、可验证的制品。本技能支持两条主要路径：

• OpenAPI/Swagger 优先：后端先产出 openapi.yaml，前端基于 spec 生成 mock server 和类型定义，后端则用工具验证自身实现与 spec 一致。适合 spec 先行、文档驱动的团队。
• Pact 优先（消费者驱动）：前端先声明「我期望的请求和响应」，生成 Pact 契约文件，后端再回放验证。适合微服务迭代快、消费者数量多的场景。

关键步骤与工具链

1. Mock Server 搭建：Prism 支持 npx @stoplight/prism-cli mock openapi.yaml 零代码启动；需要类型安全时用 openapi-typescript + openapi-msw 生成 handler；需要动态响应、状态切换时切换到 Mockoon 或 WireMock。
2. 契约测试编写：OpenAPI 侧用 @apidevtools/swagger-parser 校验 spec 合法性，用 openapi-changes 检测差异；Pact 侧分别在消费者端定义交互、在提供者端用 pactVerify() 回放验证。
3. CI 集成：PR 中自动校验 spec 格式，对比 base 分支检测 breaking change，通过 Pact broker 管理契约版本。

适用边界

本技能聚焦接口契约层面，不替代以下场景：

• 单服务内部逻辑测试请用 vitest-unit
• 端到端功能测试请用 playwright-e2e

契约测试的价值在于「尽早发现约定偏离」，它不能告诉你业务逻辑是否正确，但能让你在代码合并前就确认接口没有悄悄跑偏。