前后端分离-Restful最佳实践
作者：尹正杰
版权声明：原创作品，谢绝转载！否则将追究法律责任。
一.Restful概述
REST(Representational State Transfer),表现层状态转移。 RESTFul首次出现在2000年Roy Fielding的博士论文中,Roy Fielding是HTTP规范的主要编写者之一。 表现层是资源的表现层,对于网络中的资源就需要URI(Uniform Resource Identifier)来指向。 RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计。它的大原则容易把握，但是细节不容易做对。 博主推荐阅读: http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html
二.Restful API设计实践案例
1>.协议
使用HTTP或者HTTPS。对外若有安全性要求，可以使用HTTPS。但是内部服务间调用可以使用HTTP或HTTPS。
2>HTTP方法
GET：
从服务器获取一个资源
HEAD：
只从服务器获取文档的响应首部
POST：
向服务器输入数据，通常会再由网关程序继续处理
PUT：
将请求的主体部分存储在服务器中，如上传文件等,即多指更新资源。
PATCH:
部分更新资源。
DELETE：
请求删除服务器上指定的文档
TRACE：
追踪请求到达服务器中间经过的代理服务器
OPTIONS：
请求服务器返回对指定资源支持使用的请求方法
扩展方法：
LOCK，MKCOL，COPY，MOVE等；
3>.动词加宾语(名词)
URL指向资源，在URL路径的描述中,只需要出现名词,而不要出现动词。动词由HTTP方法提供。
不要单复数混用，建议名词使用复数，但有的公司要求名词都使用单数，比如阿里的开发手册很明显规定定义名词不允许使用复数形式。
Restful的核心是资源，URL应该指向资源，所以应该是使用名称表达，而不是动词表达。
Restful名词使用案例:
GET /posts:
返回所有文章。
GET /posts/10:
返回id为10的文章。
POST /posts:
创建新的文章。
PUT /posts/10:
更新id为10的文章。
DELETE /posts/10:
删除id为10的文章。
PATCH /posts/10:
部分更新id为10的文章数据。
不要出现下面的访问资源路径:
/getAllPosts
/addPost
/updatePost
/delPost
GET方法只是获取资源，而不是改变资源状态。改变资源请使用POST,PUT,DELETE等方法。例如:使用GET /posts/10就可以获取资源了，但是缺使用GET /posts/10/del或者GET /posts/10?v=del,本意是想删除,但这样不好，GET方法请求只为获取资源，不要改变资源状态。
子资源访问案例:
GET /posts/10/authors:
返回id为10的文章的所有作者。
GET /posts/10/authors/8:
返回id为10的文章的作者id为8的。
4>.集合功能
过滤(Filltering):
指定过滤条件,比如"GET /posts?tag=java"
排序(Sorting):
指定排序条件,有很多种设计风格,例如使用"+"表示asc,使用"-"表示desc,则有"GET /posts?sort+title,-id"或"GET /posts?sort=title_asc,id_desc"
分页(Pagination):
一般情况下,查询返回的记录非常多,必须分页。比如"GET /posts?page=5&size=20"
5>.状态码
状态码：状态码由三位数字组成，第一位数字表示响应的类型，常用的状态码有五大类如下所示： 1xx: 表示服务器已接收了客户端请求，客户端可继续发送请求 2xx: 表示服务器已成功接收到请求并进行处理 3xx: 表示服务器要求客户端重定向 4xx: 表示客户端的请求有非法内容 5xx: 表示服务器未能正常处理客户端的请求而出现意外错误
常见的状态码举例： 200: 表示OK,即客户端请求成功,一般表示成功获取资源。 201: 成功创建或修改。 204: 成功删除资源 400: 表示Bad Request,即请求报文有语法错误 401: 表示Unauthorized,即未授权 403: 表示Forbidden,即服务器拒绝服务 404: 表示Not Found,即请求的资源不存在 500: 表示Internal Server Error,即服务器内部错误 503: 表示Server Unavailable,即服务器临时不能处理客户端请求(稍后可能可以)
6>.错误处理
在Restful API设计中，错误处理也非常重要。单单从状态码中无法详尽描述错误的信息。
返回消息,如下所示:
{
error:"User Not Found"
}
从错误中了解到错误号,错误信息,错误描述等信息。甚至更详细的信息可以通过code查阅文档,如下所示,code为0表示无错误,非0表示有错误，就要看message中的错误描述了。
{
"code":10086,
"message":"Invalid ID",
"description":"More details"
}
7>.版本
强烈要求使用版本，版本号使用简单数字，例如v2。
常见的有以下两种风格:
http://api.yinzhengjie.org.cn/v1/posts/10 //这种风格会跨域，适合较大的项目
http://www.yinzhengjie.org.cn/api/v1/posts/10
8>.返回结果
返回数据依赖采用JSON格式，以下是简单的举例说明:
"GET /posts":
返回所有文章的列表。
"GET /posts/109":
返回id为10的文章对象。
"POST /posts":
创建新的文章并返回这个对象。
"PUT /posts/10":
更新id为10的文章并返回这个对象。
"DELETE /posts/10":
删除id为10的文章返回一个空对象。
"PATCH /posts/10":
部分更新id为10的文章数据并返回这个对象。