Blazor使用MapFallbackToFile()时如何返回正确的API错误响应

问题根因 #

当请求匹配到已存在的API路径但HTTP方法不被允许时，MapControllers 不会命中对应端点，请求会继续向后匹配到你自定义的api/{**slug}兜底路由，该路由直接返回404，覆盖了ASP.NET Core原生返回的405状态码。同时无限制的MapFallbackToFile会拦截所有未命中的请求，包括API的非GET请求，导致异常状态码被篡改。

解决方案 #

直接调整Blazor兜底路由的匹配规则，移除自定义的API兜底路由即可，无需手动处理API错误逻辑：

app.UseEndpoints(endpoints =>
{
    endpoints.MapRazorPages();
    endpoints.MapControllers();
    // 仅对非API路径的GET请求返回Blazor首页，优先级设为最低
    endpoints.MapFallbackToFile("index.html")
        // 限制仅处理GET请求
        .WithMetadata(new HttpMethodMetadata(new[] { HttpMethods.Get }))
        // 调整路由优先级为最低，确保不会覆盖其他接口路由
        .Add(builder => ((RouteEndpointBuilder)builder).Order = int.MaxValue);
});

该配置下：

• 所有/api/前缀的请求会优先走控制器路由，原生错误逻辑完全保留：路径不存在返回404，方法不匹配返回405，参数错误返回400等
• 仅非API路径的GET请求未命中其他路由时，才会返回Blazor的index.html，完全不影响API调用

如果确实需要保留API兜底路由做统一的错误信息格式化，可以修改HandleApiFallback方法复用原生状态码逻辑：

private Task HandleApiFallback(HttpContext context)
{
    // 获取原生路由匹配结果
    var routeValues = context.Request.RouteValues;
    
    // 存在控制器匹配但端点未命中，说明是HTTP方法不允许
    if (routeValues.ContainsKey("controller"))
    {
        context.Response.StatusCode = StatusCodes.Status405MethodNotAllowed;
    }
    // 无任何控制器匹配，返回404
    else
    {
        context.Response.StatusCode = StatusCodes.Status404NotFound;
    }
    
    // 此处可统一添加错误响应体格式逻辑
    return Task.CompletedTask;
}

修改后你的测试用例即可正常通过。

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