[Java知识库][API接口设计] RESTful 规范

RESTful是目前最流行的API设计规范，它是用于Web数据接口的设计；REST它是 Representational State Transfer的简称，中文的含义是: "表征状态转移" 或 "表现层状态转化"

1 发展来源和必要性

????????RESTful API 设计由 Roy Fielding 博士在其 2000 年的博士论文中定义。后来经过社区以及互联网发展的趋势需要就慢慢成为了一个标准；

????????目前我们实现一个RESTful接口，可以在web端 pc端及移动端，实现多端同时调用，而且前后端分离，使得前端开发无须关注过多后端业务逻辑；这是我们目前想当然的一个使用；其实在之前我们的页面、数据以及模板渲染工作都是在服务端进行的；也就是说以前开发者都是全栈开发；像我们上学时的.net Form等.net框架、flex开发；都是服务器端渲染，一个人进行前端页面以及后台数据查询、数据和页面模板绑定工作，一人负责多项工作；

????????维护工作比较困难；这里可能更应该强调是目前这个互联网环境下 换人的成本太大；

所以这里所说的维护并不是人员的维护系统难度大小，更可能是如果一个这样的系统直接换人去维护的难度和成本大小，因为需要找一个对前端、服务端、数据查询等都需满足的人，这对于咱目前各大企业如此频繁的人员流动的市场简直就是噩梦，从这个角度来看，前后端分离势在必行，可能不仅仅是因为技术原因，市场才是主要导向吧；

所以伴随着前后端分离潮流，RESTful api标准就慢慢流行起来了；

2?Rest设计原则

后端实现的接口怎么才能算是一个rest风格的接口呢，需要满足以下风格

2.1??每一个URI代表一种资源

????????这个很好理解，就是一个URI只代表一种类型的资源

http://xxx.com/api/users;        // 获取所有用户信息
http://xxx.com/api/teachers;     // 获取所有老师信息
http://xxx.com/api/areas;        // 获取所有区域信息

2.2?同一种资源有多种表现形式(xml/json)

????????一种资源可以用多种格式返回，客户端请求的时候，我们可以在请求头中设置参数，要求restful返回指定类型的数据，这是RESTful接口需要满足的元原则；比如

Accept:application/xml ?

请求时设置返回形式是xml，如使用ajax请求，则需要设置contentType:application/xml

Accept:application/json ?

请求时设置返回形式是json，如使用ajax请求，则需要设置contentType:application/json

2.3?所有的操作都是无状态的

????????http请求本身是无状态的，而RESTful是建立在无状态http协议基础上的；所以本身RESTful的各种请求也是无状态的；

? ? ? ? 怎么理解这个无状态呢

? ? ? ? 可以这么理解:协议对于事务处理没有记忆能力。缺少状态意味着如果后续处理需要前面的信息，则它必须重传，这样可能导致每次连接传送的数据量增大。但另一方面，在服务器不需要先前信息时它的应答就较快。

????????举个🌰，当浏览器发送请求给服务器的时候，服务器响应，但是同一个浏览器再发送请求给服务器的时候，他会响应，但是他不知道你就是刚才那个浏览器，简单地说，就是服务器不会去记得你；

所以如果需要有状态之类的记忆功能，就借助浏览器的cookie、session及token技术去实现即可；

2.4 规范统一接口

Rest接口约束定义为:

资源识别：它表示通过uri表示出要操作的资源；

请求动作：通过请求动作(http method)标识要执行的操作；

响应信息;：通过返回的状态码来表示这次请求的执行结果；

直接对比下

达不到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风格接口规范：?

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请求方式 添加新的用户

2.5?返回一致的数据格式

这个也好理解，比如返回的数据格式，最起码有我们标准要求的几个字段，比如状态、code、信息、data等。如下

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

{
? ? "code": 200,
? ? "status": "success",
? ? "data": [{
? ? ? ? "userName": "小白GIS",
? ? ? ? "age": 7
? ? }]
}

2.6 可缓存(客户端可以缓存响应的内容)

????????现在接口基本都提供了可缓存的功能，也就是说在接口开发阶段，我们会设置浏览器是否可以缓存，以及缓存的类型和有效时间等等.比如强缓存、协商缓存规范都是服务器端设置的

3 RESTful接口规范

3.1 uri规范

我们在接口路径定义的时候，尽量使用如下规范即可

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

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

3.2 请求方式

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

3.3 参数命名规范

参数建议使用下划线?

http://xxx.com/api/male_users // 获取男性用户。
http://xxx.com/api/male_users&sort=age_desc // 获取年纪降序的男性用户

4 状态码?

以上就是RESTful API规范了；只要咱的接口能满足以上规范和设计原则；就是一个RESTful 接口?