Asp.Versioning.Http报AmbiguousMatchException：Header API版本控制端点冲突

问题原因 #

1. 两个版本的ThingsController使用完全相同的路由模板[Route("[controller]")]，路由系统无法直接区分端点
2. 配置中注释掉了HeaderApiVersionReader的启用代码，导致API版本控制组件无法通过请求头识别版本，无法筛选出正确的端点，最终触发路由匹配冲突

修复步骤 #

1. 启用Header版本读取器 #

在AddApiVersioning配置中取消注释版本读取器的设置，让组件能识别请求头中的版本参数：

builder.Services.AddApiVersioning(options => {
    options.ApiVersionReader = new HeaderApiVersionReader("api-version");
    options.DefaultApiVersion = new ApiVersion(1.0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
}).EnableApiVersionBinding();

2. （可选，推荐）给路由添加版本约束 #

虽然启用Header读取后已能解决冲突，但给路由添加版本约束可以让路由规则更清晰，同时兼容URL路径版本传递的场景：

• V1控制器修改路由：

namespace Things.Service.Controllers.V1
{
 [ApiController]
 [ApiConventionType(typeof(DefaultApiConventions))]
 [Route("v{version:apiVersion}/[controller]")]
 [Asp.Versioning.ApiVersion(1.0)]
 public class ThingsController : ControllerBase
 {
    // controller logic
 }
}

• V2控制器修改路由：

namespace Things.Service.Controllers.V2
{
 [ApiController]
 [ApiConventionType(typeof(DefaultApiConventions))]
 [Route("v{version:apiVersion}/[controller]")]
 [Asp.Versioning.ApiVersion(2.0)]
 public class ThingsController : ControllerBase
  {
    // controller logic
  }
}

验证说明 #

• 发送请求时添加请求头api-version: 1.0，请求会路由到V1版本控制器
• 添加请求头api-version: 2.0，请求会路由到V2版本控制器
• 未指定版本时，会默认使用V1.0版本（因配置了AssumeDefaultVersionWhenUnspecified=true）

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