4. 接口契约设计原则：什么是接口契约、契约驱动开发（CDD）、接口的幂等性与一致性要求

在构建 Redis 缓存读写分离架构时，客户端与缓存层、缓存层与数据库之间的交互不能依赖“默契”或“文档注释”。必须通过接口契约明确定义输入、输出、行为约束与异常处理，才能让分布式系统中的多个服务独立演进、并行开发、自动验证。本节将深入讲解接口契约的核心概念、契约驱动开发（CDD）的落地方式，以及缓存接口中至关重要的幂等性与一致性要求。

4.1 什么是接口契约

接口契约（Interface Contract）是服务提供方与消费方之间的一份技术协议，它精确描述了：

• 请求格式：方法名、参数类型、参数范围、必填/可选字段。
• 响应格式：成功返回结构、错误码、异常类型。
• 行为语义：同步/异步、超时阈值、重试策略、缓存穿透处理方式。
• 质量属性：幂等性保证、一致性级别、吞吐量承诺。

4.2 契约驱动开发（CDD）

契约驱动开发（Contract-Driven Development, CDD）是一种先定义契约、再实现服务的开发范式。在 Redis 读写分离项目中，CDD 能够有效避免缓存层与业务层之间的“接口错位”。

4.2.1 CDD 核心流程

1. 定义契约：使用 OpenAPI / gRPC proto / Thrift IDL 编写接口规范。
2. 生成桩代码：服务端生成接口骨架，客户端生成调用桩。
3. 契约测试：双方基于契约编写 mock 测试，验证请求/响应格式。
4. 并行开发：缓存层与业务层可独立开发，无需等待对方完成。
5. 持续验证：CI 流水线自动校验实现是否偏离契约。

4.3 接口的幂等性要求

幂等性（Idempotency）是指同一个请求无论执行一次还是多次，对系统状态产生的影响相同。在 Redis 缓存读写分离中，以下场景必须保证幂等：

• 缓存写入：重复的 SET 请求不应导致数据错乱。
• 缓存删除：重复的 DEL 请求不应引发缓存击穿。
• 缓存更新：带版本号的 CAS 操作必须保证原子性。

4.3.1 幂等性实现策略

4.4 接口的一致性要求

一致性（Consistency）定义了缓存与数据库之间数据同步的即时性与准确性。在读写分离架构中，一致性级别直接影响接口契约的设计：

4.4.1 一致性级别对比

4.4.2 一致性契约示例

以下是一个支持最终一致性的缓存读取接口契约片段：

// 契约定义：CacheGetV2
// 一致性级别：最终一致性（允许最多 5 秒延迟）
// 幂等性：天然幂等（只读操作）

message CacheGetRequest {
  required string key = 1;
  optional int32 timeout_ms = 2;  // 默认 200ms
}

message CacheGetResponse {
  optional bytes data = 1;
  required bool cache_hit = 2;
  optional int64 version = 3;     // 数据版本号
  optional int32 stale_seconds = 4; // 数据已过时秒数
  required int32 status_code = 5;  // 0: 成功, 1001: 穿透, 1002: 超时
}

4.5 幂等性与一致性的协同设计

在同一个缓存接口中，幂等性与一致性并非独立维度，而是相互制约：

• 强一致性 + 幂等写入：使用 Lua 脚本在 Redis 中原子执行版本校验与数据更新，保证写操作幂等且立即生效。
• 最终一致性 + 幂等删除：删除缓存时使用 DEL 命令（天然幂等），配合延迟双删策略保证最终一致。
• 读写一致性 + 幂等重试：写后立即读主库，若缓存未命中则重试，重试时携带幂等键防止重复写库。