Pre

Spring Boot - 在Spring Boot中實(shí)現(xiàn)靈活的API版本控制（上）

---

設(shè)計(jì)思路

@ApiVersion 功能特性

1. 支持類(lèi)和方法上使用:

   • 優(yōu)先級(jí)：方法上的注解優(yōu)先于類(lèi)上的注解。
   • 如果類(lèi)和方法同時(shí)使用 @ApiVersion，則以方法上的版本為準(zhǔn)。

2. 支持多版本同時(shí)生效:

   • @ApiVersion 的參數(shù)是數(shù)組，可以配置多個(gè)版本。例如：@ApiVersion({1, 2})，此配置允許通過(guò) v1 或 v2 訪問(wèn)。

3. 可配置前綴和后綴:

   • 默認(rèn)前綴是 v，可以通過(guò)配置項(xiàng) api-version.prefix 修改。
   • 默認(rèn)沒(méi)有后綴，但可以通過(guò) api-version.suffix 配置。

4. 使用簡(jiǎn)單:

   • 僅需一個(gè)注解即可完成版本控制。

使用示例

假設(shè)你有一個(gè) UserController，需要支持 v1 和 v2 的版本訪問(wèn)：

@RestController
@RequestMapping("/users")
public class UserController {@GetMapping@ApiVersion({1, 2})public List<User> getUsers() {// 獲取用戶(hù)列表的實(shí)現(xiàn)}@GetMapping("/{id}")@ApiVersion(2)public User getUserV2(@PathVariable Long id) {// 獲取用戶(hù)詳細(xì)信息的實(shí)現(xiàn)，僅在 v2 版本中有效}
}

在這個(gè)示例中，getUsers 方法在 v1 和 v2 版本都可訪問(wèn)，而 getUserV2 方法僅在 v2 版本可訪問(wèn)。

配置示例

在 application.properties 中配置版本前綴和后綴：

api-version.prefix=v
api-version.suffix=-api

這樣，API 的 URL 可以是 /v1-api/users 或 /v2-api/users。

通過(guò)這種方式，@ApiVersion 注解簡(jiǎn)化了 API 版本控制的實(shí)現(xiàn)，提高了代碼的可維護(hù)性和靈活性。

---

Project

---

Starter Code

自定義注解 ApiVersion

package com.github.artisan.annotation;import org.springframework.web.bind.annotation.Mapping;import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 接口版本標(biāo)識(shí)注解* @author artisan*/
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Mapping
public @interface ApiVersion {/*** 指定API的版本號(hào)。* 此方法返回一個(gè)整型數(shù)組，數(shù)組中的每個(gè)元素代表一個(gè)API版本號(hào)。** @return 代表API版本號(hào)的整數(shù)數(shù)組。*/int[] value();
}

配置屬性類(lèi)用于管理API版本

package com.github.artisan;import org.springframework.boot.context.properties.ConfigurationProperties;/*** 配置屬性類(lèi)用于管理API版本。* 通過(guò)前綴 "api-version" 綁定配置屬性，以方便管理API版本。* @author Artisan*/@ConfigurationProperties(prefix = "api-version")
public class ApiVersionProperties {/*** API版本的前綴，用于定義版本的起始部分。*/private String prefix;/*** 獲取API版本的前綴。** @return 返回API版本的前綴。*/public String getPrefix() {return prefix;}/*** 設(shè)置API版本的前綴。** @param prefix 設(shè)置API版本的前綴。*/public void setPrefix(String prefix) {this.prefix = prefix;}/*** API版本的后綴，用于定義版本的結(jié)束部分。*/private String suffix;/*** 獲取API版本的后綴。** @return 返回API版本的后綴。*/public String getSuffix() {return suffix;}/*** 設(shè)置API版本的后綴。** @param suffix 設(shè)置API版本的后綴。*/public void setSuffix(String suffix) {this.suffix = suffix;}}

自動(dòng)配置基于Spring MVC的API版本控制

package com.github.artisan;import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;/*** ApiVersionAutoConfiguration類(lèi)用于自動(dòng)配置基于Spring MVC的API版本控制* 該類(lèi)通過(guò)@EnableConfigurationProperties注解激活A(yù)piVersionProperties配置類(lèi)* 并且通過(guò)@Bean注解的方法創(chuàng)建和管理ApiVersionWebMvcRegistrations的單例對(duì)象* @author Artisan*/
@ConditionalOnWebApplication
@Configuration
@EnableConfigurationProperties(ApiVersionProperties.class)
public class ApiVersionAutoConfiguration {/*** 通過(guò)@Bean注解聲明此方法將返回一個(gè)單例對(duì)象，由Spring容器管理* 該方法的目的是根據(jù)ApiVersionProperties配置生成ApiVersionWebMvcRegistrations實(shí)例* 這對(duì)于自動(dòng)配置基于Spring MVC的API版本控制至關(guān)重要** @param apiVersionProperties 一個(gè)包含API版本控制相關(guān)配置的實(shí)體類(lèi)*                             該參數(shù)用于初始化ApiVersionWebMvcRegistrations對(duì)象* @return 返回一個(gè)ApiVersionWebMvcRegistrations對(duì)象，用于注冊(cè)和管理API版本控制相關(guān)的設(shè)置*/@Beanpublic ApiVersionWebMvcRegistrations apiVersionWebMvcRegistrations(ApiVersionProperties apiVersionProperties) {return new ApiVersionWebMvcRegistrations(apiVersionProperties);}
}

實(shí)現(xiàn)WebMvcRegistrations接口，用于自定義WebMvc的注冊(cè)邏輯

package com.github.artisan;import org.springframework.boot.autoconfigure.web.servlet.WebMvcRegistrations;
import org.springframework.util.StringUtils;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;/*** 實(shí)現(xiàn)WebMvcRegistrations接口，用于自定義WebMvc的注冊(cè)邏輯* 主要用于API版本的請(qǐng)求映射配置**  @author Artisan*/
public class ApiVersionWebMvcRegistrations implements WebMvcRegistrations {/*** API版本配置屬性* 用于獲取API版本的前綴和后綴配置*/private ApiVersionProperties apiVersionProperties;/*** 構(gòu)造函數(shù)，初始化API版本配置屬性** @param apiVersionProperties API版本配置屬性對(duì)象*/public ApiVersionWebMvcRegistrations(ApiVersionProperties apiVersionProperties) {this.apiVersionProperties = apiVersionProperties;}/*** 獲取請(qǐng)求映射處理器映射對(duì)象* 此方法用于配置API版本的請(qǐng)求映射處理邏輯* 它根據(jù)配置決定映射路徑的前綴和后綴** @return 返回一個(gè)初始化好的RequestMappingHandlerMapping對(duì)象，用于處理API版本的請(qǐng)求映射*/@Overridepublic RequestMappingHandlerMapping getRequestMappingHandlerMapping() {// 根據(jù)API版本配置的前綴情況決定使用默認(rèn)前綴"v"還是用戶(hù)配置的前綴// 如果未配置前綴，則默認(rèn)使用"v"，否則使用配置的前綴// 后綴直接使用配置的值return new ApiVersionRequestMappingHandlerMapping(StringUtils.isEmpty(apiVersionProperties.getPrefix()) ?"v" : apiVersionProperties.getPrefix(), apiVersionProperties.getSuffix());}}

擴(kuò)展RequestMappingHandlerMapping的類(lèi)，支持API版本路由

package com.github.artisan;import com.github.artisan.annotation.ApiVersion;
import org.springframework.core.annotation.AnnotationUtils;
import org.springframework.util.StringUtils;
import org.springframework.web.servlet.mvc.condition.ConsumesRequestCondition;
import org.springframework.web.servlet.mvc.condition.HeadersRequestCondition;
import org.springframework.web.servlet.mvc.condition.ParamsRequestCondition;
import org.springframework.web.servlet.mvc.condition.PatternsRequestCondition;
import org.springframework.web.servlet.mvc.condition.ProducesRequestCondition;
import org.springframework.web.servlet.mvc.condition.RequestCondition;
import org.springframework.web.servlet.mvc.condition.RequestMethodsRequestCondition;
import org.springframework.web.servlet.mvc.method.RequestMappingInfo;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;import javax.validation.constraints.NotNull;
import java.lang.reflect.Method;/*** 一個(gè)擴(kuò)展了RequestMappingHandlerMapping的類(lèi)，支持API版本路由。* 它允許方法或類(lèi)通過(guò)ApiVersion注解來(lái)支持版本控制。* @author Artisan*/
public class ApiVersionRequestMappingHandlerMapping extends RequestMappingHandlerMapping {/*** API版本在URL中的前綴*/private final String prefix;/*** API版本在URL中的后綴，默認(rèn)為空字符串，如果未提供則為空字符串*/private final String suffix;/*** 構(gòu)造函數(shù)用于初始化API版本的前綴和后綴。** @param prefix API版本在URL中的前綴* @param suffix API版本在URL中的后綴，如果沒(méi)有提供則默認(rèn)為空字符串*/public ApiVersionRequestMappingHandlerMapping(String prefix, String suffix) {this.prefix = prefix;this.suffix = StringUtils.isEmpty(suffix) ? "" : suffix;}/*** 覆蓋此方法以獲取方法的路由信息，并支持基于ApiVersion注解的自定義條件。** @param method 需要獲取路由信息的方法* @param handlerType 處理器類(lèi)型* @return 方法的路由信息，包括基于API版本的自定義條件*/@Overrideprotected RequestMappingInfo getMappingForMethod(Method method, @NotNull Class<?> handlerType) {// 獲取基本的路由信息RequestMappingInfo info = super.getMappingForMethod(method, handlerType);if (info == null) {return null;}// 檢查方法是否使用了ApiVersion注解ApiVersion methodAnnotation = AnnotationUtils.findAnnotation(method, ApiVersion.class);if (methodAnnotation != null) {// 獲取自定義方法條件RequestCondition<?> methodCondition = getCustomMethodCondition(method);// 創(chuàng)建基于API版本的信息并合并到基本信息中info = createApiVersionInfo(methodAnnotation, methodCondition).combine(info);} else {// 如果方法沒(méi)有使用ApiVersion注解，則檢查類(lèi)是否使用了該注解ApiVersion typeAnnotation = AnnotationUtils.findAnnotation(handlerType, ApiVersion.class);if (typeAnnotation != null) {// 獲取自定義類(lèi)條件RequestCondition<?> typeCondition = getCustomTypeCondition(handlerType);// 創(chuàng)建基于API版本的信息并合并到基本信息中info = createApiVersionInfo(typeAnnotation, typeCondition).combine(info);}}return info;}/*** 根據(jù)ApiVersion注解創(chuàng)建路由信息。** 該方法解析ApiVersion注解的值，并根據(jù)這些值構(gòu)建URL模式，* 然后結(jié)合自定義條件創(chuàng)建RequestMappingInfo對(duì)象，用于支持版本控制。** @param annotation ApiVersion注解實(shí)例，包含API版本信息。* @param customCondition 自定義條件，用于進(jìn)一步細(xì)化請(qǐng)求映射。* @return 基于API版本的路由信息，用于將請(qǐng)求映射到特定版本的API處理方法上。*/private RequestMappingInfo createApiVersionInfo(ApiVersion annotation, RequestCondition<?> customCondition) {// 獲取注解中指定的API版本數(shù)組int[] values = annotation.value();// 為每個(gè)API版本創(chuàng)建對(duì)應(yīng)的URL模式String[] patterns = new String[values.length];for (int i = 0; i < values.length; i++) {// 構(gòu)建URL前綴patterns[i] = prefix + values[i] + suffix;}// 使用構(gòu)建的URL模式和其他請(qǐng)求條件創(chuàng)建并返回RequestMappingInfo對(duì)象return new RequestMappingInfo(new PatternsRequestCondition(patterns, getUrlPathHelper(), getPathMatcher(),useSuffixPatternMatch(), useTrailingSlashMatch(), getFileExtensions()),new RequestMethodsRequestCondition(),new ParamsRequestCondition(),new HeadersRequestCondition(),new ConsumesRequestCondition(),new ProducesRequestCondition(),customCondition);}}

spring.factories

org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.github.artisan.ApiVersionAutoConfiguration

---

Test Code

無(wú)版本控制

package com.github.artisan.web;import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;/*** @author Artisan*/
@RestController
public class NoVersionController {@GetMapping("foo")public String foo() {return "不使用版本注解";}
}

多版本控制

package com.github.artisan.web;import com.github.artisan.annotation.ApiVersion;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;/*** @author Artisan*/
@RestController
public class MultiVersionController {@GetMapping("foo3")@ApiVersion({1, 2})public String foo3() {return "注解支持多版本";}
}

v1

package com.github.artisan.web.v1;import com.github.artisan.annotation.ApiVersion;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;/*** @author Artisan*/
@ApiVersion(1)
@RestController
public class TestController {@GetMapping("foo1")public String foo1() {return "方法沒(méi)有注解, 使用類(lèi)注解";}@GetMapping("foo2")@ApiVersion(1)public String foo2() {return "方法有注解, 使用方法注解";}}

v2

package com.github.artisan.web.v2;import com.github.artisan.annotation.ApiVersion;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;/*** @author Artisan*/
@ApiVersion(2)
@RestController
public class TestController {@GetMapping("foo1")public String foo1() {return "方法沒(méi)有注解, 使用類(lèi)注解";}@GetMapping("foo2")@ApiVersion(2)public String foo2() {return "方法有注解, 使用方法注解";}@GetMapping("foo4")@ApiVersion(1)public String foo4() {return "xxxx 方法有注解使用方法注解";}}

---

Test

整個(gè)swagger吧

 package com.github.artisan.swagger;import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@EnableSwagger2
public class SwaggerConfig {@Beanpublic Docket swaggerAll() {Docket docket = new Docket(DocumentationType.SWAGGER_2);return docket.apiInfo(apiInfo("all")).groupName("all").select().apis(RequestHandlerSelectors.basePackage("com.github.artisan.web")).paths(PathSelectors.any()).build().enable(true);}private ApiInfo apiInfo(String version) {return new ApiInfoBuilder().title("api-version-test doc").description("api-version-test").termsOfServiceUrl("").version(version).build();}@Beanpublic Docket swaggerV1() {return new Docket(DocumentationType.SWAGGER_2).groupName("v1").select().apis(RequestHandlerSelectors.basePackage("com.github.artisan.web")).paths(PathSelectors.regex("/v1.*")).build().apiInfo(apiInfo("v1"));}@Beanpublic Docket swaggerV2() {return new Docket(DocumentationType.SWAGGER_2).groupName("v2").select().apis(RequestHandlerSelectors.basePackage("com.github.artisan.web")).paths(PathSelectors.regex("/v2.*")).build().apiInfo(apiInfo("v2"));}}

訪問(wèn)： http://localhost:9090/swagger-ui.html