restful api接口设计

た入场券 2021-07-26 18:09 540阅读 0赞

### 技术由来： ###

互联网早期，页面请求和并发量不高，且移动端未盛行时对接口要求不高，使用动态页面(jsp)就能满足绝大多数的使用需求。但是随着互联网和移动设备的发展，人们对Web应用的使用需求也增加，传统的动态页面由于低效率而渐渐被HTML+JavaScript(Ajax)的前后端分离所取代，并且安卓、IOS、小程序等形式客户端层出不穷，客户端的种类出现多元化，**而客户端和服务端就需要接口进行通信**，但接口的**规范性**就又成了一个问题：

![f92e6723a885b2ff02aa59e6f0c5bf51.png][]

所以一套**结构清晰、符合标准、易于理解、扩展方便**让大部分人都能够理解接受的接口风格就显得越来越重要，而RESTful风格的接口(RESTful API)刚好有以上特点，就逐渐被实践应用而变得流行起来。

![6dfd887dcc9b85c639e3acdc81491ffd.png][]

使用resetful设计的接口特点：**看Url就知道要什么资源数据，看http method就知道进行什么操作！**

所以**RESTful API就是一套接口设计风格，用来规范多种形式的前端和同一个后台的交互方式**。

### 使用场景： ###

前后端分离。前端拿到数据只负责展示和渲染，不对数据做任何处理。后端处理数据并以JSON格式传输出去，定义这样一套统一的接口，在web，ios，android三端都可以用相同的接口，节约开发成本以及便于同一调试。

### 区分**REST和**RESTful ： ###

REST是几个单词缩写 -- REpresentational State Transfer 直接翻译：表现层状态转移。字面理解太复杂了，先简单理解为：**URL定位资源，用HTTP动词（GET,POST,DELETE,DETC）描述操作。**

REST描述的是在网络中client和server的一种交互形式；**REST并没有一个明确的标准，而更像是一种设计的风格**，满足这种设计风格的程序或接口我们称之为RESTful(从单词字面来看就是一个形容词)。所以**RESTful API 就是满足REST架构特征的接口。**

### REST架构特征和设计规范： ###

*  **URI指向资源**：使用URI = Universal Resource Identifier 统一资源标志符，用来标识抽象或物理资源的一个紧凑字符串。URI包括URL和URN，在这里更多时候可能代指URL(统一资源定位符)。RESTful是面向资源的，每种资源可能由一个或多个URI对应，但一个URI只指向一种资源。注意：**使用名词的复数表示一个资源集合**，如api.domain.com/users；**使用斜线“/”用来表示资源之间的层次关系**，如api.domain.com/users/1234/orders；**URI 中应尽量使用小写字母，不实用下划线；URL末尾不应包含斜线“/”；**

*  **统一接口**: 通过一定原则设计接口降低耦合，简化系统架构，这是RESTful设计的基本出发点。**对资源的操作包括获取、创建、修改和删除，这些操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法**。换言而知，使用RESTful风格的接口但从接口上你可能只能定位其资源，但是无法知晓它具体进行了什么操作，需要具体了解其发生了什么操作动作要从其HTTP请求方法类型上进行判断。具体的HTTP方法和方法含义如下图1，这样就统一了数据操作的接口。

非RESTful风格的API中，我们通常使用GET请求和POST请求完成增删改查以及其他操作，查询和删除一般使用GET方式请求，更新和插入一般使用POST请求。从请求方式上无法知道API具体是干嘛的，所有在URL上都会有操作的动词来表示API进行的动         作，例如：query，add，update，delete等等。而**RESTful风格的API则要求在URL上都以名词（推荐用复数）的方式出现，从几种请求方式上就可以看出想要进行的操作**，这点与非RESTful风格的API形成鲜明对比。在谈及GET,POST,PUT,DELETE的时候，就必须提一下接口的**安全性和幂等性**，其中安全性是指方法不会修改资源状态，即读的为安全的，写的操作为非安全的。而幂等性的意思是操作一次和操作多次的最终效果相同，客户端重复调用也只返回同一个结果。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3pob3V6dW9sdW8_size_16_color_FFFFFF_t_70][]

上述四个HTTP请求方法的安全性和幂等性如下：

![202101261035252.png][]

**    举例子：**说了这么多，到底RESTful长什么样子的呢？

*    GET:http://www.xxx.com/source/id 获取指定ID的某一类资源。
 *    例如GET:http://www.xxx.com/friends/123表示获取ID为123的会员的好友列表。如果不加id就表示获取所有会员的好友列表。
 *    POST:http://www.xxx.com/friends/123表示为指定ID为123的会员新增好友。其他的操作类似就不举例了。

** 如果一个操作无法对应到资源的某个操作上，此时可以适当地在URI中包含动词**，但依然应该基于一个资源的标识符。例如：DELETE /users/1234/set-admin

*  **无状态。**服务器不能保存客户端的信息， 每一次从客户端发送的请求中，要包含所有必须的状态信息，会话信息由客户端保存， 服务器端根据这些状态信息来处理请求。 当客户端可以切换到一个新状态的时候发送请求信息， 当一个或者多个请求被发送之后, 客户端就处于一个状态变迁过程中。 每一个应用的状态描述可以被客户端用来初始化下一次的状态变迁。

*  **状态码和返回数据**

服务端处理完成后客户端也可能不知道具体成功了还是失败了，服务器响应时，包含**状态码**和**返回数据**两个部分。

![watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3pob3V6dW9sdW8_size_16_color_FFFFFF_t_70 1][]

![20210126103041959.png][]

{  //响应格式
        status:0,
    
        data:{}||[],
    
        msg:’’
    }

*  **过滤信息：**可以使用过滤信息进行筛选、搜索或分页查询等

![20210126100042296.png][]

*  **可缓存性（Cacheability）** ：服务端需回复是否可以缓存以让客户端甄别是否缓存提高效率。
 *  **版本号：**可以将API的版本号放入URL。GET:http://www.xxx.com/v1/friend/123。或者将版本号放在HTTP头信息中。

### 总结： ###

RESTful风格的API 固然很好很规范，但大多数互联网公司并没有按照或者完全按照其规则来设计，因为REST是一种风格，而不是一种约束或规则，过于理想的RESTful API 会付出太多的成本。

比如**RESTful API也有一些缺点**

*  比如操作方式繁琐，RESTful API通常根据GET、POST、PUT、DELETE 来区分操作资源的动作，而HTTP Method 本身不可直接见，是隐藏的，而如果将动作放到URL的path上反而清晰可见，更利于团队的理解和交流。
 *  并且有些浏览器对GET,POST之外的请求支持不太友好，还需要特殊额外的处理。
 *  过分强调资源，而实际业务API可能有各种需求比较复杂，单单使用资源的增删改查可能并不能有效满足使用需求，强行使用RESTful风格API只会增加开发难度和成本。

所以，当你或你们的技术团队在设计API的时候，如果使用场景和REST风格很匹配，那么你们可以采用RESTful 风格API。但是如果业务需求和RESTful风格API不太匹配或者很麻烦，那也可以不用RESTful风格API或者可以借鉴一下，毕竟无论那种风格的API都是为了方便团队开发、协商以及管理，不能墨守成规。

参考学习文章：

[https://www.toutiao.com/i6693727878158221836/][https_www.toutiao.com_i6693727878158221836]

[https://www.toutiao.com/a6902604637149692428/][https_www.toutiao.com_a6902604637149692428]

[f92e6723a885b2ff02aa59e6f0c5bf51.png]: /images/20210726/21da9008639146ec9f3dbd82679765e3.png
[6dfd887dcc9b85c639e3acdc81491ffd.png]: /images/20210726/b42f04ea76794c359b295829dfd4ec19.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3pob3V6dW9sdW8_size_16_color_FFFFFF_t_70]: /images/20210726/043a8d19a459449e8020a6d43cf4f752.png
[202101261035252.png]: /images/20210726/ee0db6bbdd8d4b92b5e03fefa3e4e045.png
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3pob3V6dW9sdW8_size_16_color_FFFFFF_t_70 1]: /images/20210726/e6ec35794d8b459e90fefec8d1aeffe4.png
[20210126103041959.png]: /images/20210726/ade47157c09c458baac44f783c78f0ff.png
[20210126100042296.png]: /images/20210726/c0650c8bc3fc4f089608350b79ab9f1b.png
[https_www.toutiao.com_i6693727878158221836]: https://www.toutiao.com/i6693727878158221836/?tt_from=weixin&utm_campaign=client_share&wxshare_count=1&timestamp=1611625684&app=news_article&utm_source=weixin&utm_medium=toutiao_android&use_new_style=1&req_id=202101260948030102020852164217BC93&share_token=dc6df4bc-f27f-4f5c-960e-1fd8c8766f34&group_id=6693727878158221836
[https_www.toutiao.com_a6902604637149692428]: https://www.toutiao.com/a6902604637149692428/?tt_from=weixin&utm_campaign=client_share&app=news_article&utm_source=weixin&iid=4292907490622535&utm_medium=toutiao_android&share_token=a1aa43ab-f858-4baf-9aa0-93071233e435&wxshare_count=1