RESTful杂记

前言

在网上找了许久的关于REST的资料，发现网上大部分都是说的比较片面，虽然有部分说出了本质，但也没有详细提出，因此在这里记录一下。

RESTful是什么

首先，维基百科是这样说的：

表现层状态转换（REST，英文：Representational State Transfer）是Roy Thomas Fielding博士于2000年在他的博士论文中提出来的一种万维网软件架构风格，目的是便于不一样软件/程序在网络（例如互联网）中互相传递信息

这样的概念有点难以理解，了解一个东西，一般能够先了解他的背景，他是为了解决什么问题而出现的？

Fielding是一个很是重要的人，他是HTTP协议（1.0版和1.1版）的主要设计者、Apache服务器软件的做者之1、Apache基金会的第一任主席。

而下面则是他在论文中提出REST的目的。

"本文研究计算机科学两大前沿----软件和网络----的交叉点。
长期以来，软件研究主要关注软件设计的分类、设计方法的演化，不多客观地评估不一样的设计选择对系统行为的影响。
而相反地，网络研究主要关注系统之间通讯行为的细节、如何改进特定通讯机制的表现，经常忽视了一个事实，那就是改变应用程序的互动风格比改变互动协议，对总体表现有更大的影响。
我这篇文章的写做目的，就是想在符合架构原理的前提下，理解和评估以网络为基础的应用软件的架构设计，获得一个功能强、性能好、适宜通讯的架构。"

这段话比较绕口，总结一下，就是REST是一个为了进一步解耦client和server的架构风格。

REST风格

首先，根据论文能够得知，REST风格是由约束来定义的

Web 架构背后的设计基本原理，可以被描述为由一组应用于架构中元素之上的约束组成
的架构风格。当将每一个约束添加到进化中的风格时，会产生一些影响。经过检查这些影响，
咱们就可以识别出 Web 的约束所致使的属性。而后就可以应用额外的约束来造成一种新的
架构风格，这种风格可以更好地反映出现代 Web 架构所期待的属性。

client-servet

client-server之间的解耦，服务提供者和服务消费者互不影响，也是咱们常说的先后端分离。先后端分离的优点是比较显著的，改善了用户接口跨多个平台的可移植性；同时经过简化服务器组件，改善了系统的可伸缩性。

无状态

这个约束使架构拥有了可见性、可靠性和可伸缩性等三个架构属性。
可见性是指能单独的理解一个请求，可靠性是减轻了从局部故障中恢复的任务量， 可伸缩性是指为没必要在多个请求之间保 存状态，从而容许服务器组件迅速释放资源。

可缓存

优点明显，不赘述。

统一接口

它强调组件之间要有 一个统一的接口。经过在组件接口上应用通用性的软件工程原则，总体的系统架 构获得了简化，交互的可见性（经过方法名即知道动做）也获得了改善。实现与它们所提供的服务是解耦的，这促进了独立的可进化性。
然而，付出的代价是，统一接口下降了效率，由于信息都使用标准化的形 式来转移，而不能使用特定于应用的需求的形式。（只能使用put post delete get patch等）
解决方法：为须要的动做增长一个 endpoint，使用 POST 来执行动做，好比 POST /resend 从新发送邮件。

分层系统

分层系统风格经过限制组件的行为（即，每一个组件只 能“看到”与其交互的紧邻层），将架构分解为若干等级的层。经过将组件对系统的知识限 制在单一层内，为整个系统的复杂性设置了边界，而且提升了底层独立性。
咱们可以使用层来封装遗留的服务，使新的服务免受遗留客户端的影响，经过将不经常使用的功能转移到一个共享的中间组件中，从而简化组件的实现。中间组件还可以经过支持跨多个网络和处理器的负 载均衡，来改善系统的可伸缩性。
也就是说服务器和客户端之间的中间层（代理，网关等）代替服务器对客户端的请求进行回应，而客户端不须要关心与它交互的组件以外的事情。

按需加载代码

经过下载并执行 applet 形式或脚本形式的代码，REST容许对客户端的功能进行扩展。经过减小必须被预先实现的功能的数目，简化了客户端的开发。容许在部署以后下载功能代 码也改善了系统的可扩展性。然而，这也下降了可见性，所以它只是REST的一个可选的约束。

设计原则（GITHUB API）

了解了REST是什么东西后，咱们才能设计出合适的API，如下是根据GITHUB API来总结的（基本参考自：https://cizixs.com/2016/12/12...）

使用https

这个和 Restful API 自己没有很大的关系，可是对于增长网站的安全是很是重要的。

API地址和版本

若是 API 变化比较大，能够把 API 设计为子域名，好比 https://api.github.com/v3

响应内容

尽可能使用JSON，JSON在多种语言中支持，若是须要使用其余的如XML， 应该在请求头部 Accept 中指定

以资源为中心

资源分为单个文档和集合，尽可能使用复数来表示资源，单个资源经过添加id或者name等来表示。一个资源能够有多个不一样的 URL。资源能够嵌套，经过相似目录路径的方式来表示，以体现它们之间的关系。

/users/:username/repos
/users/:org/repos
/repos/:owner/:repo
/repos/:owner/:repo/tags
/repos/:owner/:repo/branches/:branch

使用正确的METHOD

这个比较容易理解，即get（获取），post（建立），put（替换），patch（局部更新），delete（删除），head（获取某个资源的头部信息。好比只想了解某个文件的大小，某个资源的修改日期等）

对于不符合CURD的状况，能够采用参数协助

如分页page=2&per_page=100：指定第几页，以及每页的记录数，或者增长一个endpoint，如上面说的重发邮件，或者将动做转换为资源（Github:好比“喜欢”一个 gist，就增长一个 /gists/:id/star 子资源，而后对其进行操做：“喜欢”使用 PUT /gists/:id/star，“取消喜欢”使用 DELETE /gists/:id/star）

状态码

https://developer.mozilla.org...

• 2XX：请求正常处理并返回
• 3XX：重定向，请求的资源位置发生变化
• 4XX：客户端发送的请求有错误
• 5XX：服务器端错误

错误处理

返回错误时，在响应内容里加上具体的错误信息。

Hypermedia API

当服务端修改API时，客户端不须要知道和修改。

验证和受权， OAUTH2等

限流， 参考github

https://developer.github.com/...
对用户的请求限流以后，要有方法告诉用户它的请求使用状况，Github API 使用的三个相关的头部：

X-RateLimit-Limit: 用户每一个小时容许发送请求的最大值
X-RateLimit-Remaining：当前时间窗口剩下的可用请求数目
X-RateLimit-Rest: 时间窗口重置的时候，到这个时间点可用的请求数量就会变成 X-RateLimit-Limit 的值

编写清晰的文档

REST与http的关系？

我的理解是REST是一种架构风格，而http则是这种架构实现下的一种协议。

比较（以操做为中心）

• 以操做为中心可见性低，即不够清晰。
• 在除了CURD的接口外，以操做为中心调用效率高，不须要hack。
• 以操做为中心没有HyperMidea Api，修改api效率低，须要客户端服务端同时修改。
• 以操做为中心上手难度系数大。
• 以资源为中心，简单数据操做，无事务处理，开发和调用简单， 以操做为中心，清晰的规范标准定义，可以处理较为复杂的面向活动的服务

在一般的软件开发过程当中，咱们经常须要分析达成某个目标所须要使用的业务逻辑，并为业务逻辑的执行提供一系列运行接口。在一些Web服务中，这些接口经常表达了某个动做，如将商品放入购物车，提交订单等。这一系列动做组合在一块儿就能够组成完成目标所须要执行的业务逻辑。在须要调用这些接口的时候，软件开发人员须要向这些接口所在的URL发送一个请求，从而驱使服务执行该动做