ASP.NET Core调用/Users?name=aaa报AmbiguousMatchException错误排查

问题背景 #

你定义的接口代码如下：

// 接口1
[HttpGet]
[Route("Users/{id}")]
public async Task<IActionResult> GetUser(int id)

// 接口2
[HttpGet]
[Route("Users")]
public async Task<IActionResult> GetUser(string name)

// 后续补充的接口3
[HttpGet] 
public async Task GetOffers()

请求/Users?name=aaa时抛出如下异常：

Microsoft.AspNetCore.Routing.Matching.AmbiguousMatchException: The request matched multiple endpoints. Matches:

报错原因 #

• 首先单独看前两个GetUser接口不存在路由冲突：接口1的路由规则要求路径必须携带id路由段，仅能匹配/Users/数值格式的请求；接口2仅匹配/Users路径，查询参数name属于绑定参数，不参与路由段的匹配判定，正常情况下请求/Users?name=aaa只会命中接口2。
• 真正引发冲突的是接口3GetOffers：ASP.NET Core中没有单独标注[Route]属性的接口，会继承Controller级别的路由规则，如果你的Controller没有配置路由前缀，或者配置的前缀恰好和/Users的匹配范围重叠，GetOffers的默认路由规则就会和GetUser(string name)的路由规则重合，导致同一份请求同时匹配到两个接口，抛出歧义匹配异常。
• 路由匹配的优先级逻辑是先校验请求方法和路由段，查询参数、参数类型约束属于后置校验规则，前置路由段匹配重合就会直接抛出冲突。

修复方案 #

• 给GetOffers添加专属路由规则，比如[Route("Offers")]，让它的路由段和Users系列接口完全区分开。
• 给Controller统一配置路由前缀，比如[Route("api/[controller]")]，同时给所有Action配置明确的Route属性，避免无路由规则的Action默认匹配宽范围路径。
• 针对同路由段的不同接口，可以添加路由约束明确匹配规则，比如给GetUser(string name)添加[Route("Users")]的同时补充查询参数必填约束，要求请求必须携带name查询参数才能命中该接口，避免和其他同路由段接口冲突。

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