为何给.NET6 WebApi项目添加版本控制会移除控制器路径中的数字？

问题根源 #

ApiVersioning库默认启用了控制器名称版本约定——它会自动识别控制器名称末尾的数字作为API版本号，并在生成路由时移除这部分数字。你的WeatherForecast2Controller被库解析为版本2的控制器，路由自动简化为WeatherForecast，这就是访问WeatherForecast2返回404、而WeatherForecast能正常响应的原因。

验证行为 #

给控制器添加[ApiVersion]特性就能确认这一点：

[ApiVersion("2.0")]
public class WeatherForecast2Controller : ControllerBase
{
    // 原有业务代码
}

此时访问https://localhost:x/WeatherForecast?version=2.0就能正常返回结果，说明库确实把控制器名称末尾的2识别成了版本号。

解决办法 #

如果不想让库自动解析控制器名称里的数字作为版本，有两种可行方案：

1. 禁用默认的控制器名称版本约定 #

在ApiVersioning配置中移除默认约定：

services.AddApiVersioning(config =>
{
    config.AssumeDefaultVersionWhenUnspecified = true;
    config.DefaultApiVersion = new ApiVersion(1, 0);
    config.ReportApiVersions = true;
    config.ApiVersionReader = ApiVersionReader.Combine(
        new QueryStringApiVersionReader("version"),
        new HeaderApiVersionReader("x-version"));
    config.UseApiBehavior = false;
    // 移除控制器名称版本解析约定
    config.Conventions.Remove(typeof(ControllerNameApiVersionConvention));
});

配置完成后，WeatherForecast2Controller的路由会保持为WeatherForecast2，原访问路径即可正常响应。

2. 给控制器显式指定路由 #

通过[Route]特性自定义路由路径，覆盖默认规则：

[Route("WeatherForecast2")]
[ApiVersion("1.0")]
public class WeatherForecast2Controller : ControllerBase
{
    // 原有业务代码
}

这种方式更灵活，适合需要自定义路由结构的场景。

内容的提问来源于stack exchange，提问作者Daniel Pace