SpringBoot 如何实现多版本接口的方法步骤

更新时间：2026年04月14日 09:51:37 作者：(farerboy)

本文主要介绍了SpringBoot 如何实现多版本接口的方法步骤,包括几种接口多版本控制的方式,文中通过示例代码介绍的非常详细,对大家的学习或者工作具有一定的参考学习价值,需要的朋友们下面随着小编来一起学习学习吧

前言

为什么接口会出现多个版本？

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

接口多版本的方式

相同URL，用不同的版本参数区分

api.test.com/user?version=v1
api.test.com/user?version=v2

version=v1 表示 v1版本的接口, 保持原有接口不动
version=v2 表示 v2版本的接口，更新新的接口

区分不同的接口域名

不同的版本有不同的子域名, 路由到不同的实例:

v1.api.test.com/user
v2.api.test.com/user

v1版本的接口, 保持原有接口不动, 路由到instance1
v2版本的接口，更新新的接口, 路由到instance2

网关路由不同子目录到不同的实例

api.test.com/v1/user
api.test.com/v2/user

v1版本的接口, 保持原有接口不动, 路由到instance1
v2版本的接口，更新新的接口, 路由到instance2

同一实例，用注解隔离不同版本控制

api.test.com/v1/user
api.test.com/v2/user

v1版本的接口, 保持原有接口不动，匹配@ApiVersion(“1”)的handlerMapping
v2版本的接口，更新新的接口，匹配@ApiVersion(“2”)的handlerMapping

下面咱们主要展示第四种单一实例中如何优雅的控制接口的版本。

实现案例

这个例子基于 SpringBoot 封装了 @ApiVersion 注解方式控制接口版本。

自定义 @ApiVersion 注解

package com.test.springboot.api.version.config.version;
import org.springframework.web.bind.annotation.Mapping;
import java.lang.annotation.*;
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Mapping
public @interface ApiVersion {
    String value();
}

定义版本匹配 RequestCondition

版本匹配支持三层版本

v1.1.1 （大版本.小版本.补丁版本）
v1.1 (等同于v1.1.0)
v1 （等同于v1.0.0)

package com.test.springboot.api.version.config.version;
import lombok.Getter;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.servlet.mvc.condition.RequestCondition;
import javax.servlet.http.HttpServletRequest;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
@Slf4j
public class ApiVersionCondition implements RequestCondition<ApiVersionCondition> {
    /**
     * support v1.1.1, v1.1, v1; three levels .
     */
    private static final Pattern VERSION_PREFIX_PATTERN_1 = Pattern.compile("/v\\d\\.\\d\\.\\d/");
    private static final Pattern VERSION_PREFIX_PATTERN_2 = Pattern.compile("/v\\d\\.\\d/");
    private static final Pattern VERSION_PREFIX_PATTERN_3 = Pattern.compile("/v\\d/");
    private static final List<Pattern> VERSION_LIST = Collections.unmodifiableList(
            Arrays.asList(VERSION_PREFIX_PATTERN_1, VERSION_PREFIX_PATTERN_2, VERSION_PREFIX_PATTERN_3)
    );
    @Getter
    private final String apiVersion;
    public ApiVersionCondition(String apiVersion) {
        this.apiVersion = apiVersion;
    }
    /**
     * method priority is higher then class.
     *
     * @param other other
     * @return ApiVersionCondition
     */
    @Override
    public ApiVersionCondition combine(ApiVersionCondition other) {
        return new ApiVersionCondition(other.apiVersion);
    }
    @Override
    public ApiVersionCondition getMatchingCondition(HttpServletRequest request) {
        for (int vIndex = 0; vIndex < VERSION_LIST.size(); vIndex++) {
            Matcher m = VERSION_LIST.get(vIndex).matcher(request.getRequestURI());
            if (m.find()) {
                String version = m.group(0).replace("/v", "").replace("/", "");
                if (vIndex == 1) {
                    version = version + ".0";
                } else if (vIndex == 2) {
                    version = version + ".0.0";
                }
                if (compareVersion(version, this.apiVersion) >= 0) {
                    log.info("version={}, apiVersion={}", version, this.apiVersion);
                    return this;
                }
            }
        }
        return null;
    }
    @Override
    public int compareTo(ApiVersionCondition other, HttpServletRequest request) {
        return compareVersion(other.getApiVersion(), this.apiVersion);
    }
    private int compareVersion(String version1, String version2) {
        if (version1 == null || version2 == null) {
            throw new RuntimeException("compareVersion error:illegal params.");
        }
        String[] versionArray1 = version1.split("\\.");
        String[] versionArray2 = version2.split("\\.");
        int idx = 0;
        int minLength = Math.min(versionArray1.length, versionArray2.length);
        int diff = 0;
        while (idx < minLength
                && (diff = versionArray1[idx].length() - versionArray2[idx].length()) == 0
                && (diff = versionArray1[idx].compareTo(versionArray2[idx])) == 0) {
            ++idx;
        }
        diff = (diff != 0) ? diff : versionArray1.length - versionArray2.length;
        return diff;
    }
}

定义 HandlerMapping

package com.test.springboot.api.version.config.version;
import org.springframework.core.annotation.AnnotationUtils;
import org.springframework.lang.NonNull;
import org.springframework.web.servlet.mvc.condition.RequestCondition;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
import java.lang.reflect.Method;
public class ApiVersionRequestMappingHandlerMapping extends RequestMappingHandlerMapping {
    /**
     * add @ApiVersion to controller class.
     *
     * @param handlerType handlerType
     * @return RequestCondition
     */
    @Override
    protected RequestCondition<?> getCustomTypeCondition(@NonNull Class<?> handlerType) {
        ApiVersion apiVersion = AnnotationUtils.findAnnotation(handlerType, ApiVersion.class);
        return null == apiVersion ? super.getCustomTypeCondition(handlerType) : new ApiVersionCondition(apiVersion.value());
    }
    /**
     * add @ApiVersion to controller method.
     *
     * @param method method
     * @return RequestCondition
     */
    @Override
    protected RequestCondition<?> getCustomMethodCondition(@NonNull Method method) {
        ApiVersion apiVersion = AnnotationUtils.findAnnotation(method, ApiVersion.class);
        return null == apiVersion ? super.getCustomMethodCondition(method) : new ApiVersionCondition(apiVersion.value());
    }
}

配置注册HandlerMapping

package com.test.springboot.api.version.config.version;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;

@Configuration
public class CustomWebMvcConfiguration extends WebMvcConfigurationSupport {

    @Override
    public RequestMappingHandlerMapping createRequestMappingHandlerMapping() {
        return new ApiVersionRequestMappingHandlerMapping();
    }
}

或者实现 WebMvcRegistrations 接口

@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer, WebMvcRegistrations {
    //...

    @Override
    @NonNull
    public RequestMappingHandlerMapping getRequestMappingHandlerMapping() {
        return new ApiVersionRequestMappingHandlerMapping();
    }

}

测试运行

controller

package com.test.springboot.api.version.controller;

import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import tech.pdai.springboot.api.version.config.version.ApiVersion;
import tech.pdai.springboot.api.version.entity.User;

/**
 * @author farerboy
 */
@RestController
@RequestMapping("api/{v}/user")
public class UserController {

    @RequestMapping("get")
    public User getUser() {
        return User.builder().age(18).name("pdai, default").build();
    }

    @ApiVersion("1.0.0")
    @RequestMapping("get")
    public User getUserV1() {
        return User.builder().age(18).name("pdai, v1.0.0").build();
    }

    @ApiVersion("1.1.0")
    @RequestMapping("get")
    public User getUserV11() {
        return User.builder().age(19).name("pdai, v1.1.0").build();
    }

    @ApiVersion("1.1.2")
    @RequestMapping("get")
    public User getUserV112() {
        return User.builder().age(19).name("pdai2, v1.1.2").build();
    }
}

输出

http://localhost:8080/api/v1/user/get
// {"name":"farerboy, v1.0.0","age":18}

http://localhost:8080/api/v1.1/user/get
// {"name":"farerboy, v1.1.0","age":19}

http://localhost:8080/api/v1.1.1/user/get
// {"name":"farerboy, v1.1.0","age":19} 匹配比1.1.1小的中最大的一个版本号

http://localhost:8080/api/v1.1.2/user/get
// {"name":"farerboy, v1.1.2","age":19}

http://localhost:8080/api/v1.2/user/get
// {"name":"farerboy, v1.1.2","age":19} 匹配最大的版本号，v1.1.2

这样，如果我们向另外一个模块提供v1版本的接口，新的需求中只变动了一个接口方法，这时候我们只需要增加一个接口添加版本号v1.1即可用v1.1版本访问所有接口。

此外，这种方式可能会导致v3版本接口没有发布，但是是可以通过v3访问接口的；这种情况下可以添加一些限制版本的逻辑，比如最大版本，版本集合等。

到此这篇关于SpringBoot 如何实现多版本接口的方法步骤的文章就介绍到这了,更多相关SpringBoot 多版本接口内容请搜索脚本之家以前的文章或继续浏览下面的相关文章希望大家以后多多支持脚本之家！

您可能感兴趣的文章:

Java中重载与重写的对比与区别
这篇文章主要介绍了Java中重载与重写的对比与区别的相关资料,需要的朋友可以参考下
2017-03-03
Java静态代理和动态代理总结
这篇文章主要介绍了Java静态代理和动态代理总结,非常不错，具有参考借鉴价值，需要的朋友可以参考下
2017-02-02
java Swing布局管理之BoxLayout布局
这篇文章主要为大家详细介绍了java Swing布局管理之BoxLayout布局的相关资料，感兴趣的小伙伴们可以参考一下
2016-05-05
如何通过Java实现时间轴过程解析
这篇文章主要介绍了如何通过Java实现时间轴过程解析,文中通过示例代码介绍的非常详细，对大家的学习或者工作具有一定的参考学习价值,需要的朋友可以参考下
2020-02-02
java判断ftp目录是否存在的方法
这篇文章主要为大家详细介绍了java判断ftp目录是否存在的方法，具有一定的参考价值，感兴趣的小伙伴们可以参考一下
2017-04-04
JDK动态代理与CGLib动态代理的区别对比
今天小编就为大家分享一篇关于JDK动态代理与CGLib动态代理的区别对比，小编觉得内容挺不错的，现在分享给大家，具有很好的参考价值，需要的朋友一起跟随小编来看看吧
2019-02-02
SpringBoot 错误页面跳转方式
这篇文章主要介绍了SpringBoot 错误页面跳转方式，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2022-02-02
java语言注解基础概念详解
这篇文章主要介绍了java语言注解基础概念详解，具有一定借鉴价值，需要的朋友可以参考下。
2017-12-12
Springboot如何通过自定义工具类获取bean
这篇文章主要介绍了Springboot通过自定义工具类获取bean方式，具有很好的参考价值，希望对大家有所帮助。如有错误或未考虑完全的地方，望不吝赐教
2021-09-09
Java导出excel时合并同一列中相同内容的行思路详解
这篇文章主要介绍了Java导出excel时合并同一列中相同内容的行,需要的朋友可以参考下
2018-06-06