AspNetCore API 版本控制中的分组与版本描述问题解析

背景介绍

在AspNetCore项目中使用Asp.Versioning进行API版本控制时，开发者可能会遇到一个特殊场景：当同时使用[ApiExplorerSettings]进行API分组和[ApiVersion]进行版本控制时，IApiVersionDescriptionProvider会产生意外的版本描述数量。本文将深入分析这一问题的成因、影响及解决方案。

问题现象

当控制器同时标注了分组和版本属性时：

[ApiVersion(1)]
[ApiExplorerSettings(GroupName = "WeatherForecastGroupName")]

IApiVersionDescriptionProvider会产生两个版本描述：

1. 标准版本格式："1.0"
2. 组合格式："WeatherForecastGroupName_1.0"

这与开发者预期的仅产生组合格式版本描述不符。

技术原理分析

1. 端点(Endpoint)处理机制

AspNetCore中存在两种API定义方式：

• 传统的控制器方式
• 最小API方式

这两种方式在底层都会注册为Endpoint，但它们的元数据处理机制完全不同。控制器使用ApiExplorerSettingsAttribute，而最小API使用不同的元数据接口。

2. 版本描述生成流程

IApiVersionDescriptionProvider的工作流程包含两个阶段：

1. 初始阶段：在DI容器构建时处理控制器端点
2. 变更阶段：应用启动后处理所有端点（包括最小API）

当存在分组名称时，最小API处理逻辑无法正确识别控制器端点，导致同一端点被处理两次。

解决方案

临时解决方案

对于.NET 6项目，可以移除最小API的版本收集逻辑：

// 从服务集合中移除EndpointApiVersionMetadataCollationProvider
var services = builder.Services;
for (var i = 0; i < services.Count; i++)
{
    var service = services[i];
    if (service.ServiceType == typeof(IApiVersionMetadataCollationProvider)
        && service.ImplementationType == typeof(EndpointApiVersionMetadataCollationProvider))
    {
        services.RemoveAt(i);
        break;
    }
}

长期解决方案

对于需要同时支持分组和版本控制的场景，建议：

1. 升级到.NET 8，该问题已在最新版本中修复
2. 自定义IApiVersionDescriptionProvider实现，正确处理分组名称

// 自定义版本描述提供程序示例
public class CustomApiVersionDescriptionProvider : IApiVersionDescriptionProvider
{
    // 实现逻辑需确保正确处理分组名称
}

最佳实践建议

1. 版本升级：优先考虑升级到.NET 8，以获得官方修复
2. 一致性处理：确保所有API端点统一使用控制器或最小API方式
3. 分组策略：明确分组命名规范，避免混合使用分组和非分组端点
4. 测试验证：在Swagger UI中验证生成的文档是否符合预期

总结

Asp.Versioning库在复杂场景下的版本描述生成机制需要特别注意分组名称的处理。理解端点注册的生命周期和不同API定义方式的差异，有助于开发者更好地处理版本控制相关的问题。对于关键业务系统，建议采用统一的API定义方式，并在升级到最新框架版本后验证问题是否已解决。