API版本平滑降级的核心是新老版本逻辑共存并依请求头（如Accept-Version或X-API-Version）动态路由到对应实现，通过自定义@ApiVersion注解、拦截器提取版本、反射匹配候选方法及VersionDispatchHandler执行调用，配合fallback策略与日志监控实现无感降级。
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<HandlerMethod>>，key 是请求路径（如/user） - 收到请求后，根据路径查出所有候选方法，再按注解中
supported数组过滤出匹配版本的方法 - 若多个方法匹配（如都支持 v2），按「精确匹配 > 范围匹配」或「注解 value 值优先级」排序，取第一个
- 通过
HandlerMethod.invoke()手动执行（需传入已解析的参数，建议结合WebDataBinder复用 Spring 参数绑定逻辑）
不建议硬编码反射调用，而是封装为 VersionDispatchHandler，与 Spring MVC 生命周期对齐（如注册为 HandlerMapping 的替代实现）。
降级策略与兜底保障
平滑降级不是“有版本就调”，而是要有明确 fallback 规则：
- 当请求 v3，但只有 v1/v2 实现 → 检查是否配置了
fallbackTo="v2"（可在注解或配置中心扩展） - 无任何匹配方法时，返回
406 Not Acceptable或自动降级到最高可用旧版（需显式开启开关） - 记录版本未命中日志，含请求路径、期望版本、可用版本列表，便于监控和下线旧版
真正平滑的关键，在于服务端不报错、客户端无感——v3 请求拿到 v2 结果，只要契约兼容，就是成功降级。
