ASP.NET Core Web API 路由参数id异常接收'search'值的排查

核心问题成因 #

你写的[HttpGet("{id}")]是无任何约束的占位路由，ASP.NET Core 匹配请求时，只要路径结构符合模板，且没有更高优先级的匹配项，就会把对应路径段的值直接绑定到id参数上。出现id拿到"search"的情况，本质是两个问题叠加：一是路由匹配错位，本该匹配固定/search路径的请求被占位路由截胡；二是没有给Guid类型的参数加路由约束，非Guid格式的请求没有被提前拦截。

分步排查操作 #

• 定位实际路由匹配来源
  在应用管道最前置位置添加临时诊断逻辑，输出每个请求实际匹配的路由信息，避免盲目排查：

// 放在Program.cs中app.UseRouting()之后即可
app.Use(async (context, next) =>
{
    Console.WriteLine($"请求路径：{context.Request.Path}");
    Console.WriteLine($"命中路由模板：{context.GetEndpoint()?.DisplayName}");
    Console.WriteLine($"路由参数集合：{string.Join(" | ", context.Request.RouteValues.Select(pair => $"{pair.Key}={pair.Value}"))}");
    await next();
});

发送触发异常的请求，查看输出的命中路由是否为当前Get方法，就能确认异常来源。

• 核对路由定义的优先级与顺序
  如果使用传统路由模式（通过MapControllerRoute定义全局模板），控制器内的Action扫描顺序为代码书写顺序：如果带{id}占位的Get方法，写在同控制器下定义的[HttpGet("search")]搜索接口之前，请求会优先匹配到占位路由，将路径段"search"作为id参数值传入，不会走到后续的固定search接口。如果使用属性路由模式，系统会自动计算路由优先级（字面量路径段优先级高于参数占位段），此时出现匹配错位的常见原因是search路由没有加全路径前缀，或者存在更低优先级的泛化路由把请求拦截。调整固定字面量路径的Action位置、补全路由模板的前缀即可解决。
• 补上预期的Guid类型路由约束
  原本设计中id应为Guid类型，当前无约束的模板会放行所有字符串值的请求。调整路由模板和参数类型，从路由层做拦截：

[HttpGet("{id:guid}")]
public async Task<IActionResult> Get([FromRoute] Guid id)

调整后，路由系统会自动校验路径段是否为合法Guid格式，非Guid值（比如"search"）会直接跳过当前接口，不会触发Action内的逻辑。

• 排查全局路由与中间件映射
  检查Program.cs中的全局路由模板、中间件映射配置，确认是否存在泛化路由（比如默认路由模板{controller=Home}/{action=Index}/{id?}）将本应归属其他控制器的/search请求，错误路由到当前计划查询接口上。

现有代码的额外隐患 #

• 方法内用new System.Diagnostics.StackTrace()打印栈信息的调试逻辑无效：该对象只能获取当前线程的代码调用栈，拿不到路由匹配的上下文来源，没法定位为什么参数会拿到"search"值。
• 将id定义为string类型，没有在路由层做格式校验，即便传入完全不符合业务预期的字符串值，也会继续执行后续业务逻辑，不会提前返回404拦截异常请求，这也是运行时错误未被前置拦截的重要原因。

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