分布式架构设计之Rest API版本管理

分布式架构设计之RestAPI版本管理

 

随着互联网发展脚步的加快,产品项目的迭代也随之加快,所以就需要我们对产品的稳定提供一定的保障。而直接与用户接触的前端应用一般都是通过接口API与后台交互,一旦相关的API需求改版后,原来的API就不能使用,需要重新发布更新,如果前端产品是移动APP应用,比如:android/ios,那么就必须重新提交应用审核,等待若干天的审核发布是很不好的,严重影响用户的使用,所以建立API版本,使新改版的接口API不影响老版本的API使用,就显得很有必要了,那么接下来就介绍下。

 

l   版本形式

l   版本实现

l   版本方案

 

 

一、版本形式

API版本形式主要指的是API版本接口地址的形式,目前比较常见的形式如下:

1、HTPP地址参数

地址形式:http://server:port/api/xxx?v=yyy

 

xxx代表具体的接口名字,?号后面跟着参数v,该参数为具体的API版本号,需要客户端传递过来,此中版本形式比较传统。

 

 

2、HTTP请求头部

地址形式:http://server:port/api/xxx

请求头部:

即在API请求头部添加Accept属性,用于指定响应接收的媒体类型(Media Type),常见Accept形式如下:

application/vnd.api-v1+json

 

 

3、HTTP Rest风格

地址形式:http://server:port/api/{v}/xxx

 

上面的{v}为动态替换的参数,其作为接口地址API的一部分,是REST风格的地址形式,所以在灵活度及前后端通信协议的耦合度上都有优势。而在下面的版本实现时,就是采用这种方式实现验证的。

 

 

二、版本实现

在这里,我会使用Java语言的SSM框架来演示API版本的实现。并且全文中仅罗列实现的核心部分,其它内容需要读者具备一定的基础。

 

1、ApiVer.java

/**

 * 自定义接口版本标注注解,该注解可标注在

 * 类及方法函数上,并且在运行时环境起作用,

 * 并且可以被潜入到javadoc中,同时指定该

 * 标签为web映射注解.

 */

@Target({ElementType.TYPE,ElementType.METHOD})

@Retention(RetentionPolicy.RUNTIME)

@Documented

@Mapping

public @interface ApiVer {

    intvalue(); 

}

 

2、ApiRequestMapping.java

/**

 * 首先,需要在Servlet配置中注册该类

 * 其次,动态编译时匹配ApiVersion标签,

 * 获取控制器中对应类或方法的版本值.

 */

public class ApiRequestMapping extends RequestMappingHandlerMapping {

 

    // 映射匹配自定义注解(ApiVer标注在类级别)

    protected RequestCondition getCustomTypeCondition(ClasshandlerType) {

       ApiVer apiVersion = AnnotationUtils.findAnnotation(handlerType, ApiVer.class);

       returncreateCondition(apiVersion);

    }

 

    // 映射匹配自定义注解(ApiVer标注在方法级别)

    protected RequestCondition  getCustomMethodCondition(Method method){

       ApiVer apiVersion = AnnotationUtils.findAnnotation(method, ApiVer.class);

       return createCondition(apiVersion);

    }

 

    // 获取当前控制器标注的版本,初始化Api版本条件

    // 参考 @ApiVerCondition注释说明.

    private RequestCondition  createCondition(ApiVer apiVersion) {

       return apiVersion ==null ?null :newApiVerCondition(apiVersion.value());

    }

}

 

3、ApiVerCondition.java

/**

* 首先,匹配过滤出当前访问接口中是否存在v(1-9)

 * 如果存在,继续判断格式是否对,否则报错返回。

 * 其次,比较请求地址中版本与控制器中版本,如果

 * 请求的版本值大于控制器中版本值,则取控制器版本

 * 值继续接口后续访问操作。

 */

public class ApiVerCondition implements RequestCondition<ApiVerCondition>{ 

    private final static PatternVERSION_PREFIX_PATTERN =Pattern.compile("v(\\d+)/"); 

      

    private int apiVersion; 

      

    public ApiVerCondition(int apiVersion){ 

       this.apiVersion = apiVersion; 

   } 

      

    public ApiVerCondition combine(ApiVerConditionother) { 

       return new ApiVerCondition(other.getApiVersion()); 

   } 

  

    public ApiVerCondition getMatchingCondition(HttpServletRequest request) { 

       Matcher m = VERSION_PREFIX_PATTERN.matcher(request.getRequestURI()); 

       if(m.find()){ 

           Integer version = Integer.valueOf(m.group(1)); 

           if(version >=this.apiVersion)

                return this

       } 

       return null

   } 

  

    public int compareTo(ApiVerCondition other, HttpServletRequest request) { 

       return other.getApiVersion() -this.apiVersion; 

   } 

  

    public int getApiVersion() { 

       return apiVersion; 

   } 

}

 

这里值得说明下,当前端访问的接口地址版本值大于控制器中配置的接口值时,则就会自动访问当前接口版本最大的接口方法,只做了向上最大兼容。

 

4、ServletConfig.java

@Configuration

@EnableWebMvc

@ComponentScan("com.cwteam.demo.action")

public class ServletConfig extends WebMvcConfigurerAdapter {

    @Bean 

    public RequestMapping HandlerMapping requestMappingHandlerMapping() { 

       RequestMappingHandlerMapping handlerMapping =new ApiRequestMapping(); 

       return handlerMapping; 

    }

}

 

这里主要是在SpringMVC中注册请求映射拦截转发。

 

5、ApiVerAction.java

/**

 * API控制器入口:

 * 首先,根控制器为动态版本{v},供前端传递;

 * 其次,在接口方法上标注@ApiVer自定义注解;

 * 最后,访问同一个地址时,如:http://server:port/v1/hello

 * 结果返回hello world v1

 */

@RestController

@RequestMapping("/{v}")

public class ApiVerAction {

   

    @ApiVer(1)

    @RequestMapping(value="/hello",method=RequestMethod.GET)

    public String helloV1() throws Exception {

       return"hello world v1";

    }

   

    @ApiVer(2)

    @RequestMapping(value="/hello",method=RequestMethod.GET)

    public String helloV2() throws Exception {

       return"hello world v2";

    }

   

    @ApiVer(3)

    @RequestMapping(value="/hello",method=RequestMethod.GET)

    public String helloV3() throws Exception {

       return"hello world v3";

    }

   

}

 

 

测试结果:

 

访问地址:

http://localhost:8080/restapi-version/v1/hello

分布式架构设计之Rest API版本管理_第1张图片 

 

访问地址:

http://localhost:8080/restapi-version/v2/hello

分布式架构设计之Rest API版本管理_第2张图片 

 

访问地址:

http://localhost:8080/restapi-version/v3/hello

分布式架构设计之Rest API版本管理_第3张图片 

 

访问地址:

http://localhost:8080/restapi-version/v4/hello

分布式架构设计之Rest API版本管理_第4张图片 

 

 

 

三、版本方案

我们知道,实际项目中API会存在很多,如果为每个API添加3~5个版本控制,相对维护成本还好(但也很人肉),如果需要支撑所有或几十个API版本兼容昵?如果完全按照上面的实现方式,答案是维护成本非常之高。另外,如果老用户已经很多版本没更新,我们也应该支持其API正常使用,这就需要对老版本进行兼容支持,所以需要在下面讨论下API的实际需要。

 

1、支持向上兼容

分布式架构设计之Rest API版本管理_第5张图片

如上图,我们可以对老版本API兼容支持,也就是最新的API版本逻辑,能够同时满足新老用户需要,也就是我们常见到的单一API版本接口。此种版本方式优缺点都很明显,优势就是提供客户端统一一个接口,劣势就是随着版本功能的升级,该接口API内部功能会臃肿,不便于后续的维护开展。

 

 

2、不做向上兼容

分布式架构设计之Rest API版本管理_第6张图片

 

如上图,与上面的API方式对比,这里对每一次的API功能改版升级都提供一个版本,也就是功能API会存在很多子版本。它的好处就是每个API的功能内部简洁突出当前版本功能,不兼容老版本的功能,如果是老用户的API,就直接客户端传递版本号,访问对应的版本API即可。劣势就是,日后会有成千上万的版本接口,后续维护升级的成本相当高。

 

 

3、用户版本升级

就长远角度考虑,我建议上面第2种实现方式,但又不能让API的版本无限递增下去,所以我们需要结合实际情况,只保留一定数量的API支持,比如:仅支持10个版本,如果低于这个版本,则强制老用户升级API,保证正常使用。

 

实际上,软件做得再完美,如果偏离了实际,那么一文不值,所以这里的API需要判断处理:如果老用户版本低于当前最新版本10个版本时,我们提示其强制更新,否则不能正常使用。当然,总有那么一些需求人提出,要支持所有的老版本API,虽然不建议这样实现,但也是可以做到的,比如:将API的版本功能实现以字节码形式,存放在数据库或文件或中间组件中,以方便对所有API版本进行管理,在加载编译之前,将所有的API版本加载到接口API实现逻辑中,带用户提交对应版本号时,自动定位到指定API,这样做可以支持更多历史版本,实际上一些API平台就是采用这种方式(是支持了更多版本,但也是有数量限制的,如果是合理设计的化)。

 

 

 

 项目代码:

 http://download.csdn.net/download/why_2012_gogo/10122734


 

 

 

好了,由于作者水平有限,如有不正确或是误导的地方,请不吝指出讨论(技术交流群:497552060(新))

 

 

你可能感兴趣的:(软件架构设计)