Restful API的设计与实践
程序员文章站
2022-04-26 19:47:55
...
本文转自简书
Restful这个名称应该很多人都不陌生，但是我发现不少人对Restful存在或多或少的理解偏差，其中不泛比较厉害的程序员，所以有必要为Restful来“正名”。
Restful是一种软件架构风格，设计风格而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。（详见百度百科介绍）
Restful的关键是抽取资源，使用URL与资源进行对应。这边也是多数人理解有偏差之处，即Restful应该理解为面向资源的架构风格，URL的设计应该是从资源的角度出发，而不应有任何的“动作”设计，其中单个资源共享同一个接口，而不同的“动作”通过请求的方法进行区分。这也是和RPC调用方式或RPC-Restful混合调用方式最大的不同之处。
那么为什么要使用Restful风格？有什么优势？
1、统一接口：约定大于配置，有了统一的规范，大家在接口设计时能够保证理解的一致性，这样首先便于接口的理解。另外同一资源URL一致，不同的CURD操作通过不同的Http协议方法进行区分，这样在设计上做到了简化。统一接口还有个非常容易被忽视的好处，就是方便使用Http协议自带的缓存机制对请求进行缓存操作，这样在一定程度上又提高了请求的性能。
2、无状态性：由于使用Http协议进行调用，每个请求都包含了服务器所需的全部信息，所以这种方式非常适用于异构系统之间的调用，同时也良好地支持分布式架构，可以动态地扩展服务器。这也是一个非常明显的优势。
Restful风格非常好，具体如何设计？
1、提取资源： 这一步非常关键，也是Restful的核心思想所在。在面向对象的世界里，对于资源的识别不算太难，一般情况下资源即是想要处理的对象，如果对应到表结构上面，可能就是表对应的实体。例如电子商务网站上的下订单，那资源就是订单；如果是商品展示，那资源就是商品。当然这是最简单的情况，如果稍微复杂一点，比如现在是家电类的商品展示怎么办呢？那资源就是商品-家电类。像上面所述的情况，资源比较好识别，而有些情况下资源就不是那么明显了，比如登录，这是哪门子资源？这种情况确实不太好抽象，不过可以理解为登录信息资源。登录操作是对登录信息资源的新增操作。还有其它更复杂的情况，这个就得发挥面向资源的思路做进一步的抽象了。
2、URI设计： URI的设计其实与资源提取紧密相关，基本只要资源提取出来了，URI只是相应地翻译成地址就可以，有层级的资源通过分隔符进行路径区分。例如上面提到的商品展示可以是/goods，家电类商品可以/goods/elecequipt/，而登录可以是/loginInfo。
3、具体的动作： 这个严格说来并不是设计的一部分，是属于规范的一部分。因为使用Http协议，而协议中正好有相应的方法支持，所以正好使用Http协议的方法。（1）GET：获取资源的方法；（2）PUT：更新资源的方法；（3）POST:创建资源的方法；（4）DELETE：删除资源的方法。这几个 是比较常用的，还有几个不太常用的方法：（5）OPTIONS：查看资源支持哪些方法；（6）HEAD：与PUT类似，只不过HEAD只返回报头，不返回表示。
这里需要着重提一下，很多Restful-RPC混合模式可能就只会使用POST方法，这里就是混合模式与Restful风格最明显的区别之一。
4、返回结果： 返回结果包括Http请求的状态码和资源的表述。很多情况下API的返回结果使用Json或者XML格式表示，而Json是更加常用的。因为Json相比XML更加轻量，这样在传输过程中资源更小传输更快，另外Json的解析支持更广，所以解析起来非常方便。
5、缓存： Http协议是天然支持缓存的，这个也有利于性能的提升。当然服务端也可以添加缓存提高性能，这是另一个话题。缓存具体的实现在Http Header里面进行设置，例如Cache-Control、Expires。具体用法可以参见协议头描述：http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
6、安全性： 如果资源是公开的，那也没有什么安全性可言了。但是实际情况是很多资源是有对应的“权限”进行操作的，这个时候就需要进行身份的认证，认证才能够进行相应的操作。所以安全性也是设计中很重要的一环。
那么安全性如何保证呢？在Http协议中有Authorization头可以进行相关设置，最基本的可以使用Basic方式，更加安全的加密方式使用Digest方式，更进一步提高安全性还可以使用第三方的OAuth协议进行认证，OAuth也是经常采用的方式。具体使用可参考网上看到的一篇非常好的博文：理解OAuth2.0。另外为了安全性的保证，大多数情况下还会选用https协议进行传输。
设计的思路有了，那么该如何付诸实践？
1、使用场景： 前面也提到了，Restful风格特别适合于异构系统之间的调用，另外在分布式场景中也比较适用。比如现在移动端APP的接口设计很多都采用这种风格，另外有不少云平台提供的服务接口也大多采用Restful风格设计。使用还是比较广泛的。
2、实践示例： 说了半天理论还是略显空洞，下面直接来点示例加深下理解。限于篇幅，这里推荐几个看到的比较好的例子。
简单情况下的使用示例可以参考网上看到的一篇非常好的博文：理解Restful架构。
稍微复杂一点的情况可以考虑现在比较知名的云平台的API设计，比如百度云推送API设计：http://push.baidu.com/doc/restapi/restapi。另外还推荐一个看到的Saas服务商的Restful设计文档，写得很好，环信的聊天API设计：http://docs.easemob.com/doku.php?id=start:100serverintegration。
这边有几个有意思的地方可以特别关注下，比如API中的安全认证设计、接口输入输出设计。另外如果看得仔细，可能会注意到百度云平台推送平台的API设计可能与前面提到的Restful本身的设计思路有些出入，百度云推送的设计方式严格说来应该算是Restful-Rpc混合模式的设计。不过也不影响做为参考。
3、框架支持： 这里以Java版本的为例。Java对于Restful有一个规范定义JAX-RS，而支持Restful框架也不少，比如：Restlet、Jersey、RESTEasy、CXF。这几个框架的比较可以参考这篇博文：http://www.infoq.com/cn/news/2008/10/jaxrs-comparison/。我对Restlet和Jersey进行了简单了解，没有做深入的使用，觉得Restlet的文档是做得更好的。
除了上面提到的框架，现在非常流行的Spring MVC框架也对Restful有良好的支持，比如可以参考这篇的实践：http://www.importnew.com/7903.html，Spring框架的支持还是非常不错的。
Restful这个名称应该很多人都不陌生，但是我发现不少人对Restful存在或多或少的理解偏差，其中不泛比较厉害的程序员，所以有必要为Restful来“正名”。
Restful是一种软件架构风格，设计风格而不是标准，只是提供了一组设计原则和约束条件。它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。（详见百度百科介绍）
Restful的关键是抽取资源，使用URL与资源进行对应。这边也是多数人理解有偏差之处，即Restful应该理解为面向资源的架构风格，URL的设计应该是从资源的角度出发，而不应有任何的“动作”设计，其中单个资源共享同一个接口，而不同的“动作”通过请求的方法进行区分。这也是和RPC调用方式或RPC-Restful混合调用方式最大的不同之处。
那么为什么要使用Restful风格？有什么优势？
1、统一接口：约定大于配置，有了统一的规范，大家在接口设计时能够保证理解的一致性，这样首先便于接口的理解。另外同一资源URL一致，不同的CURD操作通过不同的Http协议方法进行区分，这样在设计上做到了简化。统一接口还有个非常容易被忽视的好处，就是方便使用Http协议自带的缓存机制对请求进行缓存操作，这样在一定程度上又提高了请求的性能。
2、无状态性：由于使用Http协议进行调用，每个请求都包含了服务器所需的全部信息，所以这种方式非常适用于异构系统之间的调用，同时也良好地支持分布式架构，可以动态地扩展服务器。这也是一个非常明显的优势。
Restful风格非常好，具体如何设计？
1、提取资源： 这一步非常关键，也是Restful的核心思想所在。在面向对象的世界里，对于资源的识别不算太难，一般情况下资源即是想要处理的对象，如果对应到表结构上面，可能就是表对应的实体。例如电子商务网站上的下订单，那资源就是订单；如果是商品展示，那资源就是商品。当然这是最简单的情况，如果稍微复杂一点，比如现在是家电类的商品展示怎么办呢？那资源就是商品-家电类。像上面所述的情况，资源比较好识别，而有些情况下资源就不是那么明显了，比如登录，这是哪门子资源？这种情况确实不太好抽象，不过可以理解为登录信息资源。登录操作是对登录信息资源的新增操作。还有其它更复杂的情况，这个就得发挥面向资源的思路做进一步的抽象了。
2、URI设计： URI的设计其实与资源提取紧密相关，基本只要资源提取出来了，URI只是相应地翻译成地址就可以，有层级的资源通过分隔符进行路径区分。例如上面提到的商品展示可以是/goods，家电类商品可以/goods/elecequipt/，而登录可以是/loginInfo。
3、具体的动作： 这个严格说来并不是设计的一部分，是属于规范的一部分。因为使用Http协议，而协议中正好有相应的方法支持，所以正好使用Http协议的方法。（1）GET：获取资源的方法；（2）PUT：更新资源的方法；（3）POST:创建资源的方法；（4）DELETE：删除资源的方法。这几个 是比较常用的，还有几个不太常用的方法：（5）OPTIONS：查看资源支持哪些方法；（6）HEAD：与PUT类似，只不过HEAD只返回报头，不返回表示。
这里需要着重提一下，很多Restful-RPC混合模式可能就只会使用POST方法，这里就是混合模式与Restful风格最明显的区别之一。
4、返回结果： 返回结果包括Http请求的状态码和资源的表述。很多情况下API的返回结果使用Json或者XML格式表示，而Json是更加常用的。因为Json相比XML更加轻量，这样在传输过程中资源更小传输更快，另外Json的解析支持更广，所以解析起来非常方便。
5、缓存： Http协议是天然支持缓存的，这个也有利于性能的提升。当然服务端也可以添加缓存提高性能，这是另一个话题。缓存具体的实现在Http Header里面进行设置，例如Cache-Control、Expires。具体用法可以参见协议头描述：http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html
6、安全性： 如果资源是公开的，那也没有什么安全性可言了。但是实际情况是很多资源是有对应的“权限”进行操作的，这个时候就需要进行身份的认证，认证才能够进行相应的操作。所以安全性也是设计中很重要的一环。
那么安全性如何保证呢？在Http协议中有Authorization头可以进行相关设置，最基本的可以使用Basic方式，更加安全的加密方式使用Digest方式，更进一步提高安全性还可以使用第三方的OAuth协议进行认证，OAuth也是经常采用的方式。具体使用可参考网上看到的一篇非常好的博文：理解OAuth2.0。另外为了安全性的保证，大多数情况下还会选用https协议进行传输。
设计的思路有了，那么该如何付诸实践？
1、使用场景： 前面也提到了，Restful风格特别适合于异构系统之间的调用，另外在分布式场景中也比较适用。比如现在移动端APP的接口设计很多都采用这种风格，另外有不少云平台提供的服务接口也大多采用Restful风格设计。使用还是比较广泛的。
2、实践示例： 说了半天理论还是略显空洞，下面直接来点示例加深下理解。限于篇幅，这里推荐几个看到的比较好的例子。
简单情况下的使用示例可以参考网上看到的一篇非常好的博文：理解Restful架构。
稍微复杂一点的情况可以考虑现在比较知名的云平台的API设计，比如百度云推送API设计：http://push.baidu.com/doc/restapi/restapi。另外还推荐一个看到的Saas服务商的Restful设计文档，写得很好，环信的聊天API设计：http://docs.easemob.com/doku.php?id=start:100serverintegration。
这边有几个有意思的地方可以特别关注下，比如API中的安全认证设计、接口输入输出设计。另外如果看得仔细，可能会注意到百度云平台推送平台的API设计可能与前面提到的Restful本身的设计思路有些出入，百度云推送的设计方式严格说来应该算是Restful-Rpc混合模式的设计。不过也不影响做为参考。
3、框架支持： 这里以Java版本的为例。Java对于Restful有一个规范定义JAX-RS，而支持Restful框架也不少，比如：Restlet、Jersey、RESTEasy、CXF。这几个框架的比较可以参考这篇博文：http://www.infoq.com/cn/news/2008/10/jaxrs-comparison/。我对Restlet和Jersey进行了简单了解，没有做深入的使用，觉得Restlet的文档是做得更好的。
除了上面提到的框架，现在非常流行的Spring MVC框架也对Restful有良好的支持，比如可以参考这篇的实践：http://www.importnew.com/7903.html，Spring框架的支持还是非常不错的。
上一篇： 大型网站架构技能图谱（Java版）
下一篇： JAVA EE 5 - 7 整理