理解 RESTful API 设计规范

一、什么是REST?

REST这个词，是Roy Thomas Fielding在他2000年的博士论文中提出的。Fielding是一个非常重要的人，他是HTTP协议（1.0版和1.1版）的主要设计者、Apache服务器软件的作者之一、Apache基金会的第一任主席。

Fielding将他对互联网软件的架构原则，定名为REST，即Representational State Transfer的缩写。翻译是"表现层状态转化"。

它是基于HTTP、URI、XML、JSON等标准和协议，支持轻量级、跨平台、跨语言的架构设计。

二、REST设计原则：

需要符合如下的一些原则：

1. 每一个URI代表一种资源;
2. 同一种资源有多种表现形式(xml/json);
3. 所有的操作都是无状态的。
4. 规范统一接口。
5. 返回一致的数据格式。
6. 可缓存(客户端可以缓存响应的内容)。

三、什么是RESTful？

如果一个架构符合REST原则，就称它为RESTful架构。RESTful是目前最流行的API设计规范，通过一套统一的接口为所有web相关提供服务，实现前后端分离。

四、理解规范统一的接口

Rest接口约束定义为: 资源识别；请求动作；响应信息; 它表示通过uri表示出要操作的资源，通过请求动作(http method)标识要执行的操作，通过返回的状态码来表示这次请求的执行结果。

比如说，未使用Rest规范之前，我们可能有增删改查等接口，会设计出类似这样的接口: /xxx/newAdd (新增接口), /xxx/delete(删除接口), /xxx/query (查询接口), /xxx/uddate(修改接口)等这样的。增删改查有四个不同的接口，维护起来可能也不好。

Restful规范，请求只需要一个接口，比如设计该接口为 /xxx/apis 这样的一个接口就可以了，然后请求方式(method)有 GET--查询(从服务器获取资源); POST---新增(从服务器中新建一个资源); PUT---更新(在服务器中更新资源)，DELETE---删除(从服务器删除资源)，PATCH---部分更新(从服务器端更新部分资源) 等这些方式来做，服务器端返回的数据也可以是相同的，只是我们前端会根据状态码来判断请求成功或失败的状态值来判断。

五、 URL及参数设计规范

1. url设计规范

1) url末尾不需要出现斜杠/
2) 在url中使用斜杠/是表达层级关系的。
3) 在uri中可以使用连接符-, 来提升可读性。
比如 http://xxx.com/xx-yy 比 http://xxx.com/xx_yy中的可读性更好。
4) 在url中不允许出现下划线字符_.
5) 在url中尽量使用小写字符。
6) 在url中不允许出现文件扩展名. 比如接口为 /xxx/api, 不要写成 /xxx/api.php 这样的是不合法的。
7) 在url中使用复数形式。
具体可以看：（https://blog.restcase.com/7-rules-for-rest-api-uri-design/）

在RESTful架构中，每个url代表一种资源，因此url设计中不能使用动词，只能使用名词，并且名词中也应该尽量使用复数形式。使用者应该使用相应的http动词 GET、POST、PUT、PATCH、DELETE等操作这些资源即可。

那么在我们未使用RESTful规范之前，我们是如下方式来定义接口的，形式是不固定的，并且没有统一的规范。比如如下形式:

http://xxx.com/api/getallUsers; // GET请求方式，获取所有的用户信息
http://xxx.com/api/getuser/1;   // GET请求方式，获取标识为1的用户信息
http://xxx.com/api/user/delete/1 // GET、POST 删除标识为1的用户信息
http://xxx.com/api/updateUser/1  // POST请求方式 更新标识为1的用户信息
http://xxx.com/api/User/add      // POST请求方式，添加新的用户

如上我们可以看到，在未使用Restful规范之前，接口形式是不固定的，没有统一的规范，下面我们来看下使用RESTful规范的接口如下，两者之间对比下就可以看到各自的优点了。

http://xxx.com/api/users;     // GET请求方式 获取所有用户信息
http://xxx.com/api/users/1;   // GET请求方式 获取标识为1的用户信息
http://xxx.com/api/users/1;   // DELETE请求方式 删除标识为1的用户信息
http://xxx.com/api/users/1;   // PATCH请求方式，更新标识为1的用户部分信息
http://xxx.com/api/users;     // POST请求方式 添加新的用户

如上我们可以看到，增删改成我们都是使用同一个api接口，只是请求的方式 GET(查询)、POST(新增)、DELETE(删除)、PACTH(部分更新)来代表的是增删改查操作的方式。然后开发获取到该请求的header头部信息，就可以知道是什么方式来请求数据的了。

2. HTTP请求规范

GET (SELECT): 查询；从服务器取出资源.
POST(CREATE): 新增; 在服务器上新建一个资源。
PUT(UPDATE): 更新; 在服务器上更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE): 更新；在服务器上更新部分资源(客户端提供改变的属性)。
DELETE(DELETE): 删除; 从服务器上删除资源。

3. 参数命名规范

参数推荐采用下划线命名的方式。比如如下demo:

http://xxx.com/api/today_login // 获取今天登录的用户。
http://xxx.com/api/today_login&sort=login_desc // 获取今天登录的用户、登录时间降序排序。

六、 http状态码相关的

状态码范围

客户端的每一次请求, 服务器端必须给出回应，回应一般包括HTTP状态码和数据两部分。

1xx: 信息，请求收到了，继续处理。
2xx: 代表成功. 行为被成功地接收、理解及采纳。
3xx: 重定向。
4xx: 客户端错误，请求包含语法错误或请求无法实现。
5xx: 服务器端错误.

七、返回数据格式

RESTful规范中的请求应该返回统一的数据格式。对于返回的数据，一般会包含如下字段:

1) code: http响应的状态码。
2) status: 包含文本, 比如：'success'(成功), 'fail'(失败), 'error'(异常)

当status的值为 'fail' 或 'error'时，需要添加 message 字段，用于显示错误信息。

3) data: 当请求成功的时候, 返回的数据信息。但是当状态值为 'fail' 或 'error' 时，data仅仅包含错误原因或异常信息等。

返回成功的响应JSON格式一般为如下:

{
    "code": 200,
    "status": "success",
    "data": [{
        "userName": "tugenhua",
        "age": 31
    }]
}

返回失败的响应json格式为如下:

{
    "code": 401,
    "status": "error",
    "message": '用户没有权限',
    "data": null
}

参考链接：

https://www.cnblogs.com/tugenhua0707/p/12153857.html

http://www.ruanyifeng.com/blog/2011/09/restful.html

posted @ 2020-10-20 18:39 梁涛999 阅读(277) 评论(0) 编辑收藏举报

刷新页面返回顶部

不积跬步无以至千里

理解 RESTful API 设计规范

公告