JSON 格式

如今的 RESTful API，传输数据时最常见、也最主流的格式，就是 JSON（Ja vaScript Object Notation）。

JSON 可以理解成数据世界里的“通用语言”，表达直观，读起来也很轻松。

JSON 基础语法

{
  "name": "张三",
  "age": 25,
  "email": "zhangsan@example.com",
  "hobbies": ["阅读", "游泳", "编程"],
  "address": {
    "city": "北京",
    "district": "朝阳区"
  },
  "isActive": true
}

JSON 的特点

• 表达方式直观，便于阅读。
• 结构清晰，适合接口数据传输。
• 在 RESTful API 中应用非常广泛。

请求格式

常见请求方式中，GET 和 POST 最具代表性。

GET 请求示例

// 请求
GET /api/users/123
Accept: application/json
// 响应
{
  "id": 123,
  "name": "张三",
  "email": "zhangsan@example.com",
  "createdAt": "2024-01-15T08:30:00Z"
}

POST 请求示例

// 请求
POST /api/users
Content-Type: application/json
{
  "name": "李四",
  "email": "lisi@example.com",
  "password": "securePassword123"
}
// 响应
{
  "id": 124,
  "name": "李四",
  "email": "lisi@example.com",
  "createdAt": "2024-01-15T09:00:00Z",
  "message": "用户创建成功"
}

响应结构设计

为了便于前后端协作，响应结构通常会保持统一。

统一的响应格式

{
  "success": true,
  "data": {
    "id": 123,
    "name": "张三"
  },
  "message": "操作成功",
  "timestamp": "2024-01-15T08:30:00Z"
}

错误响应格式

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "输入数据验证失败",
    "details": [
      {
        "field": "email",
        "message": "邮箱格式不正确"
      }
    ]
  },
  "timestamp": "2024-01-15T08:30:00Z"
}

分页响应

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "用户1"
    },
    {
      "id": 2,
      "name": "用户2"
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 10,
    "totalItems": 100,
    "itemsPerPage": 10
  }
}

常见响应结构类型

• 成功响应：返回 success、data、message、timestamp 等字段。
• 错误响应：返回 success、error、timestamp 等字段。
• 分页响应：在 data 之外，增加 pagination 信息。

请求头常用字段

《夸克》非常好用的免费AI浏览器

下载APP查看