SpringBoot 增加 API Version
基于restful风格上,增加version版本号
例如: get /api/v1/users/
一、增加ApiVersion自定义注解
作用于Controller上,指定API版本号
这里版本号使用了double ,考虑到小版本的情况,例如1.1
import java.lang.annotation.*;
/**
* API Version type
*/
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface ApiVersion {
/**
* api version begin 1
*/
double version() default 1;
}
二、新增RequestCondition自定义匹配条件
Spring提供RequestCondition接口,用于定义API匹配条件
这里通过自定义匹配条件,识别ApiVersion,进行版本匹配
getMatchingCondition 用于检查URL中,是否符合/v{版本号},用于过滤无版本号接口;
compareTo 用于决定多个相同API时,使用哪个接口进行处理;
import org.springframework.web.servlet.mvc.condition.RequestCondition;
import javax.servlet.http.HttpServletRequest;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
/**
* API version condition
* @author w
* @date 2020-11-16
*/
public class ApiVersionCondition implements RequestCondition<ApiVersionCondition> {
/**
* 接口路径中的版本号前缀,如: api/v[1-n]/test
*/
private final static Pattern VERSION_PREFIX_PATTERN = Pattern.compile("/v([0-9]+\\.{0,1}[0-9]{0,2})/");
/** API VERSION interface **/
private ApiVersion apiVersion;
ApiVersionCondition(ApiVersion apiVersion){
this.apiVersion = apiVersion;
}
/**
* [当class 和 method 请求url相同时,触发此方法用于合并url]
* 官方解释:
* - 某个接口有多个规则时,进行合并
* - 比如类上指定了@RequestMapping的 url 为 root
* - 而方法上指定的@RequestMapping的 url 为 method
* - 那么在获取这个接口的 url 匹配规则时,类上扫描一次,方法上扫描一次,这个时候就需要把这两个合并成一个,表示这个接口匹配root/method
* @param other 相同api version condition
* @return ApiVersionCondition
*/
@Override
public ApiVersionCondition combine(ApiVersionCondition other) {
// 此处按优先级,method大于class
return new ApiVersionCondition(other.getApiVersion());
}
/**
* 判断是否成功,失败返回 null;否则,则返回匹配成功的条件
* @param httpServletRequest http request
* @return 匹配成功条件
*/
@Override
public ApiVersionCondition getMatchingCondition(HttpServletRequest httpServletRequest) {
// 通过uri匹配版本号
System.out.println(httpServletRequest.getRequestURI());
Matcher m = VERSION_PREFIX_PATTERN.matcher(httpServletRequest.getRequestURI());
if (m.find()) {
// 获得符合匹配条件的ApiVersionCondition
System.out.println("groupCount:"+m.groupCount());
double version = Double.valueOf(m.group(1));
if (version >= getApiVersion().version()) {
return this;
}
}
return null;
}
/**
* 多个都满足条件时,用来指定具体选择哪一个
* @param other 多个时
* @param httpServletRequest http request
* @return 取版本号最大的
*/
@Override
public int compareTo(ApiVersionCondition other, HttpServletRequest httpServletRequest) {
// 当出现多个符合匹配条件的ApiVersionCondition,优先匹配版本号较大的
return other.getApiVersion().version() >= getApiVersion().version() ? 1 : -1;
}
public ApiVersion getApiVersion() {
return apiVersion;
}
}
三、重写RequestMappingHandlerMapping处理
通过重写 RequestMappingHandlerMapping 类,对RequestMappering进行识别@ApiVersion注解,针对性处理;
这里考虑到有些接口不存在版本号,则使用Spring原来的ApiVersionRequestMappingHandlerMapping继续处理;
import org.springframework.core.annotation.AnnotationUtils;
import org.springframework.web.servlet.mvc.condition.RequestCondition;
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
import java.lang.reflect.Method;
/**
* API version setting
* @author w
* @date 2020-11-15
*/
public class ApiVersionRequestMappingHandlerMapping extends RequestMappingHandlerMapping {
/**
* class condition
* - 在class上加@ApiVersion注解&url加{version}
* @param handlerType class type
* @return ApiVersionCondition
*/
@Override
protected RequestCondition<?> getCustomTypeCondition(Class<?> handlerType) {
ApiVersion apiVersion = AnnotationUtils.findAnnotation(handlerType,ApiVersion.class);
return null == apiVersion ? super.getCustomTypeCondition(handlerType) : new ApiVersionCondition(apiVersion);
}
/**
* method condition
* - 在方法上加@ApiVersion注解&url加{version}
* @param method method object
* @return ApiVersionCondition
*/
@Override
protected RequestCondition<?> getCustomMethodCondition(Method method) {
ApiVersion apiVersion = AnnotationUtils.findAnnotation(method,ApiVersion.class);
return null == apiVersion ? super.getCustomMethodCondition(method) : new ApiVersionCondition(apiVersion);
}
}
四、Controller接口增加@ApiVersion注解
通过@ApiVersion注解指定该接口版本号
import com.panda.common.web.controller.BasicController;
import com.panda.common.web.version.ApiVersion;
import com.panda.core.umc.service.UserInfoService;
import com.panda.core.umc.vo.QueryUsersConditionVo;
import com.panda.face.umc.dto.user.QueryUsersReq;
import org.springframework.beans.BeanUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;
/**
* 用户信息服务
* @author w
* @date 2020-11-06
*/
@RequestMapping("/api")
@RestController
public class UserInfoController extends BasicController{
@Autowired
private UserInfoService userInfoService;
/**
* 查询所有用户信息
* @param req 查询条件信息
*/
@ApiVersion
@RequestMapping(value = "{version}/users", method = RequestMethod.GET)
@ResponseBody
public ResponseEntity getUsers(@PathVariable("version") String version, QueryUsersReq req){
QueryUsersConditionVo condition = new QueryUsersConditionVo();
BeanUtils.copyProperties(req,condition);
condition.setOrderBy("CREATE_TIME");
condition.setSort("DESC");
return assemble("1111");
}
/**
* 查询所有用户信息
* @param req 查询条件信息
*/
@ApiVersion(version = 1.1)
@RequestMapping(value = "{version}/users", method = RequestMethod.GET)
@ResponseBody
public ResponseEntity getUsersV2(@PathVariable("version") String version, QueryUsersReq req){
QueryUsersConditionVo condition = new QueryUsersConditionVo();
BeanUtils.copyProperties(req,condition);
condition.setOrderBy("CREATE_TIME");
condition.setSort("DESC");
return assemble("222");
}
/**
* 根据用户ID获取用户信息
* @param userId 用户ID
*/
@RequestMapping(value = "/users/uid/{userId}", method = RequestMethod.GET)
@ResponseBody
public ResponseEntity getUserInfo(@PathVariable("userId") String userId){
return assemble(userInfoService.selectByUserId(userId));
}
}
五、测试调用
通过访问以下URL,测试返回结果
GET http://127.0.0.1/api/v1/users
GET http://127.0.0.1/api/v1.1/users
GET http://127.0.0.1/api/v1.2/users
GET http://127.0.0.1/api/users/uid/U0001
六、总结
1.通过@ApiVersion注解方式,可以灵活指定接口版本;
2.缺点很明显,需要在URL上加入{version},才能进行匹配成功,这种PathVariable识别过于模糊,后期排查问题增加困难;
3.建议通过包名增加v1/v2明显区分版本,且在controller的URL上直接写死v1版本号,这种更直观;