ASP.NET Core API 版本控制常见问题解析：为何任意版本号都能访问接口

在ASP.NET Core项目中使用API版本控制功能时，开发者可能会遇到一个奇怪的现象：明明只配置了v1版本的API，但通过v2、v3等其他版本号也能正常访问接口数据。本文将深入分析这一问题的成因，并提供完整的解决方案。

问题现象

当开发者在.NET 8项目中配置API版本控制后，预期只有v1版本的API能够被访问，但实际上任何数字版本（如v2、v25等）都能成功调用接口并返回数据。这与API版本控制的预期行为不符，正确的表现应该是只有明确声明的版本才能被访问，其他版本应当返回404错误。

问题根源分析

经过深入排查，发现这个问题通常由以下几个原因导致：

1. MVC中间件配置不正确：在.NET 6及以上版本中，如果仅添加了API版本控制服务但没有正确配置MVC中间件，会导致版本控制功能无法正常工作。

2. 使用了过时的路由方式：项目中如果启用了传统的IRouter实现（通过EnableEndpointRouting=false），而不是现代端点路由（Endpoint Routing），会导致版本控制失效。

3. 控制器缺少必要特性：控制器类上缺少[ApiController]特性也会影响版本控制的行为。

完整解决方案

要彻底解决这个问题，需要按照以下步骤进行配置：

1. 正确配置服务

在Program.cs或Startup.cs中，确保按以下顺序添加服务：

builder.Services.AddControllers();
builder.Services.AddApiVersioning(options =>
{
    options.ReportApiVersions = true;
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
})
.AddMvc() // 关键点：必须添加MVC支持
.AddApiExplorer(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.GroupNameFormat = "'v'VVV";
    options.SubstituteApiVersionInUrl = true;
});

2. 正确配置中间件

确保中间件管道中使用了现代端点路由：

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers(); // 使用端点路由

3. 正确标注控制器

控制器类需要同时具备[ApiController]特性和版本控制相关特性：

[ApiVersion("1.0")]
[Route("v{api-version:apiVersion}/[controller]")]
[ApiController] // 必须添加此特性
public class WeatherForecastController : ControllerBase
{
    // 控制器代码
}

注意事项

1. 避免使用传统路由：不要设置options.EnableEndpointRouting = false，这会强制使用传统路由系统，可能导致版本控制失效。

2. 版本声明一致性：确保路由模板中的版本占位符{api-version:apiVersion}与[ApiVersion]特性中声明的版本格式一致。

3. 版本读取器配置：明确指定版本读取器为UrlSegmentApiVersionReader，确保从URL路径中读取版本号。

通过以上配置，API版本控制将按预期工作，只有明确声明的版本能够被访问，其他版本请求将返回404错误，从而实现了严格的API版本隔离。

总结

API版本控制是构建长期维护的Web API服务的重要功能。在ASP.NET Core中正确配置版本控制需要注意服务注册顺序、中间件选择和控制器标注三个关键方面。遵循本文提供的解决方案，开发者可以避免常见的版本控制失效问题，构建出更加健壮的API服务。