Spring Boot入门系列（二十一）如何优雅的设计Rest API版本号，实现API版本控制-技术圈

前面介绍了Spring Boot 如何快速实现Restful api 接口，并以人员信息为例，设计了一套操作人员信息的接口。有些人可能会问我，为什么我看到很多公司的api接口文档里面，都有/api/v1/ 这样的地址呢？其实，/api 就是为了和一般的业务地址区分，标明这个地址是api 的接口。v1 则代表版本号。

可能很多人又会问了，为什么要版本号呢？那么，接下来就聊一聊Restful 接口为什么要加版本号？如何优雅的设计 Restful API 接口版本号？

一、为什么加版本号

一般来说，api 接口是提供给其他系统或是其他公司使用，不能随意频繁的变更。然而，需求和业务不断变化，接口和参数也会发生相应的变化。如果直接对原来的接口进行修改，势必会影响其他系统的正常运行。这就必须对api 接口进行有效的版本控制。

例如，添加用户的接口，由于业务需求变化，接口的字段属性也发生了变化而且可能和之前的功能不兼容。为了保证原有的接口调用方不受影响，只能重新定义一个新的接口。

http://localhost:8080/api/v1/user
http://localhost:8080/api/v2/user

Api 版本控制的方式：

　　1、域名区分管理，即不同的版本使用不同的域名，v1.api.test.com，v2.api.test.com

　　2、请求url 路径区分，在同一个域名下使用不同的url路径，test.com/api/v1/，test.com/api/v2

　　3、请求参数区分，在同一url路径下，增加version=v1或v2 等，然后根据不同的版本，选择执行不同的方法。

实际项目中，一般选择第二种：请求url路径区分。因为第二种既能保证水平扩展，又不影响以前的老版本。

二、Spring Boot如何实现

实现方案：

1、首先创建自定义的@APIVersion 注解和自定义URL匹配规则ApiVersionCondition。

2、然后创建自定义的 RequestMappingHandlerMapping 匹配对应的request，选择符合条件的method handler。

1、创建自定义注解

首先，在com.weiz.config 包下，创建一个自定义版本号标记注解 @ApiVersion

package com.weiz.config;
import java.lang.annotation.ElementType;import java.lang.annotation.Retention;import java.lang.annotation.RetentionPolicy;import java.lang.annotation.Target;
/** * API版本控制注解 */@Target({ElementType.TYPE})@Retention(RetentionPolicy.RUNTIME)public @interface ApiVersion {    /**     * @return 版本号     */    int value() default 1;}

说明：

ApiVersion 为自定义的注解，API版本控制，返回对应的版本号。

2、自定义url匹配逻辑

创建 ApiVersionCondition 类，并继承RequestCondition 接口，作用是：版本号筛选，将提取请求URL中版本号，与注解上定义的版本号进行比对，以此来判断某个请求应落在哪个controller上。

在com.weiz.config 包下创建ApiVersionCondition 类，重写 RequestCondition，创建自定义的url匹配逻辑。

package com.weiz.config;
import org.springframework.web.servlet.mvc.condition.RequestCondition;
import javax.servlet.http.HttpServletRequest;import java.util.regex.Matcher;import java.util.regex.Pattern;
public class ApiVersionCondition implements RequestCondition<ApiVersionCondition> {    private final static Pattern VERSION_PREFIX_PATTERN = Pattern.compile(".*v(\\d+).*");
    private int apiVersion;
    ApiVersionCondition(int apiVersion) {        this.apiVersion = apiVersion;    }
    private int getApiVersion() {        return apiVersion;    }

    @Override    public ApiVersionCondition combine(ApiVersionCondition apiVersionCondition) {        return new ApiVersionCondition(apiVersionCondition.getApiVersion());    }
    @Override    public ApiVersionCondition getMatchingCondition(HttpServletRequest httpServletRequest) {        Matcher m = VERSION_PREFIX_PATTERN.matcher(httpServletRequest.getRequestURI());        if (m.find()) {            Integer version = Integer.valueOf(m.group(1));            if (version >= this.apiVersion) {                return this;            }        }        return null;    }
    @Override    public int compareTo(ApiVersionCondition apiVersionCondition, HttpServletRequest httpServletRequest) {        return apiVersionCondition.getApiVersion() - this.apiVersion;    }}

当方法级别和类级别都有ApiVersion注解时，二者将进行合并（ApiVersionRequestCondition.combine）。最终将提取请求URL中版本号，与注解上定义的版本号进行比对，判断url是否符合版本要求。

3、自定义匹配的处理器

在com.weiz.config 包下创建 ApiRequestMappingHandlerMapping 类，重写部分 RequestMappingHandlerMapping 的方法。

package com.weiz.config;
import org.springframework.web.bind.annotation.RequestMapping;import org.springframework.web.servlet.mvc.condition.RequestCondition;import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
import java.lang.reflect.Method;
public class ApiRequestMappingHandlerMapping extends RequestMappingHandlerMapping {    private static final String VERSION_FLAG = "{version}";
    private static RequestCondition createCondition(Class clazz) {        RequestMapping classRequestMapping = clazz.getAnnotation(RequestMapping.class);        if (classRequestMapping == null) {            return null;        }        StringBuilder mappingUrlBuilder = new StringBuilder();        if (classRequestMapping.value().length > 0) {            mappingUrlBuilder.append(classRequestMapping.value()[0]);        }        String mappingUrl = mappingUrlBuilder.toString();        if (!mappingUrl.contains(VERSION_FLAG)) {            return null;        }        ApiVersion apiVersion = clazz.getAnnotation(ApiVersion.class);        return apiVersion == null ? new ApiVersionCondition(1) : new ApiVersionCondition(apiVersion.value());    }
    @Override    protected RequestCondition getCustomMethodCondition(Method method) {        return createCondition(method.getClass());    }
    @Override    protected RequestCondition getCustomTypeCondition(Class handlerType) {        return createCondition(handlerType);    }}

4、配置注册自定义的RequestMappingHandlerMapping

重写请求过处理的方法，将之前创建的 ApiRequestMappingHandlerMapping 注册到系统中。

package com.weiz.config;
import org.springframework.boot.autoconfigure.web.servlet.WebMvcRegistrations;import org.springframework.context.annotation.Configuration;import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
@Configurationpublic class WebMvcRegistrationsConfig implements WebMvcRegistrations {    @Override    public RequestMappingHandlerMapping getRequestMappingHandlerMapping() {        return new ApiRequestMappingHandlerMapping();    }}

上面四步，把api 版本控制配置完了。代码看着复杂，其实都是重写spring boot 内部的处理流程。

5、创建控制器Controller

配置完成之后，接下来编写测试的控制器进行测试。

在Controller/api 目录下，分别创建UserV1Controller 和 UserV2Controller

UserV1Controller

@RequestMapping("api/{version}/user")@RestControllerpublic class UserV1Controller {
    @GetMapping("/test")    public String test() {        return "version1";    }    @GetMapping("/extend")    public String extendTest() {        return "user v1 extend";    }}

UserV2Controller

@RequestMapping("api/{version}/user")@RestController@ApiVersion(2)public class UserV2Controller {    @GetMapping("/test")    public String test() {        return "user v2 test";    }}

我们在v1版本的接口中创建了2个方法：test() 和 extendtest()。在v2 版本的接口中只创建了一个test() 方法。但是就实现了v2 版本中更新覆盖test() 方法，同时继承并拥有extendtest() 方法。这样就实现了接口的版本控制。

三、测试

启动项目后，输入相关地址，查看版本控制是否生效

测试结果：

正确的接口地址

继承的接口地址

说明：

　　上图的前两个截图说明，请求正确的版本地址，会自动匹配版本的对应接口。当请求的版本大于当前版本时，默认匹配当前版本。

　　第三个截图说明，当请求对应的版本不存在接口时，会匹配之前版本的接口，即请求/v2/user/extend 接口时，由于v2 控制器未实现该接口，所以自动匹配v1 版本中的接口。这就是所谓的版本继承。

最后

以上，就把Spring Boot 如何优雅的设计 Restful API 接口版本号，实现 API 版本控制介绍完了。版本控制和权限验证是rest api 的基础，虽然看着比较复杂，但是理解了，要实现还是比较简单的。

这个系列课程的完整源码，也会提供给大家。回复：springboot源码。获取这个系列课程的完整源码。

Spring Boot入门系列（二十一）如何优雅的设计Rest API版本号，实现API版本控制

一、为什么加版本号

二、Spring Boot如何实现

三、测试

最后

Spring Boot入门系列（二十）快速实现Restful API 接口

Spring Boot入门系列（十九）集成mybatis，使用注解实现动态Sql、参数传递等常用操作！

Spring Boot入门系列（十八）mybatis 使用注解实现增删改查，无需xml文件

Spring Boot入门系列（十七）Mybatis创建自定义mapper 实现多表关联查询！

Spring Boot入门系列（十六）整合pagehelper，一秒实现分页功能！

Spring Boot入门系列（十五） SpringBoot开发环境热部署的配置

Spring Boot入门系列（十三）统一日志处理！

Spring Boot入门系列（十一）如何整合Mybatis，实现增删改查【XML 配置版】

Spring Boot入门系列（十）如何使用拦截器，一学就会！

SpringBoot入门系列（三）SpringBoot资源文件属性配置

SpringBoot入门系列（二）Controller介绍及如何返回json数据

SpringBoot入门系列（一）如何快速创建SpringBoot项

Spring Boot入门系列（二十一） 如何优雅的设计Rest API版本号，实现API版本控制

一、为什么加版本号

二、Spring Boot如何实现

三、测试

最后

Spring Boot入门系列（二十一）如何优雅的设计Rest API版本号，实现API版本控制