本文将帮忙您了解为什么须要版本控制，以及如何对REST API进行版本控制。咱们将探讨4种版本控制的办法，并比拟不同的办法。

您将学到

  • 为什么咱们须要对RESTful API 进行版本控制?
  • 可用的版本控制有哪些?
  • 如何实现基于 Restful 的版本控制?

为什么咱们须要对RESTful API进行版本化

最好的版本控制办法是不进行版本控制。只有不须要版本控制，就不要版本控制。

构建向后兼容的服务，以便尽可能防止版本控制！

然而，在许多状况下咱们都须要进行版本控制，然咱们看看上面具体的例子：

最后，你有个这个版本的Student服务，返回数据如下：

{  "name": "Bob Charlie"}

起初，您心愿将学生的名字拆分，因而创立了这个版本的服务。

{  "name": {    "firstName": "Bob",    "lastName": "Charlie"  }}

您能够从同一个服务反对这两个申请，然而随着每个版本的需要多样化，它会变得越来越简单。

在这种状况下，版本控制就成必不可少，强制性的了。

接下来让咱们创立一个简略的SpringBoot的maven我的项目，并了解对 RESTful 服务进行版本控制的4种不同办法。

<dependencies>    <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter</artifactId>    </dependency>    <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-web</artifactId>    </dependency>    <dependency>        <groupId>org.projectlombok</groupId>        <artifactId>lombok</artifactId>    </dependency>    <dependency>        <groupId>org.springframework.boot</groupId>        <artifactId>spring-boot-starter-test</artifactId>        <scope>test</scope>    </dependency></dependencies>

几个用于实现版本控制的Bean

第一个版本的 Bean

@Data@AllArgsConstructorpublic class StudentV1 {    private String name;}

第二个版本的 Bean

@Datapublic class StudentV2 {    private Name name;}

StudentV2应用的Name实体

@Data@AllArgsConstructorpublic class Name {    private String firstName;    private String lastName;}

Restful 版本控制的办法

咱们心愿创立两个版本的服务，一个返回 StudentV1，另一个返回 StudentV2。

让咱们来看看创立雷同服务版本的4种不同办法。

通过 URI 进行版本控制

@RestControllerpublic class StudentUriController {    @GetMapping("v1/student")    public StudentV1 studentV1() {        return new StudentV1("javadaily");    }    @GetMapping("v2/student")    public StudentV2 studentV2() {        return new StudentV2(new Name("javadaily", "JAVA日知录"));    }}

申请：http://localhost:8080/v1/student

响应：{"name":"javadaily"}

申请：http://localhost:8080/v2/student

响应：{"name":{"firstName":"javadaily","lastName":"JAVA日知录"}}

通过申请参数进行版本控制

版本控制的第二种办法是应用申请参数来辨别版本。申请示例如下所示：

  • http://localhost:8080/student/param?version=1
  • http://localhost:8080/student/param?version=2

实现形式如下：

@RestControllerpublic class StudentParmController {    @GetMapping(value="/student/param",params = "version=1")    public StudentV1 studentV1() {        return new StudentV1("javadaily");    }    @GetMapping(value="/student/param",params = "version=2")    public StudentV2 studentV2() {        return new StudentV2(new Name("javadaily", "JAVA日知录"));    }}

申请：http://localhost:8080/student/param?version=1

响应：{"name":"javadaily"}

申请：http://localhost:8080/student/param?version=2

响应：{"name":{"firstName":"javadaily","lastName":"JAVA日知录"}}

通过自定义Header进行版本控制

版本控制的第三种办法是应用申请头来辨别版本，申请示例如下：

  • http://localhost:8080/student/header

    • headers=[X-API-VERSION=1]

  • http://localhost:8080/student/header

    • headers=[X-API-VERSION=2]

实现形式如下所示：

@RestControllerpublic class StudentHeaderController {    @GetMapping(value="/student/header",headers = "X-API-VERSION=1")    public StudentV1 studentV1() {        return new StudentV1("javadaily");    }    @GetMapping(value="/student/header",headers = "X-API-VERSION=2")    public StudentV2 studentV2() {        return new StudentV2(new Name("javadaily", "JAVA日知录"));    }}

下图展现了咱们如何应用Postman执行带有申请头的Get申请办法。

申请：http://localhost:8080/student/header header：X-API-VERSION = 1

申请：http://localhost:8080/student/header header：X-API-VERSION = 2

通过媒体类型进行版本控制

最初一种版本控制办法是在申请中应用Accept Header，申请示例如下：

  • http://localhost:8080/student/produce

    • headers=[Accept=application/api-v1+json]

  • http://localhost:8080/student/produce

    • headers=[Accept=application/api-v2+json]

实现形式如下：

@RestControllerpublic class StudentProduceController {    @GetMapping(value="/student/produce",produces = "application/api-v1+json")    public StudentV1 studentV1() {        return new StudentV1("javadaily");    }    @GetMapping(value="/student/produce",produces = "application/api-v2+json")    public StudentV2 studentV2() {        return new StudentV2(new Name("javadaily", "JAVA日知录"));    }}

下图展现了咱们如何应用Postman执行带有申请Accept的Get办法。

申请：http://localhost:8080/student/produce header：Accept = application/api-v1+json

申请：http://localhost:8080/student/produce header：Accept = application/api-v2+json

影响版本抉择的因素

以下因素影响版本控制的抉择

  • URI 净化 - URL版本和申请参数版本控制会净化URI空间。
  • 滥用申请头 - Accept 申请头并不是为版本控制而设计的。
  • 缓存 - 如果你应用基于头的版本控制，咱们不能仅仅基于URL缓存，你须要思考特定的申请头。
  • 是否能在浏览器间接执行 ? - 如果您有非技术消费者，那么基于URL的版本将更容易应用，因为它们能够间接在浏览器上执行。
  • API文档 - 如何让文档生成了解两个不同的url是同一服务的版本？
事实上，并没有完满的版本控制解决方案，你须要依据我的项目理论状况进行抉择。

上面列表展现了次要API提供商应用的不同版本控制办法：

  • 媒体类型的版本控制

    • Github

  • 自定义Header

    • Microsoft

  • URI门路

    • Twitter，百度，知乎

  • 申请参数管制

    • Amazon