前后端 RESTful

RESTful 是一种备受推崇的 API 开发风格。

一、什么是 RESTful ？

REST，Representational State Transfer，即表象层状态转变；ful 为形容词后缀。所谓 RESTful，就是符合 REST 原则的。

简单来说，RESTful 就是用 URL 定位资源，用 HTTP 动词描述操作。

示例：

1
2
3
4
5
6
https://example.com/api/users GET 获取所有用户信息 
https://example.com/api/users/1 GET 获取标识为1用户信息 
https://example.com/api/users/1 DELETE 删除标识为1用户信息 
https://example.com/api/users/1 PUT 更新标识为1用户信息
https://example.com/api/users/1 PATCH 更新标识为1用户部分信息（只需要传递更新的信息）
https://example.com/api/users POST 添加新的用户

二、原则

  • C-S 架构：客户端与服务器分离
  • 无状态：每个请求中都包含所有信息
  • 统一的接口：接口应该保持统一
  • 系统分层：引入中间层，客户端只需要与中间层进行交互
  • 缓存：响应应该被隐式或显式的定义为可缓存的，从而减少客户端与服务器的交互次数
  • 按需编码（可选）：服务器可以通过响应传递功能代码交由客户端执行，从而扩展客户端的功能

三、规范

1. 使用 HTTP 请求方式来描述行为

使用 HTTP 请求方式，而不是 URL 来描述本次请求希望完成的行为。

例如：

  • GET：查
  • POST：增
  • PUT：改
  • PATCH：改，部分更新（只需要传递更新的信息）
  • DELETE：删

2. URL 中只能包含名词

错误：

1
/getUsers

正确：

1
/users

3. 名词应该为复数

为统一起见，URL 中的名词都使用复数

4. 避免多级 URL

多级的 URL 不利于扩展，并且语法也不明确。因此，除了 ID 以外，其它参数都应该以查询参数的形式传递

错误：

1
/school/china/sichuan/chengdu/

正确：

1
/school?country=china&province=sichuan&city=chengdu

5. 发生错误时，应返回非 200 状态码

发生错误时，应该传递符合错误情况的状态码，以便客户端在无需解析响应的情况下判断错误。

正确：

1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type: application/json

{
	"status": "failure",
    "data": {
 		"error": "Expected at least two items in list."
	}
}

正确：

1
2
3
4
5
6
7
8
9
HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "Invalid payoad.",
  "detail": {
     "surname": "This field is required."
  }
}

6. 提供 api 文档

应该提供 api 文档，以便查阅并使用。

四、分页接口的编写方案

分页是一种常见的需求，可以用于有效地管理大量数据的展示。在 RESTful 下，可以这么设置分页接口：

  • 使用查询参数传递分页要求

    1
    GET /api/resources?page=2&limit=10

  • 响应中，除了数据外，额外提供分页元数据

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    {
      "data": [
        {
          "id": 1,
          "name": "Resource Name 1"
        },
        {
          "id": 2,
          "name": "Resource Name 2"
        }
      ],
      "total": 50,
      "page": 2
    }

  • 如果不传递分页参数，则默认进行分页，以保证接口响应的一致性，并避免潜在的性能问题

参考