Restful 如何进行版本控制 ,这 4 种方法你要掌握

技术交流

 0  623

飘渺Jame 2023-09-19

积分：0

大家好，我是飘渺！

在实际项目开发中我们经常需要对接口进行版本管理。那今天我们就来聊聊为什么需要版本控制，以及如何对 REST API 进行版本控制。我们将讨论 4 种版本控制的方法，并比较不同的方法。

通过此文您将学到

为什么我们需要对 RESTful API 进行版本控制？
可用的版本控制有哪些？
如何实现基于 Restful 的版本控制？

为什么我们需要对 RESTful API 进行版本化

最好的版本控制方法是不进行版本控制。只要不需要版本控制，就不要版本控制。

“构建向后兼容的服务，以便尽可能避免版本控制！”

然而，在许多情况下我们都需要进行版本控制，然我们看看下面具体的例子：

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

{
  "name": "Bob Charlie"
}

后来，您希望将学生的名字拆分，因此创建了这个版本的服务。

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

您可以从同一个服务支持这两个请求，但是随着每个版本的需求多样化，它会变得越来越复杂。

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

接下来让我们创建一个简单的 SpringBoot 的 maven 项目，并理解对 RESTful 服务进行版本控制的 4 种不同方法。


 
  org.springframework.boot
  spring-boot-starter
 

 
  org.springframework.boot
  spring-boot-starter-web
 

 
  org.projectlombok
  lombok
 

 
  org.springframework.boot
  spring-boot-starter-test
  test

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

第一个版本的 Bean

@Data
@AllArgsConstructor
public class StudentV1 {
    private String name;
}

第二个版本的 Bean

@Data
public class StudentV2 {
    private Name name;
}

StudentV2 使用的 Name 实体

@Data
@AllArgsConstructor
public class Name {
    private String firstName;
    private String lastName;
}

Restful 版本控制的方法

我们希望创建两个版本的服务，一个返回 StudentV1，另一个返回 StudentV2。

让我们来看看创建相同服务版本的 4 种不同方法。

通过 URI 进行版本控制

@RestController
public 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

实现方式如下：

@RestController
public 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/headerheaders=[X-API-VERSION=1]
http://localhost:8080/student/headerheaders=[X-API-VERSION=2]

实现方式如下所示：

@RestController
public 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/headerheader：X-API-VERSION = 1

请求：http://localhost:8080/student/headerheader：X-API-VERSION = 2

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

最后一种版本控制方法是在请求中使用 Accept Header，请求示例如下：

http://localhost:8080/student/produceheaders=[Accept=application/api-v1+json]
http://localhost:8080/student/produceheaders=[Accept=application/api-v2+json]

实现方式如下：

@RestController
public 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/produceheader：Accept = application/api-v1+json