ASP.NET Core API 版本控制中的CurrentImplementationApiVersionSelector行为变化解析

背景介绍

在ASP.NET Core API版本控制库的5.1.0版本更新后，CurrentImplementationApiVersionSelector的行为发生了重要变化。这一变化影响了API版本选择机制，特别是在处理已弃用API版本中的特定端点时。

行为变化详解

在5.0.0及更早版本中，CurrentImplementationApiVersionSelector会为所有请求选择最新的API版本，无论该特定端点是否存在于最新版本中。而在5.1.0及更高版本中，选择器会检查请求的端点是否实际存在于最新API版本中。

举例说明：

• 假设有一个宠物API，v1.0版本包含/pets/{petId}和/pets/{petId}/vaccinations两个端点
• v2.0版本只保留了/pets/{petId}端点
• 在旧版本中，两个端点都会自动路由到v2.0版本
• 在新版本中，只有/pets/{petId}会路由到v2.0，而/pets/{petId}/vaccinations会返回400错误

技术实现原理

这一变化源于6.0+版本对路由解析机制的改进。在旧版本中，所有候选路由都会被考虑，最终通过API版本进行消歧。新版本中，端点会在路由树构建阶段就锚定其版本，导致某些场景会提前终止评估。

主要改进点包括：

1. 更早地评估和消除不匹配的路由
2. 修复了405、406/415状态码的处理问题
3. 版本中立API现在具有与OpenAPI一致的行为
4. 提高了路由评估效率
5. 防止匹配不存在的API版本

解决方案建议

对于需要保持旧行为的项目，可以考虑以下几种方案：

方案一：API版本回退

实现自定义的IApiVersionSelector，根据请求URL判断应该使用的API版本。例如，当请求/pets/42/vaccinations时，明确回退到v1.0版本。

方案二：API代理架构

使用反向代理中间件，将不同版本的API部署到不同的服务上：

• v1-v(n)使用旧版本库和主机
• 新版本使用新版本库和主机
• 通过AdvertiseApiVersions属性报告所有可用API版本

方案三：内部处理机制

在新版本API中处理旧版本特有的端点：

1. 直接调用旧版本逻辑
2. 使用URL重写转发请求
3. 返回301/308重定向响应

最佳实践建议

1. 在API设计阶段明确版本策略
2. 对于重大变更，考虑使用代理架构平滑过渡
3. 充分测试所有端点的版本兼容性
4. 在文档中明确说明版本变更和弃用计划
5. 考虑使用API网关管理版本路由

这一变化虽然可能导致升级时的兼容性问题，但从长远来看提高了API版本控制的准确性和性能，是值得采用的技术改进。