RESTful API 设计中的返回结果规范-JavaScript中文网-JavaScript教程资源分享门户

引言

RESTful API 的设计已经成为现代 Web 应用程序的标准，因为它允许客户端和服务器之间的数据交换变得简单和直观。在实际开发中，我们通常需要返回大量数据以及一些元数据，比如状态码、错误信息、分页信息等等。为了提高 API 的可读性和可维护性，我们需要遵循一些规范来定义返回结果。本文将介绍一些在 RESTful API 设计中常用的返回结果规范，并提供一些示例代码供参考。

状态码

HTTP 协议中有一个状态码的概念，用于表示客户端请求的结果，其中 2xx 系列表示成功，4xx 表示客户端请求有误，5xx 表示服务器错误。在 RESTful API 设计中，我们通常遵循以下几种状态码：

200 OK：表示请求已成功执行，并返回所需数据
201 Created：表示已成功创建新资源，并返回该资源的 URL
204 No Content：表示请求已成功执行，但返回的数据为空
400 Bad Request：表示客户端提交参数有误，无法解析请求
401 Unauthorized：表示客户端未提供身份验证信息或身份验证失败
403 Forbidden：表示客户端没有权限执行所请求的操作
404 Not Found：表示请求的资源不存在
500 Internal Server Error：表示服务器出现意外错误

在具体使用过程中，我们还需要考虑一些业务特殊的状态码。比如说，创建资源时，如果客户端提交的数据存在重复，我们可以使用 409 Conflict 表示冲突。如果客户端利用一个过期的 token 发送了请求，我们可以使用 419 Authentication Timeout 表示未认证。

返回格式

在 RESTful API 中，返回结果通常使用 JSON 格式。JSON 可以轻松地解析为对象，这使得数据交换变得简单和直观。在设计返回结果格式之前，我们需要确定自己的 API 有哪些资源，并确定每个资源都有哪些字段。通常情况下，我们需要考虑以下几方面：

消息描述

返回结果应该携带有意义的消息描述，对客户端开发者有利。比如说，在添加一条记录后返回“新纪录已添加成功”等消息。

资源元数据

资源元数据通常是一些关于资源本身的数据，如分页信息、总数、页数等等。在 RESTful API 中，元数据通常被放在头部或者每个资源的尾部，以避免过多的重复数据。可以使用以下形式的返回结果：

// javascriptcn.com 代码示例
{
  "data": [
    ...,
    ...
  ],
  "meta": {
    "pagination": {
      "total": 100,
      "per_page": 20,
      "current_page": 1,
      "last_page": 5,
      "next_page_url": "http://example.com/api/users?page=2",
      "prev_page_url": null
    }
  }
}

集合资源

在 RESTful API 中，通常使用集合资源来描述一组相关的数据（如用户列表）。返回结果应该简单，并易于客户端处理。一个典型的集合资源返回格式如下：

// javascriptcn.com 代码示例
{
  "data": [
    {
      "id": 1,
      "name": "john",
      "email": "john@example.com"
    },
    {
      "id": 2,
      "name": "james",
      "email": "james@example.com",
    }
  ]
}

单一资源

在 RESTful API 中，通常使用单一资源来描述某个实体的详细数据（如某个用户的详细信息）。一个典型的单一资源返回格式如下：

{
  "data": {
    "id": 1,
    "name": "john",
    "email": "john@example.com"
  }
}

错误处理

RESTful API 的错误处理相当重要，因为它能让客户端更好地处理服务器返回的错误信息。返回结果中应该携带一些错误信息和恰当的状态码，以便客户端开发者了解发生了什么错误。一般来说，我们需要在返回结果中添加“error”字段，用于存储错误信息，格式如下：

{
  "error": {
    "code": 400,
    "message": "Bad Request"
  }
}

此外，我们通常会在 HTTP 头部添加一些特殊的字段，如 Retry-After 表示服务器会在多少秒内尝试再次运行请求，WWW-Authenticate 表示如何对请求进行身份验证等等。

示例代码

以下是一个伪造的例子，用于展示上述规范的常见使用场景。

// javascriptcn.com 代码示例
HTTP/1.1 200 OK
Content-Type: application/json
{
  "data": {
    "id": 1,
    "name": "John Doe",
    "address": {
      "street": "Foo",
      "zip": "12345",
      "city": "Bar"
    }
  }
}

// javascriptcn.com 代码示例
HTTP/1.1 201 Created
Content-Type: application/json
Location: /api/user/1
{
  "data": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  }
}

HTTP/1.1 404 Not Found
Content-Type: application/json
{
  "error": {
    "code": 404,
    "message": "Not Found"
  }
}

总结

本文介绍了在 RESTful API 设计中常用的返回结果规范。遵循这些规范，能够让开发者更好地理解 API 的行为，提高开发效率，降低开发成本。在实际项目中，应该根据具体业务情况，结合 RESTful API 的设计原则，制定出最适合自己项目的返回结果格式。

来源：JavaScript中文网，转载请注明来源本文地址：https://www.javascriptcn.com/post/654b29be7d4982a6eb51b55e