Spring Boot API 的版本控制

教程

简介

本文将带你了解 Spring Boot 应用中对 API 进行版本控制的重要性，以及不同的实现方式。

通过 API 版本控制，你可以对API进行更改，而不会破坏与现有客户端的兼容性。本文将介绍四种常见的版本控制方式：URI 版本控制、请求参数版本控制、自定义 Header 版本控制和内容协商（Accept Header）版本控制。

URI 版本控制

URI 版本控制涉及将版本号添加到 API 的 URL 中。这是一种直接而易于理解的方法。然而，它可能不是最优雅的方法，因为它可能导致URL变得很长。

示例：

@RestController
@RequestMapping("/api/v1/users")
public class UserControllerV1 {

    @GetMapping
    public ResponseEntity<List<User>> getUsers() {
        // 实现代码
    }

    // 其他端点
}

请求参数版本控制

采用这种方法时，版本号会作为请求参数传递。这种方法比 URI 版本控制更省事，但对消费者来说可能不那么直观。

示例：

@RestController
public class UserController {

    @GetMapping(value = "/api/users", params = "version=1")
    public ResponseEntity<List<User>> getUsersV1() {
        // 实现代码
    }

    @GetMapping(value = "/api/users", params = "version=2")
    public ResponseEntity<List<User>> getUsersV2() {
        // 实现代码
    }
}

自定义 Header 版本控制

自定义 Header 版本控制涉及向 HTTP 请求添加一个自定义 Header，其中包含版本号。这种方法可以保持 URI 的清晰，但消费者必须记住要添加自定义 Header。

示例：

@RestController
public class UserController {

    @GetMapping(value = "/api/users", headers = "X-API-Version=1")
    public ResponseEntity<List<User>> getUsersV1() {
        // 实现代码
    }

    @GetMapping(value = "/api/users", headers = "X-API-Version=2")
    public ResponseEntity<List<User>> getUsersV2() {
        // 实现代码
    }
}

内容协商（Accept Header）版本控制

Accept Header 版本控制利用 HTTP Accept 头来指定所需的 API 版本。这种方法符合 HATEOAS 原则，因为版本是内容协商的一部分。

示例：

@RestController
public class UserController {

    @GetMapping(value = "/api/users", produces = "application/vnd.example.api.v1+json")
    public ResponseEntity<List<User>> getUsersV1() {
        // 实现代码
    }

    @GetMapping(value = "/api/users", produces = "application/vnd.example.api.v2+json")
    public ResponseEntity<List<User>> getUsersV2() {
        // 实现代码
    }
}

总结

这 4 种方式各有利弊，你需要根据你的应用场景来进行选择。

参考：https://medium.com/@AlexanderObregon/a-guide-to-versioning-apis-in-spring-boot-329aae1c495f