微服务生产实战-Spring Cloud自定义API版本

很多大型的平台涉及到对外开放API接口或者内部终端Restful接口, 接口涉及到升级和更新后, 一般会考虑保留原有API接口, 将升级版本的API接口通过更高的版本号进行标记, 这样已有用户的客户端程序可以保持正常工作的同时, 选择某个时机升级到新版本接口.
一般接口的版本设计路径大致如下:
/v1/api/user/info
升级后的接口如下:
/v2/api/user/info 

如何在Spring Cloud体系中做到更加优雅的API版本管理是我们本文所要描述的重点, 一般情况我们希望通过配置或者注解的方式很简单的标记某个接口的版本, 这里我们通过注解实现API的版本标记, 使用方式如下: 

/**
 * 已有老的获取用户信息接口, 实际请求路径/v1/api/user/info
 */
@ApiVersion(1)
@GetMapping("/api/user/info")
User selectByUser(String userId);
    
/**
 * 新增获取用户信息接口, 并增加是否获取内部用户的标记
 * 实际请求路径/v2/api/user/info
 */
@ApiVersion(2)
@GetMapping("/api/user/info")
User selectByUser(String userId, boolean isInner);

为了更加扩展化, 我们将支持更多的自定义注解路径标记, 比如我们可以通过@Inner接口标记微服务之间的接口仅支持内部调用, 不能对外开放. 通过@Web标记此接口只能网页端掉用, 通过@App标记此接口仅能APP端访问, 这样我们就可以在统一权限拦截中心进行注解解析和统一安全拦截. 使用方式如下:

/**
 * APP获取用户信息接口
 * 实际请求路径/app/user/info
 */
@App
@GetMapping("/user/info")
User selectByUserForApp(String userId);
    
/**
 * web获取用户信息接口
 * 实际请求路径/web/user/info
 */
@Web
@GetMapping("/user/info")
User selectByUserForWeb(String userId);

要实现Spring Cloud自定义路径解析, 我们需要有如下三个步骤:
1、自定义路径注解.
2、Spring实现解析映射.
3、Feigh实现解析映射. 

自定义路径注解

为了实现更多路径注解, 我们统一定义父类注解实现所有的自定义路由:

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface CustomPathPrefix {
    
    @AliasFor("path")
    String value() default "";
    

    @AliasFor("value")
    String path() default "";
    
    int version() default -1;
}

为了语义性更好, 我们定义了path属性与value互为别名. 然后在自定义路径前缀上实现如下特殊注解, 这里仅举例:

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@CustomPathPrefix("/v")
public @interface ApiVersion {
    
    /**
     * 版本编号
     * @return
     */
    @AliasFor(annotation = CustomPathPrefix.class, attribute = "version")
    int value();
    
}

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@CustomPathPrefix("/web")
public @interface Web {
    
}

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@CustomPathPrefix("/app")
public @interface App {
    
}

Spring实现解析映射

要实现Spring的解析映射, 我们需要首先了解RequestMappingHandlerMapping的机制, RequestMappingHandlerMapping作为Spring MVC中的核心类, 用于解析类和方法上的映射关系, RequestMappingHandlerMapping实现了完整的映射解析, 我们只需要继承它并将自定义注解的解析逻辑增加上即可.

首先我们需要自定义一个CustomPathPrefix的RequestCondition信息:

pub