接口文档与契约测试
说明
接口文档是团队协作的约定，契约测试用于验证接口实现是否符合文档定义，常用 OpenAPI 或 Pact。
面试怎么问
你们项目怎么维护接口文档？
使用 OpenAPI（Swagger）规范定义接口文档，包含：接口路径、请求方法、参数定义、响应结构、错误码。
文档管理方式：代码注解自动生成（保持同步）、独立文档仓库（集中管理）、文档平台（支持在线测试）。
关键是文档与代码同步更新，避免文档过时。
接口变更时怎么保证文档和实现一致？
建立变更管控流程：接口变更先更新文档评审、文档通过后同步开发、开发完成后做契约测试验证。契约测试在 CI 中执行：对比文档定义和实际响应，发现不一致自动报警。还要建立接口版本管理机制，兼容性变更升级小版本，破坏性变更升级大版本。
契约测试是什么，怎么用？
契约测试验证接口提供者和消费者是否符合约定的接口规范。
分为两种：提供者契约测试验证服务端是否符合文档定义。消费者契约测试验证客户端是否能正确处理服务端响应。
工具选择：OpenAPI Validator 用于 REST API，Pact 用于微服务契约测试。
契约测试是接口治理的重要手段。
项目里怎么用
- 用 OpenAPI 或 Swagger 定义接口规范，作为开发和测试的共同参考。
- 在 CI 中做契约测试，拦截不兼容变更，保证文档和实现一致。
- 文档变更时同步更新测试用例和接口断言，避免测试覆盖遗漏。
- 使用文档生成测试用例骨架，提高测试编写效率。
- 建立接口变更通知机制，影响范围可控。
容易答错什么
文档和实现脱节，维护成本高
文档脱节的表现：接口参数变了文档没更新、错误码新增了没记录、响应结构与文档不符。
解决方案：代码注解自动生成文档、契约测试发现不一致、变更流程强制更新文档。
文档准确性直接影响前后端协作效率和测试效率。
不会讲契约测试和功能测试的区别
契约测试关注接口结构是否符合约定，功能测试关注业务逻辑是否正确。
契约测试验证：字段是否存在、类型是否正确、必填是否生效。
功能测试验证：业务规则、边界条件、异常处理。
两者互补，契约测试是功能测试的前提——接口结构都不对，功能测试无法进行。
忽略接口版本管理和兼容性策略
接口变更会影响所有调用方，要有版本管理策略：URL 路径版本化（/v1/api）、请求头版本化、向后兼容原则（新增字段可选、删除字段需要过渡期）。破坏性变更要提前通知、灰度发布、监控影响。版本管理是接口治理的核心能力。