4 种 API 版本控制方案

目录

1、通过 URI 进行版本控制

2、通过请求参数进行版本控制

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

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

---

1、通过 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日知录"}}

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日知录"}}

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

@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日知录"));
    }
}

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

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

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

@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日知录"));
    }
}

在请求中使用Accept Header，请求示例如下：

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

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

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

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

影响版本选择的因素

• URI 污染 - URL版本和请求参数版本控制会污染URI空间。

• 滥用请求头 - Accept 请求头并不是为版本控制而设计的。

• 缓存 - 如果你使用基于头的版本控制，我们不能仅仅基于URL缓存，你需要考虑特定的请求头。

• 是否能在浏览器直接执行 ? - 如果您有非技术消费者，那么基于URL的版本将更容易使用，因为它们可以直接在浏览器上执行。

• API文档 - 如何让文档生成理解两个不同的url是同一服务的版本？

主要API提供商使用的不同版本控制方法

• 媒体类型的版本控制

  • Github

• 自定义Header

  • Microsoft

• URI路径

  • Twitter，百度，知乎

• 请求参数控制

  • Amazon