ASP.NET Core Web API版本控制：未声明版本被匹配问题求助

问题 #

在微服务中使用Asp.Versioning库对ASP.NET Core Web API控制器做版本控制，控制器代码如下：

using Asp.Versioning;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.AspNetCore.Mvc.ModelBinding;

[ApiController]
[ApiVersion("1")]
[ControllerName("example")]
[Route("v{version:apiVersion}/[controller]")]
public class ExampleController : ControllerBase
{
    [HttpGet("version")]
    [Produces("text/plain")]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public IActionResult GetVersion() => Ok("v1");
}

服务配置代码：

services.AddApiVersioning(opt =>
{
    opt.ApiVersionReader = new UrlSegmentApiVersionReader();
}).AddApiExplorer(opt =>
{
    opt.GroupNameFormat = "'v'V";
});

执行curl请求时，无论使用已声明的v1还是未声明的v1337，都能匹配路由并返回结果。但控制器仅声明了ApiVersion("1")，期望未声明的版本返回404，请问是否配置有误？能否拒绝未声明版本？

解决方案 #

问题出在Asp.Versioning的默认配置上：默认情况下AssumeDefaultVersionWhenUnspecified为true，且默认版本是1.0。当请求的版本未被任何控制器支持时，框架会自动回退到默认版本，而你的控制器声明的ApiVersion("1")与默认版本1.0等价，所以未声明的版本（如v1337）会被匹配到v1的控制器。

要实现拒绝未声明版本的需求，只需修改服务配置，关闭默认版本回退行为：

services.AddApiVersioning(opt =>
{
    opt.ApiVersionReader = new UrlSegmentApiVersionReader();
    // 关闭未指定版本时自动使用默认版本的逻辑
    opt.AssumeDefaultVersionWhenUnspecified = false;
    // 可选：开启响应头返回当前API支持的所有版本
    opt.ReportApiVersions = true;
}).AddApiExplorer(opt =>
{
    opt.GroupNameFormat = "'v'V";
    // 可选：确保API文档生成时替换URL中的版本占位符
    opt.SubstituteApiVersionInUrl = true;
});

修改后，当请求未被控制器声明的版本（如v1337）时，框架会找不到对应的匹配控制器，返回404状态码，符合预期。

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