.NET 5 API迁移路由匹配先后抛AmbiguousMatchException、NotImplementedException求解

异常底层原因 #

1. AmbiguousMatchException歧义匹配的根因 #

.NET 5+ 端点路由的匹配逻辑是先匹配路由模板结构，再验证参数约束/默认值：

• 两个Action的路由模板都是单动态段结构，都可以匹配/api/questions/{任意单段值}的路径结构，模板层面首先全部命中
• 你的第二个路由[Route("{folderId=folderId:Guid}")]存在语法错误：路由参数的约束和默认值正确语法是{参数名:约束=默认值}，写反顺序导致Guid类型约束根本没有生效，路由系统不会校验该段是否符合Guid格式，因此路径值2可以同时命中两个路由的模板，触发歧义匹配。
• 就算你给第一个路由加了{processedId:int}约束，只要第二个路由的Guid约束没生效，依然会出现模板全命中的情况，所以会抛出匹配异常。

2. 注释单端点后出现NotImplementedException的根因 #

• 当你注释掉单条查询接口，仅剩列表查询接口时：路径/2命中路由模板后，尝试把2转换为Guid给folderId赋值，转换失败导致路由匹配失败，此时如果你的项目配置了全局fallback端点、全局异常处理规则返回未实现提示，或者有其他未实现的默认路由被命中，就会抛出该异常。
• 你通过/api/questions/?folderId=xxx能正常访问的原因是：你写的路由模板{folderId=folderId:Guid}里的=folderId表示该路由段是可选的，当请求没有路径段时，路由模板也能匹配，此时folderId参数会自动从查询字符串绑定，所以可以正常访问。

解决方法（不修改原有对外URL规则） #

方法1：修正路由约束，通过类型自动区分 #

把两个Action的路由约束写对，让路由系统可以通过参数类型自动匹配对应接口：

// 按processedId查询单条的接口，加int约束，只有路径段是整数时才命中
[HttpGet]
[Route("{processedId:int}")] 
public async Task<TypedActionResult<Question>> GetQuestionByProcessedId(int processedId)

// 列表接口：去掉错误的路由段定义，因为你实际是从查询字符串传folderId，不需要路由段
[HttpGet]
[Route("")]
public async Task<TypedActionResult<IEnumerable<Question>>> GetQuestionsForFolder(Guid folderId)

修改后效果：

• 访问https://localhost:12345/api/questions/2：只有带int约束的单条接口命中，正常返回
• 访问https://localhost:12345/api/questions/?folderId=xxx：命中列表接口，正常返回
• 如果你一定要保留列表接口的路由段传参方式，把Guid约束写对即可：[Route("{folderId:Guid}")]，路由系统会自动判断路径段是整数还是Guid，自动匹配对应接口，不会有歧义。

方法2：调整路由优先级 #

如果有特殊场景不能加约束，可以给两个路由加Order属性，数值越小优先级越高：

// 单条接口优先级更高
[HttpGet, Route("{processedId}", Order = 0)]
// 列表接口优先级更低
[HttpGet, Route("{folderId:Guid}", Order = 1)]

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