4. 请求与响应结构设计：统一请求格式、响应体规范、错误码体系设计、分页与排序标准

在承运商集成场景中，API 的请求与响应结构是系统间通信的“通用语言”。缺乏统一规范将导致集成方适配成本激增、调试困难、错误处理混乱。本章围绕四个核心维度——统一请求格式、响应体规范、错误码体系、分页与排序标准——建立企业级 RESTful API 契约。

4.1 统一请求格式

所有面向承运商的 API 请求应遵循一致的 HTTP 方法和头部约定，减少集成方的学习成本。

4.2 响应体规范

响应体采用三层封装结构：状态层、数据层、元数据层。所有响应（包括错误）均遵循此契约。

{
  "status": {
    "code": 200,
    "message": "Success",
    "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  },
  "data": {
    // 业务数据对象或数组
  },
  "meta": {
    "timestamp": "2025-03-21T10:30:00Z",
    "apiVersion": "1.0",
    "pagination": { }  // 仅分页响应时出现
  }
}

4.3 错误码体系设计

错误码采用 5 位数字分段编码：前 3 位对应 HTTP 状态码大类，后 2 位为业务细分码。所有错误响应必须包含 errors 数组，提供可操作的错误详情。

{
  "status": {
    "code": 42203,
    "message": "Validation Failed",
    "requestId": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  },
  "data": null,
  "meta": {
    "timestamp": "2025-03-21T10:30:05Z",
    "apiVersion": "1.0"
  },
  "errors": [
    {
      "field": "shipment.weight",
      "code": "INVALID_VALUE",
      "message": "Weight must be between 0.1 and 50000 kg"
    },
    {
      "field": "shipment.dimensions.length",
      "code": "MISSING_REQUIRED",
      "message": "Length is required when volume weight is calculated"
    }
  ]
}

4.4 分页与排序标准

所有列表查询接口必须支持统一的分页和排序参数，避免每个接口各自定义 page、limit、offset 等混乱命名。

4.4.1 请求参数

GET /api/v1/shipments?page=2&size=50&sort=status:asc,createdAt:desc

4.4.2 响应分页元数据

"pagination": {
  "page": 2,
  "size": 50,
  "totalElements": 1234,
  "totalPages": 25,
  "hasNext": true,
  "hasPrevious": true
}

4.4.3 排序语法

sort 参数格式：字段名:方向，多个排序条件用逗号分隔。方向仅支持 asc 或 desc。允许排序的字段必须在 API 文档中显式声明，避免对未索引字段排序导致性能问题。

4.5 实战案例：运单列表查询接口

以下是一个完整的请求-响应示例，展示上述规范在真实承运商集成中的落地效果。

请求示例

GET /api/v1/shipments?page=1&size=20&sort=createdAt:desc
Headers:
  Content-Type: application/json
  Accept: application/json
  X-Request-ID: f47ac10b-58cc-4372-a567-0e02b2c3d479
  X-Timestamp: 2025-03-21T10:30:00Z
  Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

响应示例

{
  "status": {
    "code": 200,
    "message": "Success",
    "requestId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
  },
  "data": [
    {
      "shipmentId": "SHP202503210001",
      "status": "IN_TRANSIT",
      "weight": 120.5,
      "origin": "CNHKG",
      "destination": "USLAX",
      "createdAt": "2025-03-21T08:15:00Z"
    }
  ],
  "meta": {
    "timestamp": "2025-03-21T10:30:01Z",
    "apiVersion": "1.0",
    "pagination": {
      "page": 1,
      "size": 20,
      "totalElements": 156,
      "totalPages": 8,
      "hasNext": true,
      "hasPrevious": false
    }
  }
}