使用Asp.Versioning.Mvc实现ASP.NET Core MVC API URL版本控制遇歧义错误

问题根源 #

出现AmbiguousMatchException是因为API版本控制配置不完整，或者控制器的版本标记与路由规则未正确绑定，导致请求无法精准匹配到对应端点。

修复步骤 #

1. 完善Program.cs的服务配置 #

确保API版本控制服务配置正确，添加必要的版本解析、默认版本等规则：

var builder = WebApplication.CreateBuilder(args);

// 配置API版本控制核心服务
builder.Services.AddApiVersioning(options =>
{
    // 指定从URL段读取版本号（匹配你用的路由格式）
    options.ApiVersionReader = new UrlSegmentApiVersionReader();
    // 设置默认版本为1.0
    options.DefaultApiVersion = new ApiVersion(1, 0);
    // 允许客户端获取服务支持的版本信息
    options.ReportApiVersions = true;
    // 未指定版本时使用默认版本
    options.AssumeDefaultVersionWhenUnspecified = true;
}).AddMvc(); // 绑定MVC相关的版本控制支持

// 添加控制器服务
builder.Services.AddControllers();

var app = builder.Build();

app.UseHttpsRedirection();
app.UseAuthorization();
app.MapControllers();

app.Run();

2. 修正控制器的版本标记与路由 #

确保每个版本控制器都正确配置特性，避免路由冲突：

V1版本控制器

[ApiController]
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/helloworld")]
public class HelloWorldV1Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok("Hello from v1.0");
    }
}

V2版本控制器

[ApiController]
[ApiVersion("2.0")]
[Route("api/v{version:apiVersion}/helloworld")]
public class HelloWorldV2Controller : ControllerBase
{
    [HttpGet]
    public IActionResult Get()
    {
        return Ok("Hello from v2.0");
    }
}

3. 关键注意事项 #

• 所有API控制器必须添加[ApiController]特性，确保版本控制组件能正确识别并处理。
• 路由模板中的{version:apiVersion}约束是版本解析的关键，不能省略或写错。
• 若控制器支持多个版本，需额外添加[MapToApiVersion("x.x")]特性指定对应版本。

验证测试 #

启动项目后分别调用：

• http://localhost:5069/api/v1.0/helloworld 应返回v1版本响应
• http://localhost:5069/api/v2.0/helloworld 应返回v2版本响应

此时请求会精准匹配对应版本的端点，不再出现模糊匹配异常。

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