前后端分离：RESTful API和HTTP动词

Posted 2021-04-26 张富涛的学习笔记

这是张富涛的第12篇原创

前后端分离：RESTful API和HTTP动词

1. 前言

现在很多公司都使用“前后端分离”进行开发，“后端工程师”为“前端工程师”提供API接口，这么做的好处是可以“确认职责”和“提高开发效率”，同时还有一套接口设计的比较好后，还可以让移动端调用。但前后端分离本质上是使用“增加人数、明确分工”来“提高产能”的，软件研发行业一般有一个比较基本的理念是：如无必要，勿增实体 ，但如果使用这种方案，一般必须要制定一套机制，或者说是一套约定，保证“实体”（前后端工程师）之间的沟通顺畅，让其更有条理进行前后端分离开发。

本系列讲讲我们在开发过程中进行的，可行的前后端分离探索，主要包含以下命题，大概3~4篇内容：

• RESTful API和HTTP动词
• Swagger
• JWT(JSON Web Token)

2. 概述

RESTful API就是目前比较成熟的一套互联网应用程序的API设计理论，今天我们就来简单了解一下RESTful API，在下面的介绍中，我们可以假设自己即将设计一套为移动端提供的接口，来寻找解决方案，这样会更便于理解RESTful API。

3. 域名

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

https://api.example.com/

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

https://example.com/api/

4. API版本

https://api.example.com/v1/

值得一提的是Github就采用这种做法。

5. Action地址设计

https://api.example.com/v1/users

而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

6. HTTP动词

在RESTful框架中，用不同的HTTP动词标识对一种资源的操作类型。

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

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

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

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

下面是关于设计的一些例子：

• GET     /users：列出所有用户
• POST  /users：新建一个用户
• GET     /users/id：获取某个指定用户的信息
• PUT     /users/id：更新某个指定用户的信息（提供该用户的全部信息）
• PATCH /users/id：更新某个指定用户的信息（提供该用户的部分信息）
• DELETE /users/id：删除某个用户
• GET         /users/id/orders：列出某个指定用户的所有订单
• DELETE /users/id/orders/id：删除某个指定用户的指定订单

7. 对于不同HTTP动词的返回值

• GET（SELECT）：一个对象或多个对象的集合（数组）
• POST（CREATE）：返回创建的对象信息
• PUT（UPDATE）：返回修改后的对象信息
• PATCH（UPDATE）：返回修改后的对象信息
• DELETE（DELETE）：返回空

8. 返回状态码

在RESTful设计中，接口返回的信息中需要返回状态码及提示信息，如在“连接成功要返回200”，“获取不到访问页面返回404”等状态码，常用的状态码如下（除了这些我们也可以自己设计状态码，但是需要跟前端做好约定）：

（方括号中是该状态码对应的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 - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

9. 安全性

为了保证我们设计的接口的安全性，保证应用与API服务器之间的安全通信，防止数据篡改中间人攻击等恶意攻击，建议使用HTTPS协议，同时不建议一些隐私权限的API直接将参数进行明文传参，而改成传递token和参数加密等形式：例如：有个修改昵称的API，参数中“修改谁的昵称（uid）”不应该直接传递，而应该改为token形式，同时增加调用权限校验。

10. 完美结合RESTful的文档生成工具

在做RESTful形式开发时，最好结合文档生成工具进行开发，这样能够实时给前端更新文档的同时，也方便前端进行测试。

下面这张图为Swagger生成的接口文档和测试接口：

注意：经过实践结果，swagger仅是生成API文档（并可供web直接访问）的工具，对代码有一定侵入性，但侵入程度不大。

11. 一个可供参考的RESTful返回值结构

之前我在开发前后端分离时自己总结出了一个返回值的结构，在项目开发的过程中我们的开发体验较不错，在这里分享给大家（删除了get、set方法）：

长按下图二维码关注：