RESTful接口标准

我不是女神ヾ 2022-05-26 03:50 357阅读 0赞

# RESTful 接口实现简明指南 #

在前后端分离的 Web 应用架构中，前端专注于页面，同时与后端进行数据交互；而后端则专注于提供 API 接口。在这样的结构下，REST 是一个很流行的前后端交互形式的约定。这只是一套约定，并不是某个技术标准，所以在实际的应用中，对器实现程度完全取决于后端开发者；一些号称 RESTful 的接口并没有那么RESTful。

在我所见过的 RESTful 接口的实现中，以 GitHub 最让人惊叹。我第一次如此强烈得感受到 REST 接口的美妙，完全满足了我所期待的「接口的形式美感」，简直就是对 REST 规范实现的最佳范本。我觉得每一个后端开发者都应该看一看 [GitHub 的 REST 接口文档][GitHub _ REST]，感受一下循规蹈矩的美妙。

本文选取了几个点来简要介绍，一个让前端开发者用起来舒服的 RESTful 接口是什么样子。

## REST 简介 ##

以防有些观众刚刚打开电梯，还是有必要简单介绍一下 REST 这个概念。

REST 是一个术语的缩写，REpresentational State Transfer，中文直译「表征状态转移」，这是个很拗口的词。我的建议是先不要强行理解，直接看怎么做，等对实施细节有一些了解后，再来看名字会有更深刻的理解。REST 是一套风格约定，RESTful 是它的形容词形式；比如一套实现了 REST 风格的接口，可以称之为 RESTful 接口。

## REST 对请求的约定 ##

REST 用来规范应用如何在 HTTP 层与 API 提供方进行数据交互；在现阶段，你应该已经很熟悉 GET 和 POST 请求；甚至有可能因为受限于后端框架限制等原因，你的整个应用全都是用这两种 HTTP 方法来完成的。这样无疑浪费了 HTTP 协议的潜力，而 REST 则充分利用了 HTTP 规范中的方法，达到接口描述的语义化。

REST 描述了 HTTP 层里客户端和服务器端的数据交互规则；客户端通过向服务器端发送 HTTP（s）请求，接收服务器的响应，完成一次 HTTP 交互。这个交互过程中，REST 架构约定两个重要方面就是 HTTP 请求的所采用方法，以及请求的链接。

在请求层面，REST 规范可以简单粗暴抽象成以下两个规则：

1. 请求 API 的 URL 表示用来定位资源；

2. 请求的 METHOD 表示对这个资源进行的操作；

以下将以这两个规则为基础，描述如何构造一个符合 REST 规范的请求。

一、API 的 URL

URL 用来定位资源，跟要进行的操作区分开，这就意味这 URL 不该有任何动词；

下面示例中的 get、create、search 等动词，都不应该出现在 REST 架构的后端接口路径中。在以前，这些接口中的动名词通常对应后台的某个函数。比如：

/api/getUser
    /api/createApp
    /api/searchResult
    /api/deleteAllUsers

当我们需要对单个用户进行操作时，根据操作的方式不同可能需要下面的这些接口：

/api/getUser （用来获取某个用户的信息，还需要以参数方式传入用户 id 信息）
    /api/updateUser （用来更新用户信息）
    /api/deleteUser （用来删除单个用户）
    /api/resetUser （重置用户的信息）

更有甚者，可能在更新用户不同信息时，提供不同的接口，比如：

/api/updateUserName
    /api/updateUserEmail
    /api/updateUser

这样的弊端在于：首先加上了动词，肯定是使 URL 更长了；其次对一个资源实体进行不同的操作就是一个不同的 URL，造成 URL 过多难以管理。

其实当你回过头看「URL」 这个术语的定义时，更能理解这一点。URL 的意思是统一资源定位符，这个术语已经清晰的表明，一个 URL 应该用来定位资源，而不应该掺入对操作行为的描述。

在 REST 架构的链接应该是这个样子：

1.  URL 中不应该出现任何表示操作的动词，链接只用于对应资源；
2.  URL 中应该单复数区分，推荐的实践是永远只用复数；比如 GET /api/users 表示获取用户的列表；如果获取单个资源，传入 ID，比如 /api/users/123 表示获取单个用户的信息；
3.  按照资源的逻辑层级，对 URL 进行嵌套，比如一个用户属于某个团队，而这个团队也是众多团队之一；那么获取这个用户的接口可能是这样：

GET /api/teams/123/members/234 表示获取 id 为 123 的小组下，id 为234 的成员信息

按照类似的规则，可以写出如下的接口

/api/teams （对应团队列表）
    /api/teams/123 （对应 ID 为 123 的团队）
    /api/teams/123/members （对应 ID 为 123 的团队下的成员列表）
    /api/teams/123/members/456 （对应 ID 为 123 的团队下 ID 是 456 的成员）

二、API 请求的方法

在很多系统中，几乎只用 GET 和 POST 方法来完成了所有的接口操作；这个行为类似于全用 DIV 来布局。实际上，我们不只有GET 和 POST 可用，在 REST 架构中，有以下几个重要的请求方法：GET，POST，PUT，PATCH，DELETE。这几个方法都可以与对数据的 CRUD 操作对应起来。

【Read】，资源的读取，用 GET 请求；比如：

GET /api/users  （ 表示读取用户列表）

GET 应当实现为一个安全方法。用于获取数据而不应该产生副作用。

【Created】，资源的创建，用 POST 方法；

POST 是一个非幂等的方法，多次调用会造成不同效果；

> 幂等（Idempotent）：如果对服务器资源的多次请求与一次请求造成的副作用是一样的的话，那这个请求方法可以被认为是幂等。

比如下面的请求会在服务器上创建一个 name 属性为 'John Snow' 的用户；多次请求就会创建多个这样的用户。

POST /api/users
    {
      "name": "John Snow"
    }

【Update】，资源的更新。用于更新的 HTTP 方法有两个，PUT 和 PATCH。

他们都应当被实现为幂等方法，即多次同样的更新请求应当对服务器产生同样的副作用。

PUT 和 PATCH 有各自不同的使用场景：

PUT 用于更新资源的全部信息，在请求的 body 中需要传入修改后的全部资源主体；