ASP.NET API Versioning 中 CurrentImplementationApiVersionSelector 的行为变化分析

背景介绍

在 ASP.NET API 版本控制库的升级过程中，开发者发现 CurrentImplementationApiVersionSelector 的行为发生了变化，特别是在处理不同 API 版本中存在的操作时表现不同。这一变化主要影响了 API 的向后兼容性，特别是当某些操作在新版本中被移除时。

问题现象

在升级到 5.1.0 版本后，CurrentImplementationApiVersionSelector 的行为发生了变化：只有当操作在当前最新 API 版本中仍然存在时，请求才会被正确处理。同时，ReportApiVersions 的行为也发生了变化，现在会报告所有支持的 API 版本，即使某些操作在最新版本中已被移除。

技术分析

路由解析机制的变化

在 6.0+ 版本中，路由解析机制发生了重要变化：

1. 端点现在会在路由树构建阶段就锚定其版本
2. 候选路由会在更早的阶段被评估和过滤
3. 版本中立的 API 现在具有更符合预期的运行时行为

这些变化带来了以下影响：

• 更快的路由评估速度
• 更准确的 405、406/415 状态码返回
• 不再可能匹配到不存在的 API 版本

设计理念

API 版本控制的核心设计理念是：

• 版本是针对整个逻辑 API 的，而不是针对单个端点或操作
• 当前版本应该是整个 API 的当前版本，而不是特定端点的版本
• 在路由系统引导阶段，可用的信息非常有限

解决方案

方案一：内部处理

1. 让新版本调用或执行旧版本的代码
2. 使用 URL 重写来转移请求
3. 使用 301 或 308 重定向客户端

方案二：自定义版本选择器

实现自定义的 IApiVersionSelector，根据请求 URL 和当前 API 版本来匹配端点。例如，当请求 pets/42/vaccinations 时，明确映射回 1.0 版本，因为该端点不存在于 2.0 版本中。

方案三：使用反向代理分割 API

使用反向代理（如 YARP）将不同版本的 API 部署到不同的主机：

• 旧版本（1-n）使用旧库和旧主机
• 新版本使用新库和新主机
• 使用 [AdvertiseApiVersions] 来报告所有存在的 API 版本

最佳实践建议

1. 版本规划：在设计 API 时，考虑长期版本演进策略，避免频繁移除端点
2. 变更管理：重大变更应通过版本号升级来明确标识
3. 客户端兼容性：考虑使用自定义版本选择器来保持向后兼容性
4. 文档说明：清晰地记录每个版本的端点变化情况

总结

ASP.NET API Versioning 库在 6.0+ 版本中对路由解析机制进行了优化，提高了性能和准确性，但也带来了一些行为变化。开发者需要理解这些变化背后的设计理念，并根据实际需求选择合适的解决方案来保持 API 的兼容性和稳定性。

对于需要严格保持旧版行为的场景，可以考虑使用反向代理分割 API 或实现自定义版本选择器。在大多数情况下，遵循 API 版本控制的最佳实践，合理规划版本演进策略，可以最大限度地减少升级带来的影响。