Restful接口设计的学习和实践之路

REST接口在前几年是很火的，关于REST与SOAP有着无数的口水战，现在随着restful接口逐渐作为行业的事实上的标准普及开来应该已经没有什么异议了，这篇文章接口为什么要使用restful风格的以及在近几年的开发中restful接口设计的更新。

什么是Rest

REST是“表现层状态转移（REpresentational State Transfer）”的缩写。并不是一种标准或规范，实际上是一种架构和接口风格，在客户端和服务端之间通过呈现状态的转移来驱动应用状态的演进。

这么解释估计还是不太好理解，太学术了。
那下面的例子可以比较好的说明Rest定义，例子是转载的哦。

Marcus是一个农民，他有4头牛，12只鸡和3头奶牛。他现在模拟一个REST API，而我是客户端。如果我想用REST来请求当前的农场状态，我仅会问：“State？”Marcus会回答：“4头猪、12只鸡、3头奶牛”。

这是REST最简单的一个例子。Marcus使用表征来传输农场状态。表征的句子很简单：“4头猪、12只鸡、3头奶牛”。

接口为什么要Restful

到底什么引起了Restful接口的流行呢？
我觉得是近几年互联网发展导致各个公司开发的系统规模逐步扩大，各个服务提供者越来越多的以独立的组件或中间件的形式出现，各个系统之间的对接工作大幅提高，而Restful接口设计由于其轻量级、简约的风格、效率、生产者和消费者的耦合性低受到各大公司的青睐，同时由于restful接口的无状态特性使大规模应用的故障替换有了非常理想的解决方案，用户不会有任何感觉，更关键的是热备方案可以与业务完全隔离开，因此Restful接口风格迅速普及开来。
以下是Restful接口的几个优点：
1. 接口的易用性，关于这一点请详见参考资料.
2. 解耦，由于将业务都转换为资源同时服务端不用关心客户端之前的操作状态，使客户端与服务端能够做到大幅度的设计解耦；
3. 效率与代码的简洁性，如果使用SOAP接口的话，还记得WSDL2java生成的那一堆大部分没用的代码么，看着就头疼，要是与十几个系统进行webservice接口对接，而且各家规范还不一样，想想就可怕。
还有其他的缓存什么就不详细介绍了。
但是有一个问题，rest接口的安全问题并没有在规范中提及因此各家实现的方式并不一致，因此这个问题需要注意，这也是在传统注重安全的公司中webservice还是主流的原因。

我的Restful实践之路

这是什么

那是参加的第一个项目，正值2013年底，当时也是Restful接口在国内逐渐普及的时候，当时项目前天采用html+css+jquery的方式，后台采用osgi+spring+jpa的架构。
我作为一个新手加入进来，起初看着每个接口都有一个requestmapping很奇怪，后台做前台时知道只要这个uri一致就能访问到后台服务，这背后的理论缺并不了解。后来我在阅读系统方案时才了解到这样的接口是符合rest风格的。当然当时主要是追时髦，我记得写的最多的接口名就是findById，实际上有着Rest的名却不是rest的思想。

原来是这样

我作为项目技术负责人参加到了第二个项目中，此时我已经习惯了之前的接口方式。由于我们前端能力不足，我们的前端开发是外包给另一家小规模互联网公司了，当我拿出了我设计的接口时，对方的负责人很认真的向我们介绍了他们使用rest经验，并给出了接口的修改意见，现在回想起来确实很感谢他们，为我打开了一扇门。
之后我才去查了restful接口相关的知识，确实我们之前的接口只有rest名，经过一番大改并组织团队一起学习和讨论定下了新的接口。
当时对于rest的认识也只是停留在get是查，post创建，put和patch是修改，delete是删除的阶段。

感觉哪里不对

但随着项目的推进，我发现外包公司的经验也有问题，比如最简单的用户登录和注销接口应该是什么样子的呢？是使用get方法，uri:api/user/login?username=XX&&password=123么，但login是动词啊，这不符合rest风格啊。还有rest接口中关于业务流程该怎么说明呢，我怎么知道这个资源能干什么啊，只能开发人员相互确定么等等。
这方面的疑问还是很多的，后来我又找到了更多的相关资料来阅读，疑问才逐渐的解开。最终的了解到了Hypermedia这个概念，接口中的_link可以添加资源相关的其他业务接口等等。

新的实践

有了之前的经验，我系统的查阅了rest相关资料，拜读了Roy Fielding的论文和很多源头性资料，发现了以前接口设计的问题，更重要的是了解到为什么要restful。

Richardson成熟度模型

在这里我只介绍这个模型关于rest应用的几个级别，详细信息请参考文末的链接。
level 0：The Swamp of POX,基本是RPC的一套对接流程，需要关心对接方的业务
level 1：Resources，将业务向资源转化，不管什么操作都是get
level 2：HTTP Verbs，能够通过post，put，get来进行业务操作
典型表现:
取东西就要GET（GET就是安全的，不会修改服务资源），新增就要POST（POST就是不安全的），修改就要PUT(PUT就要幂等)，删除就是DELETE(DELETE就要幂等)….优雅的展示你的资源，甚至让别人不看协议就能找到这个资源.
level 3:: Hypermedia Controls，通过接口的自描述来说明接口，通过_links的内容就能了解到相关的业务如何进行交互。
接口返回值应该差不多是这样的：
{
“tracking_id”: “123456”,
“status”: “WAIT_PAYMENT”,
“items”: [
{
“name”: “potato”,
“quantity”: 1
}
],
“_links”: {
“self”: {
“href”: “http://localhost:57900/orders/123456”
},
“cancel”: {
“href”: “http://localhost:57900/orders/123456”
},
“payment”: {
“href”: “http://localhost:57900/orders/123456/payments”
}
}
}

Restful接口的常见设计问题

1. 接口的地址中含有动词或方法
2. 没有_link的相关接口链接
3. 自己造Hypermedia
4. URI要中统一使用小写字母

关于Rest接口的设计具体规范我这里就不一一列举了，网上这方面的资源非常多，主要是关于URI设计，请求的方法以及HTTP标准状态码的应用。

参考资源

http://hippoom.github.io/blogs/value-of-hypermedia-from-client-perspective.html
https://martinfowler.com/articles/richardsonMaturityModel.html
http://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm