基于注解实现API版本平滑降级_自定义注解如何根据请求头反射匹配不同的逻辑流-java教程-PHP中文网

api版本平滑降级的核心是新老版本逻辑共存并依请求头（如accept-version或x-api-version）动态路由到对应实现，通过自定义@apiversion注解、拦截器提取版本、反射匹配候选方法及versiondispatchhandler执行调用，配合fallback策略与日志监控实现无感降级。

基于注解实现api版本平滑降级_自定义注解如何根据请求头反射匹配不同的逻辑流

API版本平滑降级的核心，是让新老版本逻辑共存，并根据请求头（如 Accept-Version: v1 或 X-API-Version: v2）动态路由到对应实现，而无需改接口签名或重复写 Controller。自定义注解 + 反射 + Spring 的 HandlerMethodArgumentResolver / HandlerInterceptor / @ControllerAdvice 组合，能干净地实现这一目标。

定义版本选择注解 @ApiVersion

声明一个运行时保留、可用于方法上的注解，标注该方法支持的版本范围：

@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiVersion {
    String value() default "v1"; // 默认版本
    String[] supported() default {"v1"}; // 支持的多个版本（可扩展）
}

例如：

@GetMapping("/user")
@ApiVersion(supported = {"v1", "v2"})
public UserDTO getUserV1orV2(@RequestParam Long id) { ... }

@GetMapping("/user")
@ApiVersion(value = "v3", supported = {"v3"})
public UserV3DTO getUserV3(@RequestParam Long id) { ... }

提取请求头中的版本标识

在拦截器或参数解析器中统一读取版本字段，推荐使用标准头 Accept-Version 或兼容性更强的 X-API-Version：

优先从 Accept-Version 解析（符合 REST 语义）
若不存在，回退到 X-API-Version
若仍为空，使用全局默认版本（如 v1），或抛出 400 Bad Request

注意：版本值需标准化（小写、去空格、校验格式），避免 v1 和 V1 匹配失败。

反射匹配候选方法并择优调用

Spring 默认不允许多个同路径方法共存，所以需绕过标准映射，转为「运行时方法分发」。关键步骤如下：

启动时扫描所有 @ApiVersion 标记的方法，缓存为 Map<string list>></string>，key 是请求路径（如 /user）
收到请求后，根据路径查出所有候选方法，再按注解中 supported 数组过滤出匹配版本的方法
若多个方法匹配（如都支持 v2），按「精确匹配 > 范围匹配」或「注解 value 值优先级」排序，取第一个
通过 HandlerMethod.invoke() 手动执行（需传入已解析的参数，建议结合 WebDataBinder 复用 Spring 参数绑定逻辑）

不建议硬编码反射调用，而是封装为 VersionDispatchHandler，与 Spring MVC 生命周期对齐（如注册为 HandlerMapping 的替代实现）。