前后端分离-Restful最佳实践

　　　　　　　　　　　　　　　　前后端分离-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的文章数据并返回这个对象。