3. 契约概念详解：数据契约、接口契约、版本契约的定义与区别

在缓存契约版本校验体系中，“契约”并非单一概念，而是由数据契约、接口契约和版本契约三个层次共同构成的约束体系。三者分别关注缓存数据的结构、存取行为以及变更演进，理解其定义与区别是实施契约校验的基础。

3.1 数据契约（Data Contract）

数据契约是缓存中存储的数据结构的静态定义。它规定了缓存值的字段名称、类型、嵌套结构、默认值以及可选/必填约束。数据契约通常以 JSON Schema、Protobuf 或 Avro 等模式描述语言表达。

3.2 接口契约（Interface Contract）

接口契约定义了缓存存取的行为规范，包括键的命名规则、序列化/反序列化方式、过期策略、缓存模式（Cache-Aside / Read-Through）以及异常处理约定。接口契约确保生产者和消费者在交互方式上达成一致。

• 键命名规范：如 user:{userId}:profile 的分段式命名，避免冲突。
• 序列化协议：JSON、MessagePack、Protobuf 等，必须统一。
• TTL 策略：固定过期时间、滑动过期时间或永不过期。
• 错误语义：缓存 Miss 返回 null 还是抛出异常？
• 批量操作：MGET/MSET 的键顺序与返回值映射规则。

// 接口契约示例（伪代码）
interface UserCacheContract {
  // 键模式: user:{userId}:profile
  // 序列化: JSON (UTF-8)
  // TTL: 3600 秒 (滑动)
  // 缓存 Miss: 返回 null，不抛异常
  
  @Cacheable(key = "user:#userId:profile", ttl = 3600, sliding = true)
  UserProfile getUserProfile(String userId);
  
  @CacheEvict(key = "user:#userId:profile")
  void evictUserProfile(String userId);
}

3.3 版本契约（Version Contract）

版本契约是数据契约和接口契约随时间演进的版本化约束。它定义了当缓存数据结构或存取行为发生变化时，如何通过版本号标识、兼容性规则以及迁移策略来保证系统平滑过渡。

3.4 三者关系与区别

三种契约在缓存系统中扮演不同角色，但相互依赖。数据契约是基础，接口契约是行为约束，版本契约是演进保障。下面通过对比表格和结构图进一步厘清。

3.5 实际场景中的契约分层

以一个用户信息缓存为例，展示三种契约如何分层作用：

• 数据契约：定义 UserProfile 包含 userId（string）、nickname（string）、level（int32）、tags（string array）。
• 接口契约：键格式为 user:profile:{userId}，序列化使用 JSON，TTL 为 1800 秒，缓存 Miss 返回 null。
• 版本契约：当前版本 v3，新增 vipExpireTime 字段为向前兼容变更，旧版本消费者仍可读取，但新版本消费者可获取额外信息。