restful风格的接口设计

1 为什么要用restful接口风格

restful的风格其实是一种规范，用来规范我们在写接口时的命名，用于前端与后端、项目与项目之间来传递数据。restful可以使我们的接口更加简洁、快捷高效、透明。

简洁：使用restful接口规范会使我们的接口名称的长度会变得更短，从而更加的简单清爽。

快捷高效：不管是前端的开发人员还是后端的开发人员，都可以根据接口的名称来得到接口的含义，进而也可以降低沟通成本。

透明：由于使用了restful接口风格来编程，又因为它是面向资源来写接口的，所以，后端的程序架构会很清晰透明。

2 restful风格的特点

2.1 约定大于配置

restful风格的接口设计被提出的很早，随着时间的演进它逐渐的被人们认可，这样使用确实更加的方便快捷，所以自然而然的也就流传了起来。随着使用越来越多，所以逐渐人们对接口的认识就变得统一了起来，就像resource文件夹里面装的是配置文件一样，我们约定俗称了restful接口的风格就是这样来写的，所以，我们也就达到了一个理想的状态：看到接口的uri，就能知道接口的功能。

2.2 无状态性

restful风格的接口依旧有着无状态性的特点，不管是何时从哪发送到哪，它的结果都是不变的，也不需要考虑上下文的状态。返回的状态和http请求的状态相同，符合http的状态码规范。

2.3 面向资源

restful风格的所有接口都是面向资源的，这样我们对于接口也更清晰明确它的功能。

3 restful风格是什么样的

3.1 restful的规范

一般来说，不同的请求类型对应着不同的操作
POST：添加
DELETE：删除
GET：查询
PUT：修改

查询某个国家中的城市

GET
http://localhost:8080/country/1/city/2

添加城市

POST
http://localhost:8080/city   添加的参数全部都写在body中

删除某个城市

DELETE
http://localhost:8080/city/2

修改某个城市

PUT
http://localhost:8080/country/1/city/2      修改的参数全部都写在body中

对于PUT和PATCH，PUT更新整个资源，具有幂等性，PATCH只更新部分资源，不具有幂等性。

如果有过于复杂的参数，更倾向于向后连接参数

过滤条件
?type=1&age=16	

排序
?sort=age,desc	 

投影
?whitelist=id,name,email	 

分页
?limit=10&offset=3

3.2 常用的几种状态码

状态代码	状态描述	说明
200	OK	客户端请求chengg
400	Bad Request	请求的url和接口的url有错误
401	Unauthorized	权限不足
403	Forbidden	服务器可能受到请求，但是不能解析
404	Not Found	页面不存在
500	Internal Server Error	后端处理的程序用出错
503	Service Unavailable	服务器问题

4 多说几句

1. restful风格的接口规范不是确定的，不同的公司或者不同的人对它的理解都不尽然相同，但是从总体上来说他是简单易懂的，尽最大的努力在接口中体现出来含义。
2. 不要贸然将接口的规范直接修改为restful风格，它有它的好处，但是要注意成本，不要意气用事。
3. 修改必然要付出代价。

5 追加参考部分

https://my.oschina.net/jumpLee/blog/1529137