乐趣区

关于restful:RESTful-API如何进行版本控制

jiezi

本文将帮忙您了解为什么须要版本控制，以及如何对 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
@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/header

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

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

    • headers=[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/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]

实现形式如下：

@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/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

退出移动版