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

最新推荐文章于 2024-08-22 19:03:27 发布

张富涛

最新推荐文章于 2024-08-22 19:03:27 发布

阅读量740

点赞数 1

分类专栏：前后端分离文章标签：前端后端架构 java

本文链接：https://blog.csdn.net/zhangft7478191/article/details/113341534

版权

前后端分离专栏收录该内容

3 篇文章 0 订阅

订阅专栏

这是张富涛的第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版本

在我们设计的接口中，可能会出现版本迭代和更新，对于大的改动，我们可以直接更改接口版本，那么对于访问的接口地址，我们可以直接体现在URL上，如：

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

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

5. Action地址设计

在RESTful架构中，意图对一个对象进行操作（如增删改查等），所有的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形式，同时增加调用权限校验。