4. API 响应格式规范：RESTful API 响应体通用结构设计原则

在数据库缓存回归冒烟测试中，契约测试的核心校验对象之一便是 API 响应体的结构。一个统一、可预测的响应格式能够大幅降低客户端解析成本，并使得缓存中间件（如 Redis、CDN）能够稳定地缓存和回填数据。本节将定义 RESTful API 响应体的通用结构设计原则，作为后续契约校验的基准。

4.1 通用响应体三层结构

所有 API 响应体应遵循“状态-消息-数据”三层结构，确保客户端在任何场景下都能通过固定路径获取关键信息。该结构适用于成功响应、业务错误响应及系统异常响应。

4.2 响应体结构设计原则

为保证缓存层能够正确序列化/反序列化，且契约测试能够稳定匹配，响应体设计需遵循以下五项核心原则：

1. 字段命名一致性： 全系统统一使用小驼峰（camelCase）命名，禁止混用下划线（snake_case）或短横线（kebab-case）。例如：userId 而非 user_id。
2. 数据类型严格化： code 必须为整型，message 必须为字符串，data 必须为对象或数组。禁止将 code 定义为字符串类型。
3. 空值显式化： 当 data 无内容时，必须返回 null 而非空字符串 "" 或缺失该字段。缓存层应能区分 null 与 undefined。
4. 错误详情可扩展： 业务错误时，data 字段可包含 errors 子对象，用于携带字段级校验失败信息。该子对象结构也需在契约中明确定义。
5. 版本兼容性： 响应体结构一旦发布，禁止删除已有字段。新增字段必须为可选（optional），且需在契约中标注 since 版本号。

4.3 成功与失败响应示例

以下代码展示了符合通用结构规范的成功响应与业务失败响应。注意 data 字段在不同场景下的形态差异。

// 成功响应：查询用户信息
{
  "code": 0,
  "message": "success",
  "data": {
    "userId": 1024,
    "userName": "zhangsan",
    "email": "zhangsan@example.com"
  }
}

// 业务失败响应：用户不存在
{
  "code": 1001,
  "message": "user not found",
  "data": null
}

// 参数校验失败响应：带错误详情
{
  "code": 4000,
  "message": "validation failed",
  "data": {
    "errors": [
      {
        "field": "email",
        "message": "email format is invalid"
      }
    ]
  }
}

4.4 响应体结构契约校验流程

在缓存回归冒烟测试中，契约测试工具（如 Pact、Spring Cloud Contract）会针对响应体结构生成校验规则。下图展示了从契约定义到缓存回填校验的完整流程。

4.5 缓存场景下的特殊约束

当响应体经过缓存层时，需额外关注以下三个约束，否则可能导致缓存污染或客户端解析异常：

• 序列化一致性： 缓存层（如 Redis）必须使用与 API 网关相同的 JSON 序列化库（如 Jackson、Gson），避免因字段排序、浮点数精度差异导致契约校验失败。
• TTL 与 message 字段： 缓存过期后回填时，message 字段必须从源服务重新获取，禁止使用固定字符串（如 "cached response"）覆盖原始消息。
• 批量接口的 data 结构： 对于返回列表的接口，data 必须为数组类型，即使列表为空也应返回 [] 而非 null。契约中需明确标注 data 的数组元素类型。

4.6 响应体结构对比：直连 vs 缓存

下表对比了直连数据库查询与缓存回填两种场景下响应体结构的差异，帮助测试人员快速定位缓存引入的潜在问题。

4.7 契约测试中的响应体结构断言

在 Pact 或 Spring Cloud Contract 中，针对响应体结构的断言应覆盖以下三个层级：

// Pact 消费者端契约示例（Groovy DSL）
Interaction {
  given: "用户存在且缓存已预热"
  uponReceiving: "查询用户信息"
  withRequest {
    method: "GET"
    path: "/api/users/1024"
    headers { accept: "application/json" }
  }
  willRespondWith {
    status: 200
    headers { contentType: "application/json" }
    body {
      // 第一层：code 必须为整型且值为 0
      code: integer(0)
      // 第二层：message 必须为非空字符串
      message: nonEmptyString()
      // 第三层：data 必须为对象且包含 userId
      data: {
        userId: integer(1024)
        userName: string("zhangsan")
        email: string("zhangsan@example.com")
      }
    }
  }
}