4、Redis接口契约定义：如何定义Redis的SET/GET/DELETE/HGETALL等核心操作的契约规范。

在契约测试驱动Redis迁移的体系中，接口契约是连接旧集群与新集群、测试用例与业务代码的“法律条文”。契约不是简单的API文档，而是一份可执行、可验证的规范，它精确描述了每个Redis命令的输入参数、预期输出、异常场景以及数据格式约束。本章将围绕SET、GET、DELETE、HGETALL四个最核心的操作，定义一套标准化的契约模板。

4.1 契约结构总览

每个Redis操作的契约由以下五个维度构成：

4.2 SET 操作契约定义

SET 是Redis中最基础的写入操作，其契约定义直接影响数据一致性与过期策略的验证。

{
  "operation": "SET",
  "version": "1.0",
  "input": {
    "key": {
      "type": "string",
      "encoding": "UTF-8",
      "length": { "min": 1, "max": 256 },
      "required": true
    },
    "value": {
      "type": "string",
      "encoding": "UTF-8",
      "length": { "min": 0, "max": 536870912 },
      "required": true
    },
    "expiration": {
      "type": "integer",
      "unit": "seconds",
      "range": { "min": 1, "max": 31536000 },
      "required": false,
      "default": -1
    },
    "nx_xx": {
      "type": "enum",
      "values": ["NX", "XX", null],
      "required": false
    }
  },
  "output": {
    "success": {
      "type": "simple_string",
      "value": "OK"
    },
    "null_reply": {
      "condition": "NX/XX 条件不满足",
      "type": "null_bulk_string"
    }
  },
  "errors": [
    {
      "type": "WRONGTYPE",
      "message": "WRONGTYPE Operation against a key holding the wrong kind of value",
      "trigger": "key 已存在且类型非 string"
    },
    {
      "type": "ERR",
      "message": "ERR value is not an integer or out of range",
      "trigger": "expiration 参数格式错误"
    }
  ],
  "side_effects": {
    "overwrite": true,
    "ttl_reset": true,
    "aof_log": true,
    "cluster_route": "key hash slot"
  }
}

4.3 GET 操作契约定义

GET 是读取操作的基石，其契约重点在于“键不存在”与“类型不匹配”两种异常路径的精确区分。

{
  "operation": "GET",
  "version": "1.0",
  "input": {
    "key": {
      "type": "string",
      "encoding": "UTF-8",
      "length": { "min": 1, "max": 256 },
      "required": true
    }
  },
  "output": {
    "success": {
      "type": "bulk_string",
      "encoding": "UTF-8",
      "max_length": 536870912
    },
    "key_not_found": {
      "type": "null_bulk_string",
      "value": "nil"
    }
  },
  "errors": [
    {
      "type": "WRONGTYPE",
      "message": "WRONGTYPE Operation against a key holding the wrong kind of value",
      "trigger": "key 已存在且类型非 string"
    }
  ],
  "side_effects": {
    "read_only": true,
    "ttl_no_change": true,
    "cluster_route": "key hash slot"
  }
}

4.4 DELETE 操作契约定义

DELETE 的契约特殊性在于：返回值是被删除键的数量，而非布尔值。迁移后若新集群对不存在的键返回 false 而非 0，将直接破坏依赖计数逻辑的业务代码。

{
  "operation": "DEL",
  "version": "1.0",
  "input": {
    "keys": {
      "type": "array_of_string",
      "min_items": 1,
      "max_items": 1000,
      "required": true
    }
  },
  "output": {
    "success": {
      "type": "integer",
      "range": { "min": 0, "max": 1000 },
      "description": "实际被删除的键数量"
    }
  },
  "errors": [
    {
      "type": "WRONGTYPE",
      "message": "WRONGTYPE Operation against a key holding the wrong kind of value",
      "trigger": "任一 key 类型不支持删除（极少出现）"
    }
  ],
  "side_effects": {
    "key_removed": true,
    "aof_log": true,
    "cluster_route": "multi-key 需在相同 slot"
  }
}

4.5 HGETALL 操作契约定义

HGETALL 返回哈希表的所有字段与值，其契约难点在于空哈希与不存在键的区分，以及返回数组的排列顺序保证。

{
  "operation": "HGETALL",
  "version": "1.0",
  "input": {
    "key": {
      "type": "string",
      "encoding": "UTF-8",
      "length": { "min": 1, "max": 256 },
      "required": true
    }
  },
  "output": {
    "success": {
      "type": "array",
      "item_type": "bulk_string",
      "ordering": "field1, value1, field2, value2, ...",
      "description": "空哈希返回空数组 []"
    },
    "key_not_found": {
      "type": "empty_array",
      "value": "[]",
      "description": "键不存在也返回空数组，与空哈希无法区分"
    }
  },
  "errors": [
    {
      "type": "WRONGTYPE",
      "message": "WRONGTYPE Operation against a key holding the wrong kind of value",
      "trigger": "key 已存在且类型非 hash"
    }
  ],
  "side_effects": {
    "read_only": true,
    "ttl_no_change": true,
    "cluster_route": "key hash slot"
  }
}

4.6 契约定义的SVG流程：从命令到契约验证

下图展示了如何将一条Redis命令转化为契约定义，并最终用于迁移冒烟测试的完整链路：

4.7 契约定义的常见误区与避坑

• 误区一：契约只定义成功路径。 迁移后80%的兼容性问题出现在异常路径（如类型错误、键不存在、参数越界）。每个操作必须至少定义2种异常场景。
• 误区二：忽略数据编码。 Redis内部使用二进制安全字符串，但客户端可能使用不同的编码（UTF-8、GBK）。契约必须明确指定编码格式，否则迁移后中文或特殊字符可能出现乱码。
• 误区三：将集群路由视为客户端责任。 契约中必须包含 cluster_route 字段，明确标识该操作是否依赖key hash slot。多key操作（如DEL批量）在集群模式下可能触发CROSSSLOT错误，契约应提前声明。
• 误区四：混淆“空结果”与“错误”。 GET返回nil不是错误，HGETALL返回空数组也不是错误。契约必须严格区分 output 中的空结果与 errors 中的异常，避免冒烟测试误报。

4.8 契约定义的版本管理策略

在Redis迁移过程中，旧集群与新集群可能运行不同版本的Redis（如6.x vs 7.x），某些命令的行为存在细微差异。契约必须引入版本号管理：