本文概述

• 当我们需要版本控制时
• 如何版本化
• 使用请求参数进行版本控制
• 使用接受标头进行版本控制

版本控制是API最重要和最困难的部分, 因为它需要向后兼容API。确定更改后, 版本控制可帮助我们更快地迭代。我们应该始终对Web API进行版本控制。
考虑一个场景, 其中我们有一个已启动（状态）并且正在运行的Web API。用户正在使用该API。现在, 我们想在Web API中添加更多功能, 但希望保持现有功能不变。可能有少数用户仍想使用旧的API, 而其他用户想要具有新功能或扩展功能的API的新版本。这是Web API版本化存在的场景。
当我们需要版本控制时 当我们对Web API进行重大更改时, 我们应该对API进行版本升级。重大更改包括：

• 一个或多个呼叫的响应数据格式的更改。
• 更改响应类型。
• 删除API的任何部分。

重大更改应始终导致API或内容响应类型的主版本号更改。
不间断的更改（添加新点或新的响应参数）不需要更改主版本号。但是, 跟踪次要版本的API可能会有所帮助。
如何版本化 最常用的方法分为三类：

• URI版本控制
• 使用自定义请求标头进行版本控制
• 使用接受标头进行版本控制

URI版本控制
URI版本控制是最直接的方法。它在URL中指定为查询字符串。它违反了URI应该引用唯一资源的原则。还保证你在更新版本时会中断客户端集成。 Twitter使用URI版本控制。
例
http://api.demo.com/v1 http://apiv1.demo.com
版本不需要是数字, 也不需要使用v [x]语法指定。备选方案包括日期, 项目名称, 季节或其他有意义的标识符, 这些标识符足以随着版本更改而更改。
使用自定义请求标头进行版本控制
自定义标头允许我们保留我们的URL。它与现有Accept标头实现的内容协商行为重复。版本信息是在请求标头中指定的, 不需要更改URL。 Microsoft使用请求标头版本控制。用户无法在普通浏览器（chrome）中访问请求标头版本。我们需要一个特殊的插件才能在浏览器中访问它们。
例
接受版本：v1接受版本：v2
使用接受标头进行版本控制
Accept标头定义媒体类型和字符编码。我们还可以通过接受标头传递Web API的版本信息, 而无需更改URL。也称为媒体类型版本控制或内容协商或接受标头。 Github使用accept标头版本控制。用户无法在普通浏览器（chrome）中访问接受标头版本控制。我们需要一个特殊的插件才能在浏览器中访问它们。
例
接受：application / vnd.demo.v1 + json接受：application / vnd.demo + json; version = 1.0
让我们看看如何在项目中实现版本控制。
URI版本控制
步骤1：在com.srcmini.server.main.versioning包中创建一个名为PersonV1.java的类。 PersonV1表示API的第一个版本。 API的初始版本具有名称变量。
PersonV1.java

package com.srcmini.server.main.versioning; public class PersonV1 {private String name; }

步骤2：经过一段时间, 我们认识到需要分别使用名字和姓氏。因此, 我们创建了一个名为Person2.java的类。它表示API的第二个版本。
PersonV2.java

package com.srcmini.server.main.versioning; public class PersonV2 {private Name name; }

步骤3：创建一个名称为Name.java的类, 该类分别具有两个变量firstName和lastName。
Name.java

package com.srcmini.server.main.versioning; public class Name {private String firstName; private String lastName; }

旧版本仍返回全名, 第二个版本分别返回firstName和lastName。现在, 我们需要创建同一服务的两个不同版本。
让我们看看如何为同一服务创建两个不同版本, 以及存在哪些不同版本的服务。
步骤4：在Name.java文件中, 生成Getter和Setter, 使用Fields生成构造函数。创建类Name的无参数构造函数。
Name.java

package com.srcmini.server.main.versioning; public class Name {private String firstName; private String lastName; //no argument constructorpublic Name() {}public Name(String firstName, String lastName) {super(); this.firstName = firstName; this.lastName = lastName; }public String getFirstName() {return firstName; }public void setFirstName(String firstName) {this.firstName = firstName; }public String getLastName() {return lastName; }public void setLastName(String lastName) {this.lastName = lastName; }}

步骤5：打开PersonV1.java类。生成Getter和Setter, 使用Fields生成构造函数。创建类PersonV1.java的无参数构造函数。
PersonV1.java

package com.srcmini.server.main.versioning; public class PersonV1 {private String name; //no argument constructorpublic PersonV1() {super(); }public PersonV1(String name) {super(); this.name = name; }public String getName() {return name; }public void setName(String name) {this.name = name; }}

步骤6：打开PersonV2.java。生成Getter和Setter, 使用Fields生成构造方法。创建类PersonV2.java的无参数构造函数。
PersonV2.java

package com.srcmini.server.main.versioning; public class PersonV2 {private Name name; public PersonV2() {super(); }public PersonV2(Name name) {super(); this.name = name; }public Name getName() {return name; }public void setName(Name name) {this.name = name; }}

现在我们需要创建一个服务。
步骤7：创建一个名为PersonVersioningController.java的类。为不同的版本创建两个方法, 并将它们映射到不同的URI。
PersonVersioningController.java

package com.srcmini.server.main.versioning; import org.springframework.web.bind.annotation.RestController; import org.springframework.web.bind.annotation.GetMapping; @RestControllerpublic class PersonVersoningController {//this method is for the first version that returns the entire name@GetMapping("v1/person")public PersonV1 personv1(){return new PersonV1("Tom Cruise"); }//this method is for the second version that returns firstName and lastName separately@GetMapping("v2/person")public PersonV2 personv2(){return new PersonV2(new Name("Tom", "Cruise")); }}

步骤8：打开邮递员, 并使用URI http：// localhost：8080 / v1 / person发送GET请求。它返回全名, 如下图所示。

文章图片
将第二个版本的URI更改为http：// localhost：8080 / v2 / person。它将分别返回firstName和lastName, 如下图所示。

文章图片
使用请求参数进行版本控制 实现版本控制的另一种方法是使用request参数。 Amazon使用请求参数版本控制。打开PersonVersioningController.java并进行以下更改：

• 将第一种方法的URI从/ v1 / person更改为/ person / param。
• 将方法的名称从personV1更改为paramV1。
• 同样, 将第二种方法的URI从/ v2 / person更改为/ person / param。

两种方法都具有相同的get映射, 因此我们将通过使用value和params属性来区分它们。 value属性包含我们要使用的URI, params属性包含区分版本的参数。
PersonVersoningController.java

package com.srcmini.server.main.versioning; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RestController; @RestControllerpublic class PersonVersoningController {//this method is for first version that returns the entire name@GetMapping(value="http://www.srcmini.com/person/param", params="version=1")public PersonV1 personV1(){return new PersonV1("Tom Cruise"); }//this method is for second version that returns firstName and lastName separately@GetMapping(value="http://www.srcmini.com/person/param", params="version=2")public PersonV2 personV2(){returnnew PersonV2(new Name("Tom", "Cruise")); }}

现在, 移至Postman并使用URI http：// localhost：8080 / person / param？version = 1发送GET请求。它返回全名, 如下图所示。

文章图片
再次, 使用URI http：// localhost：8080 / person / param？version = 2生成GET请求以访问第二个版本。它将分别返回firstName和lastName, 如下图所示。

文章图片
使用请求标头进行版本控制
还有另一个选项可以使用请求标头进行版本控制。它类似于内容协商。在这种方法中, 我们根据请求标头区分服务。
在PersonVersioningController.java中, 执行以下操作：

• 复制这两种方法并粘贴到同一文件中。
• 将方法名称paramV1更改为headerV1, 将paramV2更改为headerV2。
• 将URI / person / param替换为/ person / header, 将params替换为headers。

/*---------------using request header--------------*///this method is for first version that returns the entire name@GetMapping(value="http://www.srcmini.com/person/header", headers="X-API-Version=1")public PersonV1 headerV1(){return new PersonV1("Tom Cruise"); }//this method is for second version that returns firstName and lastName separately@GetMapping(value="http://www.srcmini.com/person/header", headers="X-API-Version=2")public PersonV2 headerV2(){return new PersonV2(new Name("Tom", "Cruise")); }

打开邮递员：

• 选择标题选项卡并设置密钥：X-API-VERSION和值：1。
• 输入URI http：// localhost：8080 / person / header并发送GET请求。

它返回名称全名。

文章图片
让我们发送版本2的GET请求。为此, 我们需要在Headers选项卡下将值从1更改为2。它分别返回firstName和lastName。

文章图片
使用接受标头进行版本控制 版本控制中使用的另一种方法是“接受标头”。也称为内容协商或接受版本控制。在此方法中, 我们使用称为Produce的属性。它表示我们正在为特定服务生成什么样的输出。
在PersonVersioningController.java文件中, 执行以下操作：

• 复制这两种方法并粘贴到同一文件中。
• 将方法名称headerV1更改为ProducesV1, 将headerV2更改为ProducesV2。
• 将URI / person / header替换为/ person / produces, 并将header替换为Produces。

/*---------------using accept header--------------*///this method is for first version that returns the entire name@GetMapping(value="http://www.srcmini.com/person/produces", produces="application/vnd.company.app-v1+json")public PersonV1 producesV1(){return new PersonV1("Tom Cruise"); }//this method is for second version that returns firstName and lastName separately@GetMapping(value="http://www.srcmini.com/person/produces", produces="application/vnd.company.app-v2+json")public PersonV2 producesV2(){returnnew PersonV2(new Name("Tom", "Cruise")); }

打开邮递员：

• 选择“标题”选项卡并设置密钥：接受和值：application / vnd.company.app-v1 + json。
• 取消选中X-API-VERSION项。
• 输入URI http：// localhost：8080 / person / produces并发送GET请求。

它返回全名。

文章图片
让我们发送版本2的GET请求。为此, 我们需要将值从Value：application / vnd.company.app-v1 + json更改为Value：application / vnd.company.app-v2 + json。
【使用URI对RESTful Web服务进行版本控制的基本方法】它分别返回firstName和lastName。

文章图片

推荐阅读

• 

  过期蜂蜜能做面膜吗 过期了的面膜可以用来做什么
• 

  男性不育症影响家庭调和 日常是如何医治的
• 

  哪些过敏体质不能打新冠疫苗能
• 

  绿豆发芽的过程
• 

  脆甜萝卜的腌制方法 脆甜萝卜如何腌制
• 

  蚊香能杀小飞虫吗
• 

  主动降噪|魅蓝官宣：主动降噪耳机219元起售 11月3日发布
• 

  妇女节温馨祝福语给妈妈
• 

  草莓有酒味还能吃吗
• 

  普洱一般几年的比较好，普洱茶的最佳年份
• 

  2023年广州7月9日放榜 广州2022年放寒假时间
• 

  痰湿中阻是怎么回事？
• 

  长沙省直公积金贷款条件是什么
• 

  华为p30锁屏壁纸怎么设置（华为p30锁屏壁纸如何设置）
• 

  顺嫔是好人吗
• 

  绿豆视频直播 绿豆夏季直播技术
• 

  红油渗入塑料pvc桌布怎么办
• 

  水刑是什么刑法
• 

  朗逸助力泵皮带怎么上 老款朗逸助力泵皮带安装方法
• 

  如何输入ip来远程 如何进行远程连接

• SOAP Web服务
• SOAP与REST Web服务的区别
• Java面向服务的架构（SOA）
• 执行RESTful服务的验证
• 配置自动生成Swagger文档
• 使用Spring Boot Actuator监视API
• Swagger文档格式简介
• 执行GET服务以检索用户的所有帖子
• 为RESTful服务实现静态过滤