4. 缓存一致性闭环接口设计原则

在构建 Elasticsearch 缓存一致性闭环时，接口设计是保障数据正确性与系统稳定性的核心防线。本章聚焦三大设计原则：接口幂等性、最终一致性 vs 强一致性选择、读己之写（Read-Your-Writes）保证策略。这些原则共同决定了缓存与索引之间数据流动的可靠程度。

4.1 接口幂等性设计

幂等性（Idempotency）是指同一个请求无论执行一次还是多次，对系统状态产生的影响相同。在缓存一致性闭环中，网络重试、消息重复消费、客户端超时重发等场景频繁发生，非幂等接口会导致缓存与 ES 索引数据不一致。

4.1.1 幂等性实现策略对比

4.1.2 幂等性接口设计示例

以下是一个基于 请求唯一 ID + ES 乐观锁 的幂等写入接口伪代码：

// 幂等写入接口
POST /api/cache-consistent/write
{
  "idempotency_key": "req-20250321-abc123",
  "doc_id": "user_1001",
  "data": { "name": "张三", "age": 30 },
  "expected_seq_no": 5,
  "expected_primary_term": 1
}

// 服务端处理逻辑
1. 检查 idempotency_key 是否已处理（Redis SETNX）
2. 若已处理 → 直接返回上次结果（幂等）
3. 若未处理 → 执行 ES 条件更新（if_seq_no + if_primary_term）
4. 更新成功 → 写入缓存（设置 TTL）
5. 记录 idempotency_key 到 Redis（TTL = 24h）
6. 返回成功响应

4.2 最终一致性 vs 强一致性选择

缓存一致性闭环需要在数据正确性与系统可用性之间做权衡。Elasticsearch 本身是近实时（NRT）系统，写入后默认 1 秒才可搜索，这决定了缓存层无法做到绝对的强一致性。

4.2.1 一致性模型对比

4.2.2 一致性选择决策树

在实际项目中，建议按以下决策路径选择一致性模型：

1. 业务是否允许短暂不一致？
   • 是 → 走最终一致性（默认路径）
   • 否 → 进入下一步判断
2. 不一致是否会导致资损或安全风险？
   • 是 → 必须强一致性（如支付、库存）
   • 否 → 进入下一步判断
3. 用户是否能接受等待？
   • 是 → 使用 ?refresh=wait_for 同步等待
   • 否 → 使用最终一致性 + 读己之写补偿

4.3 读己之写（Read-Your-Writes）保证策略

读己之写（RYW）是指：用户写入数据后，立即读取时能看到自己刚写入的内容。这是最终一致性系统中最基本的一致性保证，也是缓存一致性闭环必须解决的核心问题。

4.3.1 RYW 实现架构

以下 SVG 图展示了基于 写后标记 + 缓存穿透 的 RYW 保证策略：

4.3.2 RYW 保证策略详解

RYW 的核心思路是：写操作留下“痕迹”，读操作根据痕迹决定数据来源。常见实现策略如下：

4.3.3 推荐实现：写后标记 + 缓存穿透

这是生产环境中最常用的 RYW 策略，兼顾性能与一致性。以下是关键实现细节：

// 写操作：写入 ES + 设置写后标记
public void writeWithRYW(String userId, String docId, Map<String, Object> data) {
    // 1. 幂等写入 ES（使用 idempotency_key）
    esClient.index(docId, data);
    
    // 2. 设置写后标记（TTL = 5s，覆盖 ES refresh 窗口）
    redisClient.setex("ryw:" + userId + ":" + docId, 5, "1");
    
    // 3. 异步更新缓存（非关键路径）
    cacheClient.asyncSet(docId, data, 300);
}

// 读操作：检查标记 + 决定数据来源
public Map<String, Object> readWithRYW(String userId, String docId) {
    // 1. 检查写后标记
    boolean hasWritten = redisClient.exists("ryw:" + userId + ":" + docId);
    
    if (hasWritten) {
        // 2. 有标记 → 直接查 ES（保证读到最新）
        return esClient.get(docId);
    } else {
        // 3. 无标记 → 读缓存（高性能）
        Map<String, Object> cached = cacheClient.get(docId);
        if (cached != null) {
            return cached;
        }
        // 4. 缓存未命中 → 查 ES 并回填缓存
        Map<String, Object> data = esClient.get(docId);
        cacheClient.set(docId, data, 300);
        return data;
    }
}

4.4 三种原则的协同关系

接口幂等性、一致性模型选择、RYW 保证策略三者并非独立，而是构成一个完整的闭环：