spring boot: 设计接口站api的版本号,支持次版本号(spring boot 2.3.2)
一，为什么接口站的api要使用版本号?
1，当服务端接口的功能发生改进后，
客户端如果不更新版本，
则服务端返回的功能可能不能使用，
所以在服务端功能升级后，
客户端也要相应的使用新版的服务端接口
2,注意点：不要频繁变更服务端接口站的版本
不管是新增/修改服务端功能，只要app旧版本可以兼容,
则服务端的版本号无需变动，因为这个版本和git的版本控制不一样，
它起的作用是比较客户端的哪些版本和服务端的哪些版本能兼容
只有客户端不能兼容时，才会新增版本号以便区分
3,版本号需要能向下兼容，
如果访问一个高的版本不存在时，应该能访问到比它小的离它最近的版本，
因为如果每个入口或每个功能在有新版本时都要重新写一遍，
则和把代码复制一份没有两样了，
这样才可以方便的管理
4，版本号可以放到请求头和url中，
我们采用比较直观的放到url中的形式演示,
形如: /v1.2/home/page?
5,说明：生产环境中没发现有必要在次版本号后面再加一级，
所以有次版本号后已经够用了，
大家如果认为有必要增加一级的话，可以修改代码中VERSION_PREFIX_PATTERN的正则:
说明：刘宏缔的架构森林是一个专注架构的博客，地址：https://www.cnblogs.com/architectforest
对应的源码可以访问这里获取： https://github.com/liuhongdi/
说明：作者:刘宏缔 邮箱: 371125307@qq.com
二，演示项目的相关信息
1，项目地址:
https://github.com/liuhongdi/apiversion
2,项目说明:
我们给接口站的接口增加api的版本号
支持整数方式(例：v1)和次版本号形式(例：v1.3)
3,项目结构：如图:
三，java代码说明
1,ApiVersion.java
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ApiVersion {
//版本号的值，从1开始
String value() default "1";
}
用来添加版本号的一个注解
2,ApiVersionCondition.java
//实现RequestCondition
public class ApiVersionCondition implements RequestCondition<ApiVersionCondition> {
//api版本号
private String apiVersion;
//版本号的格式，如: /v[1-n]/api/test or /v1.5/home/api
private final static Pattern VERSION_PREFIX_PATTERN = Pattern.compile("/v((\\d+\\.\\d+)|(\\d+))/");
public ApiVersionCondition(String apiVersion) {
this.apiVersion = apiVersion;
} //将不同的筛选条件进行合并
@Override
public ApiVersionCondition combine(ApiVersionCondition other) {
// 采用最后定义优先原则，则方法上的定义覆盖类上面的定义
return new ApiVersionCondition(other.getApiVersion());
} //版本比对，用于排序
@Override
public int compareTo(ApiVersionCondition other, HttpServletRequest request) {
//优先匹配最新版本号
return compareTo(other.getApiVersion(),this.apiVersion)?1:-1;
} //获得符合匹配条件的ApiVersionCondition
@Override
public ApiVersionCondition getMatchingCondition(HttpServletRequest request) {
Matcher m = VERSION_PREFIX_PATTERN.matcher(request.getRequestURI());
if (m.find()) {
String version = m.group(1);
if (compareTo(version,this.apiVersion)){
return this;
}
}
return null;
}
//compare version
private boolean compareTo(String version1,String version2){
if (!version1.contains(".")) {
version1 += ".0";
}
if (!version2.contains(".")) {
version2 += ".0";
}
String[] split1 = version1.split("\\.");
String[] split2 = version2.split("\\.");
for (int i = 0; i < split1.length; i++) {
if (Integer.parseInt(split1[i])<Integer.parseInt(split2[i])){
return false;
}
}
return true;
} public String getApiVersion() {
return apiVersion;
}
}
实现查找和比较版本号的功能
3,ApiVersionRequestMappingHandlerMapping.java
//扩展RequestMappingHandlerMapping
public class ApiVersionRequestMappingHandlerMapping extends RequestMappingHandlerMapping { //类上有 @ApiVersion注解时生效
@Override
protected RequestCondition<?> getCustomTypeCondition(Class<?> handlerType) {
ApiVersion apiVersion = AnnotationUtils.findAnnotation(handlerType, ApiVersion.class);
return createRequestCondition(apiVersion);
} //方法上有 @ApiVersion注解时生效
@Override
protected RequestCondition<?> getCustomMethodCondition(Method method) {
ApiVersion apiVersion = AnnotationUtils.findAnnotation(method, ApiVersion.class);
return createRequestCondition(apiVersion);
} //返回ApiVersionCondition
private RequestCondition<ApiVersionCondition> createRequestCondition(ApiVersion apiVersion) {
return apiVersion == null ? null : new ApiVersionCondition(apiVersion.value());
}
}
继承RequestMappingHandlerMapping，在类上和方法上有注解时，
使用ApiVersionCondition进行处理
4,WebMvcConfig.java
@Configuration
public class WebMvcConfig extends WebMvcConfigurationSupport {
//在获取RequestMappingHandlerMapping时
//返回我们自定义的ApiVersionRequestMappingHandlerMapping
@Override
protected RequestMappingHandlerMapping createRequestMappingHandlerMapping() {
return new ApiVersionRequestMappingHandlerMapping();
}
}
把createRequestMappingHandlerMapping方法返回时使用我们自定义的ApiVersionRequestMappingHandlerMapping
5,HomeController.java
@RestController
@RequestMapping("/{version}/home")
public class HomeController { //匹配版本v1的访问
@ApiVersion("1")
@GetMapping
@RequestMapping("/home")
public String home01(@PathVariable String version) {
return "home v1 : version:" + version;
} //匹配版本v2的访问
@ApiVersion("2.0")
@GetMapping
@RequestMapping("/home")
public String home02(@PathVariable String version) {
return "home v2 version: " + version;
} //匹配版本v1.5-2.0的访问
@ApiVersion("1.5")
@GetMapping
@RequestMapping("/home")
public String home15(@PathVariable String version) {
return "home v1.5 version: " + version;
}
}
6,GoodsV1Controller和GoodsV2Controller
把版本号加到controller上，
和加在方法上的使用一样，
为节省篇幅，不再贴代码，大家可以自己去github上访问
四，测试效果
1,访问
http://127.0.0.1:8080/v1.0/home/home
返回:
home v1 : version:v1.0
访问
http://127.0.0.1:8080/v2/home/home
返回:
home v2 version: v2
可见版本号带不带点，不妨碍它访问到对应的版本
2,访问:
http://127.0.0.1:8080/v3.0/home/home
返回：
home v2 version: v3.0
访问:
http://127.0.0.1:8080/v1.14/home/home
返回：
home v1.5 version: v1.14
可见版本号可以自动访问到距它最近的版本的功能
五, 查看spring boot的版本
. ____ _ __ _ _
/\\ / ___'_ __ _ _(_)_ __ __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
\\/ ___)| |_)| | | | | || (_| | ) ) ) )
' |____| .__|_| |_|_| |_\__, | / / / /
=========|_|==============|___/=/_/_/_/
:: Spring Boot :: (v2.3.2.RELEASE)