RESTful API响应结构设计

根据 RESTful API 的最佳实践，以下是针对单条数据、列表数据和错误信息的推荐响应结构设计：

一、单条数据返回结构

适用场景：获取或操作单个资源（如 GET /users/{id} 或 POST /users）

{
  "code": 200,          // 自定义业务状态码（可选，也可依赖 HTTP 状态码）
  "message": "success", // 可读的成功消息（可选）
  "data": {             // 核心数据包裹在 data 字段
    "id": "123",
    "name": "John",
    "email": "john@example.com"
  }
}

二、列表数据返回结构

适用场景：获取分页或列表数据（如 GET /users）

{
  "code": 200,
  "message": "success",
  "data": {                // 包裹列表和分页信息
    "items": [             // 数据列表
      { "id": "1", "name": "John" },
      { "id": "2", "name": "Alice" }
    ],
    "pagination": {        // 分页元数据
      "current_page": 1,
      "per_page": 10,
      "total_items": 100,
      "total_pages": 10
    }
  }
}

三、错误信息返回结构

适用场景：请求失败时（如参数错误、权限问题）

{
  "code": 40001,          // 自定义错误码（如 40001 表示参数无效）
  "message": "Invalid input", // 概括性错误描述
  "errors": [             // 具体错误细节（可选）
    {
      "field": "email",
      "message": "Must be a valid email address"
    }
  ],
  "trace_id": "abc-123"   // 唯一追踪 ID（便于后端排查）
}

关键设计原则

1. 一致性

   • 所有成功响应使用 data 包裹核心数据，错误响应使用 error 或直接包含错误字段。
   • 保持字段命名（如 code/message）、结构层级统一。

2. HTTP 状态码

   • 成功：200 OK（通用成功）、201 Created（资源创建）。
   • 错误：400 Bad Request（客户端错误）、404 Not Found、500 Internal Server Error。

3. 分页标准化

   • 使用 current_page + per_page 或 offset + limit 风格，提供足够的分页元数据。

4. 错误可读性

   • 错误消息需对开发者友好，避免暴露敏感信息（如数据库错误）。
   • 使用 errors 数组细化表单验证类错误的字段级问题。

5. 扩展性

   • 通过 data 包裹未来可能新增的元数据（如 data: { item: {}, metadata: {} }）。

示例：完整请求流程

1. 成功获取单个用户

   HTTP/1.1 200 OK
   {
     "data": { "id": "123", "name": "John" }
   }
   

2. 创建用户失败（验证错误）

   HTTP/1.1 400 Bad Request
   {
     "code": "VALIDATION_ERROR",
     "message": "Request contains invalid data",
     "errors": [
       { "field": "email", "message": "Invalid email format" }
     ]
   }
   

3. 获取用户列表（分页）

   HTTP/1.1 200 OK
   {
     "data": {
       "items": [ ... ],
       "pagination": { "current_page": 1, "total_items": 50 }
     }
   }
   

附加建议

• 版本控制：在 URL（/v1/users）或 Header 中添加 API 版本。
• 文档：提供 Swagger/OpenAPI 文档，明确每个端点的响应格式。
• HATEOAS：高级场景可在响应中添加 links 字段引导客户端操作（如 "links": [{ "rel": "next", "href": "/users?page=2" }]）。