4. Redis错误码体系：服务端错误、客户端错误、超时错误、连接错误、数据错误

在搜索服务的契约测试中，Redis 错误码是断言通信质量的核心指标。错误码体系可划分为五大类：服务端错误、客户端错误、超时错误、连接错误、数据错误。每一类错误在契约测试中都有对应的断言策略和阈值定义。

4.1 错误码分类总览

下表列出了五类错误码的典型场景、Redis 原生错误前缀以及契约测试中的断言关注点：

4.2 错误码分类与契约断言流程

下图展示了搜索服务在契约测试中如何根据 Redis 错误码类别进行断言分支处理：

4.3 服务端错误与客户端错误

服务端错误 通常由 Redis 实例的内部状态引发，例如内存达到 maxmemory 限制、AOF 重写失败或主从复制链路中断。在契约测试中，服务端错误应触发重试断言，验证搜索服务是否在指定次数内恢复。

客户端错误 则源于请求本身的问题，如命令语法错误、操作了错误的数据类型（-WRONGTYPE）或认证信息缺失（-NOAUTH）。契约测试应断言客户端错误不触发重试，而是直接返回 4xx 或 5xx 响应。

// 服务端错误：允许重试 3 次
assertRedisErrorRetry("ERR OOM", 3, 100);

// 客户端错误：禁止重试，直接返回
assertRedisErrorNoRetry("WRONGTYPE Operation against a key holding the wrong kind of value");

4.4 超时错误与连接错误

超时错误 在搜索服务中尤为关键。当 Redis 命令执行时间超过客户端配置的 timeout 阈值时，会抛出 RedisTimeoutException。契约测试需要断言：

• 超时阈值是否与搜索接口的 SLA 一致（通常 ≤ 50ms）。
• 超时后是否触发熔断器（Circuit Breaker）进入 OPEN 状态。
• 熔断恢复后的半开探测请求是否正常。

连接错误 包括连接池耗尽、网络分区、DNS 解析失败等。契约测试应验证：

• 连接池最大连接数是否与搜索服务的并发模型匹配。
• 连接断开后是否在预期时间内发起重连。
• 重连失败后是否返回降级数据（如本地缓存）。

4.5 数据错误

数据错误 涵盖数据损坏、序列化/反序列化失败、缓存穿透导致的数据不一致。在搜索服务中，数据错误通常表现为：

• 从 Redis 读取的搜索结果无法反序列化为预期的 Protobuf 结构。
• 缓存键的 TTL 设置错误导致数据提前过期。
• Redis 处于 LOADING 状态（持久化恢复中）时拒绝服务。

契约测试应断言数据错误场景下的降级策略：是否返回空结果、是否回查数据库、是否记录告警日志。

4.6 错误码断言策略对比

4.7 契约测试中的错误码断言实现

以下是一个基于 Java 的契约测试片段，展示如何针对不同 Redis 错误码进行断言：

@Test
public void testRedisErrorCodeAssertion() {
    // 模拟服务端错误
    when(redisClient.get("search:query:test"))
        .thenThrow(new RedisException("ERR OOM command not allowed when used memory > 'maxmemory'"));

    SearchResponse response = searchService.search("test");
    assertThat(response.getStatus()).isEqualTo(503);
    assertThat(response.getRetryCount()).isLessThanOrEqualTo(3);

    // 模拟客户端错误
    when(redisClient.get("search:query:test"))
        .thenThrow(new RedisException("WRONGTYPE Operation against a key holding the wrong kind of value"));

    response = searchService.search("test");
    assertThat(response.getStatus()).isEqualTo(400);
    assertThat(response.getRetryCount()).isEqualTo(0);

    // 模拟超时错误
    when(redisClient.get("search:query:test"))
        .thenThrow(new RedisTimeoutException("Command timed out after 50ms"));

    response = searchService.search("test");
    assertThat(response.getStatus()).isEqualTo(504);
    assertThat(response.getCircuitBreakerState()).isEqualTo("OPEN");
}