4. 接口稳定性定义：幂等性、健壮性、向后兼容性、语义版本化与契约的关系
接口稳定性是微服务集成环境中衡量契约质量的核心指标。一个不稳定的接口会导致消费者频繁适配、回放失败、数据不一致甚至生产故障。本章从四个维度——幂等性、健壮性、向后兼容性和语义版本化——拆解稳定性与契约之间的内在关系，并给出可量化的判定标准。
4.1 幂等性：契约对重复请求的承诺
幂等性指同一请求被多次执行时，系统状态与执行一次的结果完全一致。在契约测试中，幂等性是接口契约必须显式声明的属性，尤其对回放场景至关重要——回放可能因网络重试、消息重复投递而触发多次调用。
| HTTP 方法 | 天然幂等 | 契约中需额外约束 |
|---|---|---|
| GET | 是 | 无副作用，查询结果可缓存 |
| PUT | 是 | 全量替换，请求体必须包含完整资源 |
| DELETE | 是 | 重复删除返回相同状态码（如 204/404） |
| POST | 否 | 需引入幂等键（Idempotency-Key） |
| PATCH | 视实现而定 | 需使用条件更新或版本号 |
契约实践要点：在 Pact 或 Spring Cloud Contract 中，幂等性应作为接口元数据写入契约文件。例如，为 POST 接口声明
idempotencyKey: true，并在消费者测试中验证幂等键的传递逻辑。
4.2 健壮性：契约对异常输入的防御
健壮性要求接口在接收非法、边界或恶意输入时，仍能返回明确的错误响应，而不会崩溃或产生不可恢复的状态。契约测试通过定义负面测试用例来验证健壮性。
- 必填字段缺失：契约中声明字段的 required 属性，提供者返回 400 + 错误码。
- 数据类型越界：例如 age 字段接受 0-150，契约中定义 range 约束。
- 格式校验：email 字段必须符合正则，契约中嵌入 pattern。
- 空值/空字符串：契约明确允许或禁止 null 和空串。
契约健壮性检查清单：
- 每个请求参数是否有类型、长度、枚举值约束？
- 是否定义了至少一种错误响应（400/422/500）的契约？
- 消费者测试是否覆盖了至少一个负面输入？
- 提供者是否对未知字段采取了“忽略而非崩溃”策略？
4.3 向后兼容性：契约演进的底线
向后兼容性指接口升级后，已有消费者无需修改代码仍能正常工作。契约测试是检测兼容性断裂的第一道防线。以下表格列出常见变更及其兼容性影响：
| 变更类型 | 示例 | 是否向后兼容 | 契约检测方式 |
|---|---|---|---|
| 新增可选字段 | 响应体增加 middleName |
是 | 消费者契约不引用该字段即可 |
| 新增必填字段 | 请求体增加必填 phone |
否 | 旧消费者契约缺少该字段，验证失败 |
| 字段类型收紧 | id 从 string 改为 integer |
否 | 类型匹配失败 |
| 删除字段 | 移除响应中的 discount |
否 | 消费者契约仍期望该字段 |
| URL 路径变更 | /v1/users → /v2/users |
否 | 路径不匹配 |
| 枚举值扩展 | status 新增 "pending" | 是 | 消费者未枚举所有值时可兼容 |
常见误区：仅依赖语义版本号（major/minor/patch）判断兼容性是不够的。契约测试必须实际运行消费者验证，因为“理论上兼容”的变更（如新增可选字段）可能因消费者代码的隐式依赖而断裂。
4.4 语义版本化：契约版本的生命周期管理
语义版本化（SemVer）为接口演进提供版本号规则，契约测试则确保版本号与实际变更一致。推荐在契约文件中显式声明 version 字段，并与 API 版本号对齐。
| 版本号 | 变更含义 | 契约兼容性要求 | 消费者升级策略 |
|---|---|---|---|
| MAJOR（1.x → 2.0） | 不兼容的 API 变更 | 旧契约全部失效，需重新协商 | 必须修改消费者代码 |
| MINOR（1.0 → 1.1） | 向后兼容的新功能 | 旧契约仍可通过，新契约可选 | 消费者可选择性升级 |
| PATCH（1.0.0 → 1.0.1） | 向后兼容的缺陷修复 | 契约不变或仅内部实现调整 | 无需修改消费者代码 |
4.5 四维稳定性与契约的映射关系
将上述四个维度统一映射到契约测试的各个阶段，形成可执行的稳定性保障体系：
| 稳定性维度 | 契约中的体现 | 消费者测试 | 提供者验证 | 回放场景影响 |
|---|---|---|---|---|
| 幂等性 | 幂等键声明、方法幂等标记 | 验证幂等键传递 | 验证重复请求返回一致 | 防止回放重复执行导致数据错误 |
| 健壮性 | 参数约束、错误响应契约 | 发送边界/非法输入 | 返回标准错误结构 | 回放异常输入时提供者可优雅处理 |
| 向后兼容性 | 字段可选性、类型不变性 | 旧契约在新版本上运行 | 不破坏已有契约 | 回放历史请求时接口仍可理解 |
| 语义版本化 | 契约文件中的 version 字段 | 按版本选择契约 | 按版本暴露接口 | 回放时精确匹配版本号 |
最佳实践：在 CI/CD 流水线中，每次提供者部署前自动执行“兼容性检查”——加载所有消费者契约的最新版本，若发现不兼容变更，则阻断发布并要求升级 MAJOR 版本。这一机制将稳定性从“口头承诺”转化为“代码强制”。