快捷導(dǎo)航

SpringBoot的項目API版本控制方式

更新時間：2026年05月14日 16:24:27 作者：梁云亮

本文主要講述了如何通過自定義版本控制來實現(xiàn)接口版本的管理,主要包括自定義版本號標記注解,重寫RequestCondition和RequestMappingHandlerMapping以實現(xiàn)自定義的URL匹配邏輯,以及配置注冊自定義的WebMvcRegistrations,最后通過測試接口頁面驗證了效果

第一步：自定義版本號標記注解

@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ApiVersion {
    /**
     * 標識版本號，從1開始
     */
    int value() default 1;
}

第二步：重寫RequestCondition，自定義url匹配邏輯

@Data
@Slf4j
public class ApiVersionCondition implements RequestCondition<ApiVersionCondition> {
    /**
     * 接口路徑中的版本號前綴，如: api/v[1-n]/fun
     */
    private final static Pattern VERSION_PREFIX = Pattern.compile("/v(\\d+)/");
    private int apiVersion;

    ApiVersionCondition(int apiVersion) {
        this.apiVersion = apiVersion;
    }
    /**
     * 最近優(yōu)先原則，方法定義的 @ApiVersion > 類定義的 @ApiVersion
     */
    @Override
    public ApiVersionCondition combine(ApiVersionCondition other) {
        return new ApiVersionCondition(other.getApiVersion());
    }
    /**
     * 獲得符合匹配條件的ApiVersionCondition
     */
    @Override
    public ApiVersionCondition getMatchingCondition(HttpServletRequest request) {
        Matcher m = VERSION_PREFIX.matcher(request.getRequestURI());
        if (m.find()) {
            int version = Integer.valueOf(m.group(1));
            if (version >= getApiVersion()) {
                return this;
            }
        }
        return null;
    }
    /**
     * 當出現(xiàn)多個符合匹配條件的ApiVersionCondition，優(yōu)先匹配版本號較大的
     */
    @Override
    public int compareTo(ApiVersionCondition other, HttpServletRequest request) {
        return other.getApiVersion() - getApiVersion();
    }
}

說明：

getMatchingCondition方法中，控制了只有版本小于等于請求參數(shù)中的版本的 ApiCondition 才滿足規(guī)則
compareTo 指定了當有多個ApiCoondition滿足這個請求時，選擇最大的版本

第三步：重寫RequestMappingHandlerMapping，自定義匹配的處理器

public class ApiRequestMappingHandlerMapping extends RequestMappingHandlerMapping {
    @Override
    protected RequestCondition<?> getCustomTypeCondition(Class<?> handlerType) {
        // 掃描類上的 @ApiVersion
        ApiVersion apiVersion = AnnotationUtils.findAnnotation(handlerType, ApiVersion.class);
        return createRequestCondition(apiVersion);
    }
    @Override
    protected RequestCondition<?> getCustomMethodCondition(Method method) {
        // 掃描方法上的 @ApiVersion
        ApiVersion apiVersion = AnnotationUtils.findAnnotation(method, ApiVersion.class);
        return createRequestCondition(apiVersion);
    }
    private RequestCondition<ApiVersionCondition> createRequestCondition(ApiVersion apiVersion) {
        if (Objects.isNull(apiVersion)) {
            return null;
        }
        int value = apiVersion.value();
        Assert.isTrue(value >= 1, "Api Version Must be greater than or equal to 1");
        return new ApiVersionCondition(value);
    }
}

第四步：配置注冊自定義WebMvcRegistrations

@Configuration
public class WebMvcRegistrationsConfig implements WebMvcRegistrations {
    @Override
    public RequestMappingHandlerMapping getRequestMappingHandlerMapping() {
        return new ApiRequestMappingHandlerMapping();
    }
}

第五步：編寫測試接口

@RestController
@RequestMapping("/api/{version}")
public class ApiControler {
    @GetMapping("/fun")
    public String fun1() {
        return "fun 1";
    }
    @ApiVersion(5)
    @GetMapping("/fun")
    public String fun2() {
        return "fun 2";
    }
    @ApiVersion(9)
    @GetMapping("/fun")
    public String fun3() {
        return "fun 5";
    }
}

頁面測試效果：