API版本平滑降级的核心是新老版本逻辑共存并依请求头（如Accept-Version或X-API-Version）动态路由到对应实现，通过自定义@ApiVersion注解、拦截器提取版本、反射匹配候选方法及VersionDispatchHandler执行调用，配合fallback策略与日志监控实现无感降级。
API版本平滑降级的核心，是让新老版本逻辑共存，并根据请求头（如
或
）动态路由到对应实现，而无需改接口签名或重复写 Controller。自定义注解 + 反射 + Spring 的 HandlerMethodArgumentResolver / HandlerInterceptor / @ControllerAdvice 组合，能干净地实现这一目标。
定义版本选择注解 @ApiVersion
声明一个运行时保留、可用于方法上的注解，标注该方法支持的版本范围：
例如：
提取请求头中的版本标识
在拦截器或参数解析器中统一读取版本字段，推荐使用标准头
或兼容性更强的
：
优先从
解析（符合 REST 语义）
若不存在，回退到
若仍为空，使用全局默认版本（如 v1），或抛出
注意：版本值需标准化（小写、去空格、校验格式），避免
和
匹配失败。
反射匹配候选方法并择优调用
Spring 默认不允许多个同路径方法共存，所以需绕过标准映射，转为「运行时方法分发」。关键步骤如下：
启动时扫描所有
标记的方法，缓存为
，key 是请求路径（如
）
收到请求后，根据路径查出所有候选方法，再按注解中
数组过滤出匹配版本的方法
若多个方法匹配（如都支持 v2），按「精确匹配 > 范围匹配」或「注解 value 值优先级」排序，取第一个
通过
手动执行（需传入已解析的参数，建议结合
复用 Spring 参数绑定逻辑）
不建议硬编码反射调用，而是封装为
，与 Spring MVC 生命周期对齐（如注册为
的替代实现）。
降级策略与兜底保障
平滑降级不是“有版本就调”，而是要有明确 fallback 规则：
当请求 v3，但只有 v1/v2 实现 → 检查是否配置了
（可在注解或配置中心扩展）
无任何匹配方法时，返回
或自动降级到最高可用旧版（需显式开启开关）
记录版本未命中日志，含请求路径、期望版本、可用版本列表，便于监控和下线旧版
真正平滑的关键，在于服务端不报错、客户端无感——v3 请求拿到 v2 结果，只要契约兼容，就是成功降级。
Accept-Version: v1X-API-Version: v2@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-VersionX-API-VersionAccept-VersionX-API-Version400 Bad Requestv1V1@ApiVersionMap> /usersupportedHandlerMethod.invoke()WebDataBinderVersionDispatchHandlerHandlerMappingfallbackTo="v2"406 Not Acceptable