资讯频道 → 企业架构
阅读更多

4顶
0踩

企业架构

转载新闻 Restful API的设计与实践

2015-12-08 19:01 by 副主编 mengyidan1988 评论(0) 有6591人浏览
API 开放平台
本文转自简书
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框架的支持还是非常不错的。
来自: 简书
4
顶
0
踩
评论 共 0 条 请登录后发表评论

发表评论

您还没有登录,请您登录后再发表评论

相关推荐

  • RESTful API 设计最佳实践

    这些REST的关键原则与将你的 API 分割成逻辑资源紧密相关。使用HTTP请求控制这些资源，其中，这些方法（GET, POST, PUT, PATCH, DELETE）具有特殊含义。 一旦定义好了资源, 需要确定什么样的 actions 应用它们，...

  • RESTful API设计与实践

    RESTful API即遵循REST原则的API，采用HTTP方法（GET、POST、PUT、DELETE等）对资源进行操作，使得不同平台和语言的客户端可以轻松地与服务器进行交互。本文介绍了RESTful API的概念、优势、应用场景以及常见问题和...

  • RESTful API 设计最佳实践1

    Roy Felding 在他论文 network based software architectures 的 第五章 中首次介绍了这些原则。这些REST的关键

  • Restful API 设计实践

    第一次接触Restful API设计规范是在本科的软工课上，当时懵懵懂懂的跟着助教的指导了解了Restful API的一些内容。后来在实验室产品的开发中第一版后端的API设计被同学吐槽不够Restful。由于接下来一段时间要做后端的...

  • RESTful图书管理系统架构设计-restful api 设计最佳实践WORD范本.docx

    RESTful图书管理系统架构设计-restful api 设计最佳实践WORD范本.docx

  • RESTful API设计最佳实践（转译）

    RESTful API设计最佳实践（转译）每个资源，使用两个URL用名词替代动词表示URL使用HTTP方法来操作URL在表示集合URL上，使用POST来创建新的资源在表示特定袁术URL上，使用PUT来表示更新资源坚持使用复数名词使用“？...

  • Restful API规范及实践

    RESTful API 最佳实践 22条API设计的最佳实践 1.定义 1.1 RESOUCE（资源） 对象的单个实例。 例如，一只动物。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。你可以用一个URI（统一资源...

  • RESTful API 设计指南，RESTful API 设计最佳实践

    RESTful API 设计指南，RESTful API 设计最佳实践 网络应用程序，分为前端和后端两个部分。当前的发展趋势，就是前端设备层出不穷（手机、平板、桌面...RESTful API是目前比较成熟的一套互联网应用程序的API设计...

  • RESTful API 设计最佳实践（7）

    RESTful API 设计最佳实践（7）本篇博客将侧重介绍在RESTful API设计中，消息头HEADER和消息体body相关的东西。URL只是RESTful API设计的主要一部分，要实现REST的统一接口，HTTP协议中的其他部分也不可或缺。关于...

  • Restful api 设计最佳实践

    ● CURD的操作 ○ GET /users # 获取user列表 ○ GET /users/12 # 查看某个具体的user ○ POST /users # 新建一个user ○ PUT /users/12 # 更新user 12 ○ DELETE /users/12 #删除user 12 ...

  • RESTful API设计与实现

    RESTful API是遵循REST原则的Web API。它使用简单、通用的方法（如HTTP方法）来操作资源（如Web页面、数据对象等）。无状态：服务器不保存客户端的状态信息，每个请求都包含处理该请求所需的所有信息。客户端-服务器...

  • RESTful API 设计实践

    RESTful是目前流行的API设计规范，遵守这套规范设计出的API可以较好的适用不同类型的客户端，例如：PC/Mobile/Pad… RESTful 表现层状态转换（英语：Representational State Transfer，缩写：REST）是Roy Thomas ...

  • 【开发规范】API设计风格 RESTful API

    二、API设计： 1.API请求设计： 2.API响应设计： 三、API请求详解： 1.HTTP动词： 2. URL（宾语）必须是名词： 3.过滤信息（Filtering）： 4.不符合 CRUD 情况的 RESTful API： 5.动词覆盖，应对服务器不...

  • RESTful API 设计与最佳实践

    在这个系列博客中，我们将深入了解RESTful API的设计原则、优势、弊端以及一些建议，帮助你更好地构建和使用RESTful API。RESTful API 是一种基于资源的设计风格，通过标准的HTTP方法（如GET、POST、PUT、DELETE）对...

  • spring-ai-spring-boot-autoconfigure-1.0.0-M5.jar中文文档.zip

    # 【spring-ai-spring-boot-autoconfigure-***.jar中文文档.zip】 中包含： 中文文档：【spring-ai-spring-boot-autoconfigure-***-javadoc-API文档-中文(简体)版.zip】 jar包下载地址：【spring-ai-spring-boot-autoconfigure-***.jar下载地址(官方地址+国内镜像地址).txt】 Maven依赖：【spring-ai-spring-boot-autoconfigure-***.jar Maven依赖信息(可用于项目pom.xml).txt】 Gradle依赖：【spring-ai-spring-boot-autoconfigure-***.jar Gradle依赖信息(可用于项目build.gradle).txt】 源代码下载地址：【spring-ai-spring-boot-autoconfigure-***-sources.jar下载地址(官方地址+国内镜像地址).txt】 # 本文件关键字： spring-ai-spring-boot-autoconfigure-***.jar中文文档.zip,java,spring-ai-spring-boot-autoconfigure-***.jar,org.springframework.ai,spring-ai-spring-boot-autoconfigure,***,org.springframework.ai.autoconfigure.anthropic,jar包,Maven,第三方jar包,组件,开源组件,第三方组件,Gradle,springframework,spring,ai,boot,autoconfigure,中文API文档,手册,开发手册,使用手册,参考手册 # 使用方法： 解压 【spring-ai-spring-boot-autoconfigure-***.jar中文文档.zip】，再解压其中的 【spring-ai-spring-boot-autoconfigure-***-javadoc-API文档-中文(简体)版.zip】，双击 【index.html】 文件，即可用浏览器打开、进行查看。 # 特殊说明： ·本文档为人性化翻译，精心制作，请放心使用。 ·只翻译了该翻译的内容，如：注释、说明、描述、用法讲解 等； ·不该翻译的内容保持原样，如：类名、方法名、包名、类型、关键字、代码 等。 # 温馨提示： （1）为了防止解压后路径太长导致浏览器无法打开，推荐在解压时选择“解压到当前文件夹”（放心，自带文件夹，文件不会散落一地）； （2）有时，一套Java组件会有多个jar，所以在下载前，请仔细阅读本篇描述，以确保这就是你需要的文件； # Maven依赖： ``` <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-spring-boot-autoconfigure</artifactId> <version>***</version> </dependency> ``` # Gradle依赖： ``` Gradle: implementation group: 'org.springframework.ai', name: 'spring-ai-spring-boot-autoconfigure', version: '***' Gradle (Short): implementation 'org.springframework.ai:spring-ai-spring-boot-autoconfigure:***' Gradle (Kotlin): implementation("org.springframework.ai:spring-ai-spring-boot-autoconfigure:***") ``` # 含有的 Java package（包）： ``` org.springframework.ai.autoconfigure.anthropic org.springframework.ai.autoconfigure.azure.openai org.springframework.ai.autoconfigure.bedrock org.springframework.ai.autoconfigure.bedrock.anthropic org.springframework.ai.autoconfigure.bedrock.anthropic3

  • 50页-道路环卫保洁服务项目管理计划方案.pdf

    在当今智慧城市的建设浪潮中，智慧环卫作为城市管理的重要组成部分，正以其独特的魅力引领着环卫行业的变革。本方案旨在通过一系列高科技手段，如物联网、大数据、云计算等，全面提升环卫作业效率与管理水平，为城市居民创造更加清洁、宜居的生活环境。 一、智慧环卫系统概述与核心亮点 智慧环卫系统是一个集机械化保洁、垃圾清运、设施管理、事件指挥调度等多功能于一体的综合性管理平台。其核心亮点在于通过高精度定位、实时监控与智能分析，实现环卫作业的精细化管理。例如，机械化保洁管理子系统能够实时监控机扫车、洒水车等作业车辆的运行状态，自动规划最优作业路线，并根据作业完成情况生成考核评价报表，极大地提高了作业效率与服务质量。同时，垃圾清运管理子系统则通过安装GPS定位设备和油量传感器，对清运车辆进行全方位监控，确保垃圾清运过程的规范与高效，有效解决了城市垃圾堆积与随意倾倒的问题。此外，系统还配备了垃圾箱满溢报警系统，通过智能感应技术，当垃圾箱内垃圾达到预设高度时自动报警，提醒作业人员及时清运，避免了因垃圾满溢而引发的居民投诉与环境污染。 二、智慧环卫系统的趣味性与知识性融合 智慧环卫系统不仅实用性强，还蕴含着丰富的趣味性与知识性。以餐厨垃圾收运管理子系统为例，该系统通过为餐厨垃圾收运车辆安装GPS定位、车载称重、视频监控等多种感知设备，实现了对餐厨垃圾收运过程的全程监控与智能管理。作业人员可以通过手机APP实时查看车辆位置、行驶轨迹及收运情况，仿佛在玩一场现实版的“垃圾追踪游戏”。同时，系统还能自动生成餐厨垃圾收运统计报表，帮助管理人员轻松掌握收运量、违规情况等关键数据，让数据管理变得既科学又有趣。此外，中转站视频监控子系统更是将趣味性与实用性完美结合，通过高清摄像头与双向语音对讲功能，实现了对中转站内外环境的实时监控与远程指挥，让管理人员足不出户就能掌控全局，仿佛拥有了一双“千里眼”和一对“顺风耳”。 三、智慧环卫系统的未来展望与社会价值 随着科技的不断进步与智慧城市建设的深入推进，智慧环卫系统将迎来更加广阔的发展前景。未来，智慧环卫系统将更加注重数据的深度挖掘与分析，通过大数据与人工智能技术，为城市环卫管理提供更加精准、高效的决策支持。同时，系统还将加强与其他城市管理系统的互联互通，实现资源共享与协同作战，共同推动城市管理的智能化、精细化水平。从社会价值来看，智慧环卫系统的推广与应用将有效提升城市环境卫生质量，改善居民生活环境，提升城市形象与竞争力。此外，系统还能通过优化作业流程、减少资源浪费等方式，为城市可持续发展贡献重要力量。可以说，智慧环卫系统不仅是城市管理的得力助手，更是推动社会进步与文明发展的重要力量。

  • 微信小程序驾校管理平台约车小程序demo完整源码下载-完整源码.zip

    微信小程序驾校管理平台约车小程序demo完整源码下载_完整源码

  • MATLAB实现含风电不确定性的电力系统低碳调度模型

    内容概要：本文详细介绍了使用MATLAB和YALMIP工具包构建的电力系统低碳调度模型。该模型主要解决风电和负荷不确定性带来的挑战，采用模糊机会约束处理风电预测误差，将复杂的非线性约束转化为混合整数线性规划问题。文中展示了如何通过分段线性化、大M法等技巧提高求解效率，并实现了包括火电、水电、风电、储能等多种能源类型的综合调度。此外，还讨论了碳排放成本、启停时间约束、爬坡率约束以及储能系统的建模方法。最终，通过结果可视化展示各成本构成及其对调度策略的影响。 适合人群：从事电力系统优化研究的专业人士，尤其是熟悉MATLAB编程并希望深入了解低碳调度模型的研究人员和技术人员。 使用场景及目标：适用于需要处理风电不确定性、优化电力系统调度的研究项目。目标是降低电力生产成本的同时减少碳排放，确保电力系统的稳定性和经济性。 其他说明：代码中包含了详细的注释和扩展提示，方便进一步修改与应用。对于大规模电力系统调度问题，提供了高效的求解策略和性能优化建议。

Global site tag (gtag.js) - Google Analytics