休息顶部

通过参考,使用Spring 5和Spring Boot 2开始学习的春天课程:

>>看看这个课程

1.问题

演变一个休息的api这是一个困难的问题,有许多可供选择的方法。本文将讨论其中一些选项。

进一步阅读:

引导一个简单的应用程序

这就是您开始了解春令生启动的方式。

探索弹簧启动测试restTemplate

了解如何在Spring Boot中使用新的TestRestTemplate来测试一个简单的API。

用泽西和春天休息API

使用泽西2和春天建立RESTful Web服务。

2.合同内容是什么?

在开始之前,我们需要回答一个简单的问题API和API之间的契约是什么客户端吗?

2.1。URIS合同的一部分?

让我们先考虑一下其余API的URI结构- 是合同的一部分吗?客户应该书签,硬否,通常依赖API的URI吗?

如果是这种情况,那么客户端与REST服务的交互将不再由服务本身驱动,而是由什么驱动Roy Fielding的电话带外信息:

在输入REST API时,除了最初的URI(书签)和一组适合目标受众的标准化媒体类型之外,不应该有任何先验知识……这里的失败意味着带外信息正在驱动交互,而不是超文本。

显然uri不是合同的一部分!!客户端应该只知道一个URI - API的入口点。在消耗API时应该发现所有其他URI。

2.2。媒体类型是合同的一部分?

那么用于资金宝搏官网188be源表示的媒体类型信息呢?这些是客户端和服务之间的合约的一部分吗?

为了成功消耗API,客户必须具有对这些媒体类型的先验知识。实际上,这些媒体类型的定义代表了整个合同。

因此,这是REST服务最应该关注的地方:

REST API应在定义用于表示资源和驾驶应用程序状态的媒体类型时,或者在定义现有标准媒体类型的扩展关系名称和/或超文本启用的标记中的媒体类型来花费几乎所有的描述性努力。

因此,媒体类型定义是契约的一部分应该是消耗API的客户端的先验知识。这是标准化进入的地方。

现在,我们对契约有了一个很好的了解,让我们继续讨论如何实际处理版本控制问题。

3.高级选项

现在让我们讨论一下REST API的高级版本控制方法:

  • URI版本化- 使用版本指示器版本URI空间
  • 媒体类型版本控制-版本资源的表示

当我们在URI空间中介绍版本时,资源的表示被视为不可变。因此,当在API中需要引入更改时,需要创建新的URI空间。

例如,假设一个API发布了以下资源——用户和权限:

http://host/v1/users http://host/v1/privileges

现在,让我们考虑一下用户API需要介绍第二个版本:

http://host/v2/users http://host/v2/privileges

当我们版本媒体类型并扩展语言时,我们经历了基于此标题的内容协商。其余的API将使用自定义供应商MIME媒体类型而不是通用的媒体类型,如application / json。我们将版本化这些媒体类型,而不是uri。

例如:

===> get / users / 3 http / 1.1接受:application / vnd.myname.v1 + json <=== http / 1.1 200 ok content-type:application / vnd.myname.v1 + JSON {“用户”:{“姓名”:“John Smith”}}

我们可以看看这个“自定义媒体类型的Rest api”文章关于这个主题的更多信息和例子。

这是什么重要的是客户对响应结构没有假设金宝搏官网188be超出媒体类型中的定义。

这就是通用媒体类型不是理想的原因。这些没有提供足够的语义信息并强制客户使用客户需要额外提示来处理资源的实际表示。

这是一个例外,它是使用一些唯一标识内容的语义的其他方式 - 例如XML模式。

4.优点和缺点

现在,我们对客户端和服务之间的契约有了一个清晰的概念,并且对API版本的选项有了一个高层次的概述,让我们讨论每种方法的优缺点。

第一的,介绍URI中的版本标识符导致了一个非常大的URI足迹。这是由于任何发布的API中的任何破坏变化都将为整个API引入整个新的表示树。随着时间的推移,这成为维护的负担以及客户的问题 - 现在有更多的选择可以选择。

URI中的版本标识符也是严重的不灵活。没有办法简单地发展单个资源的API,或者整个API的一个小子集。

正如我们之前提到的那样,这是一件无关紧要的方法。如果API的一部分移动到新版本,则整个API必须与其一起移动。这也使得从V1升级到V2的主要事业 - 这导致旧版本的升级速度和更长的日落时期。

在版本控制时,HTTP缓存也是一个主要问题。

从中间的代理高速缓存的角度来看,每个方法都具有优缺点。如果URI是版本的,则缓存将需要保留每个资源的多个副本 - 对于API的每个版本。这对缓存进行了负载,并且由于不同的客户端将使用不同的版本,因此降低了缓存命中率。

此外,一些缓存失效机制将不再起作用。如果媒体类型是版本控制的,那么客户端和服务都需要支持不同HTTP头表示有多个版本正在被缓存。

来自客户端缓存的视角但是,对媒体类型进行版本化的解决方案比uri包含版本标识符的解决方案所涉及的工作稍微多一些。这是因为当键是URL时比媒体类型更容易缓存某些内容。

让我们通过定义一些目标来结束本节API演变):

  • 保持兼容的更改
  • 避免使用新的主要版本
  • 使改变向后兼容
  • 考虑向前兼容金宝搏官网188be

5. API可能更改

接下来,让我们考虑一下REST API的变化类型——在这里介绍:

  • 表示格式更改
  • 资源变更

5.1。添加到资源的表示

媒体类型的格式文档应该在设计时考虑到向前兼容性。具体来说,客户端应该忽略它不理解的信息(JSON比XML做得更好)。

现在,在资源的表示中添加信息不会破坏现有的客户端,如果这些信息被正确实现。

继续我们之前的示例,添加数量在代表的情况下用户不会有突破性的改变:

{"用户":{“名称”:“约翰·史密斯”,“数量”:" 300 "}}

5.2。删除或更改现有的表示

在现有表示的设计中删除、重命名或通常重组信息对客户来说是一个重大改变。这是因为他们已经了解并依赖旧格式。

这是内容协商进来的地方。对于此类更改,我们可以添加新的供应商MIME介质类型。

让我们继续前面的例子。说我们想打破名称用户进入

===> GET /users/3 HTTP/1.1 Accept: application/vnd.myname. GET /users/3v2+json <=== HTTP/1.1 200 OK Content-Type: application/vnd.myname. jsonv2 + json{"用户":{“firstname”:“约翰”,“姓”:“史密斯”,“数量”:" 300 "}}

因此,这表明客户端的更改 - 必须要求新的表示并了解新的语义。但是,URI空间将保持稳定,不会受到影响。

5.3。主要的语义变化

这些更改包括参考资料的含义、它们之间的关系或在后端映射到的内容。这种更改可能需要新的媒体类型,或者他们可能需要在旧的旁边发布新的兄弟资源,并利用链接到点。

虽然这听起来像在URI中使用版本标识符再次使用,但重要的区别是新资源是否独立于API中的任何其他资源发布并且不会在根上派生整个API。

其余的API应该遵守Hateyoas约束。据此,大多数URI都应被客户发现,而不是硬致的。改变这种URI不应被视为不兼容的变化。新的URI可以替换旧的URI和客户端将能够重新发现URI和仍然的功能。

但是值得注意的是,尽管在URI中使用版本标识符是有问题的,这不是不依赖的以任何方式。

6.结论

本文试图提供非常多样化和难题的概述演进一个REST服务。我们讨论了每一个的共同解决方案,优点和缺点,以及在休息的背景下对这些方法的推理方式。金宝搏官网188be

本文通过履行第二种解决方案的案件 -版本控制媒体类型在检查RESTFUL API的可能更改时。

可以找到本教程的全面实现GitHub项目

7.进一步阅读

通常,这些阅读资源贯穿全文,但在这种情况下,有太多好的:

休息底部

使用Spring 5和Spring Boot 2开始,通过学习的春天课程:

>>看看这个课程
评论在本文上关闭!