全栈修炼

28 11月

REST介绍与设计指南

2020-11-28 全栈修炼

REST 是目前比较流行的一种API设计理论。因为它结构清晰、符合标准、易于理解、扩展方便，所以被越来越多的应用场景所使用。REST（REpresentational State Transfer），首次出现在 2000 年 Roy Thomas Fielding 的博士论文中，它指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 REST 的。

REST介绍

下面我们先来普及一下基础知识。

什么是 REST？

REST（REpresentational State Transfer），首次出现在 2000 年 Roy Thomas Fielding 的博士论文中，提出了一种万维网的软件架构风格-REST（全称：Representational State Transfer， 表现层状态转换），目的是便于在不同软件/程序中（例如互联网）中互相传递信息。它指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 REST 的。

  • 资源（Resources），REST 是“表现层状态转化”，其实它省略了主语。“表现层”其实指的是“资源”的“表现层”。那么什么是资源呢？平时上网访问到图片、文字、文档、多媒体等就是资源，一般通过 URI 来定位。也就是说，一个 URI 就表示一个资源。
  • 表现层（Representation），资源是作为一个具体的实体信息，它可以有多种的展现方式。而把实体展现出来就是表现层。例如一个 txt 文本信息，它可以输出成 html、json 等。
  • 状态转化（State Transfer），访问一个网站，就代表了客户端和服务器的一个互动过程。在这个过程中，就涉及到数据和状态的变化。而 HTTP 协议是无状态的，那么这些状态肯定保存在服务器端，所以如果客户端想要通知服务器端改变数据和状态的变化，就要通过某种方式来通知它。客户端能通知服务器端的手段，只能是 HTTP 协议。具体来说，就是 HTTP 协议里面，四个表示操作方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：
    • GET 用来获取资源
    • POST 用来新建资源（也可以用于更新资源）
    • PUT 用来更新资源
    • DELETE 用来删除资源

综上所述，下面看下什么是 REST 架构：

1、每一个 URI 代表一种资源

2、客户端和服务端之间，传递这种资源的某种表现层

3、客户端通过四个 HTTP 动词，对服务端资源进行操作，实现“表现层状态转化”

将它们概述为图片形式，则 REST 架构图为：

REST架构图

REST 的扩展性：

REST 的扩展性

 

什么是 RPC？

RPC（Remote Procedure Call Protocol）远程过程调用协议，是一种通过网络从远程计算机程序上请求服务，而不需要了解底层网络技术的协议。它假定某些传输协议的存在，如 TCP 或 UDP，以便为通信程序之间携带信息数据。通过它可以使函数调用模式网络化。在 OSI 网络通信模型中，RPC 跨越了传输层和应用层。RPC 使得开发包括网络分布式多程序在内的应用程序更加容易。

工作原理

RPC工作原理

运行时，一次客户端对服务器的 RPC 调用，其内部操作大致有如下步骤：

1、调用客户端句柄；执行传送参数

2、调用本地系统内核发送网络消息

3、消息传送到服务端

4、服务器句柄得到消息并取得参数

5、执行远程过程

6、执行的过程将结果返回服务器句柄

7、服务器句柄返回结果，调用远程系统内核

8、消息传回本地主机

9、客户端句柄由内核接收消息

10、客户端接收句柄返回的数据

REST vs RPC

在做 API 服务器开发时，很多人都会遇到这个问题 —— 选择 REST 还是 RPC。RPC 相比 REST 的优点主要有 3 点：

1、RPC+Protobuf 采用的是 TCP 做传输协议，REST 直接使用 HTTP 做应用层协议，这种区别导致 REST 在调用性能上会比 RPC+Protobuf 低

2、RPC 不像 REST 那样，每一个操作都要抽象成对资源的增删改查，在实际开发中，有很多操作很难抽象成资源，比如登录操作。所以在实际开发中并不能严格按照 REST 规范来写 API，RPC 就不存在这个问题

3、RPC 屏蔽网络细节、易用，和本地调用类似

但是 REST 相较 RPC 也有很多优势：

1、轻量级，简单易用，维护性和扩展性都比较好

2、REST 相对更规范，更标准，更通用，无论哪种语言都支持 HTTP 协议，可以对接外部很多系统，只要满足 HTTP 调用即可，更适合对外，RPC 会有语言限制，不同语言的 RPC 调用起来很麻烦

3、JSON 格式可读性更强，开发调试都很方便

4、在开发过程中，如果严格按照 REST 规范来写 API，API 看起来更清晰，更容易被大家理解

其实业界普遍采用的做法是，内部系统之间调用用 RPC，对外用 REST，因为内部系统之间可能调用很频繁，需要 RPC 的高性能支撑。对外用 REST 更易理解，更通用些。

RESTful API设计指南

域名

API与用户的通信协议，总是使用HTTPs协议。

域名

应该尽量将API部署在专用域名之下。

https://api.example.com

如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

https://example.org/api/

版本（Versioning）

应该将API的版本号放入URL。

应该将API的版本号放入URL。

另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。

路径（Endpoint）

路径又称"终点"（endpoint），表示API的具体网址。

在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

HTTP动词

对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面五个（括号里是对应的SQL命令）。

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。

还有两个不常用的HTTP动词。

HEAD：获取资源的元数据。
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

下面是一些例子。

GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

过滤信息（Filtering）

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。

状态码（Status Codes）

服务器向用户返回的状态码和提示信息，常见的有以下一些（方括号中是该状态码对应的HTTP动词）。

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

状态码的完全列表参见这里【所有HTTP状态码】。

错误处理（Error handling）

如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

{
    error: "Invalid API key"
}

返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

误区

RESTful架构有一些典型的设计误区。

最常见的一种设计错误，就是URI包含动词。因为"资源"表示一种实体，所以应该是名词，URI不应该有动词，动词应该放在HTTP协议中。

举例来说，某个URI是/posts/show/1，其中show是动词，这个URI就设计错了，正确的写法应该是/posts/1，然后用GET方法表示show。

如果某些动作是HTTP动词表示不了的，你就应该把动作做成一种资源。比如网上汇款，从账户1向账户2汇款500元，错误的URI是：

POST /accounts/1/transfer/500/to/2

正确的写法是把动词transfer改成名词transaction，资源不能是动词，但是可以是一种服务：

POST /transaction HTTP/1.1
Host: 127.0.0.1
　　
from=1&to=2&amount=500.00

另一个设计误区，就是在URI中加入版本号：

http://www.example.com/app/1.0/foo
http://www.example.com/app/1.1/foo
http://www.example.com/app/2.0/foo

因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分。

 

摘自：http://www.ruanyifeng.com/blog/2014/05/restful_api.html

resturihttprpchttp状态码