.NET 7下ASP.NET Core Web API控制器路由无法注册及请求失败问题

问题现象 #

开发基于.NET 7的前后端分离BFF后端时，API控制器路由始终无法注册生效，访问端点时路由未被识别为控制器路由，所有请求均被SPA逻辑拦截。

代码分析 #

Program.cs 关键问题点 #

app.Map("", client => {...})注册了匹配所有根路径请求的SPA端点，且该代码位于MapControllers()之前。由于ASP.NET Core端点匹配是按注册顺序执行的，所有请求（包括API请求）会先被SPA中间件拦截，无法到达控制器路由。

控制器代码说明 #

控制器的路由配置本身无语法错误，但[HttpGet(Name = "test")]中的Name是路由名称，并非路由模板，该接口的实际访问路径为/api/Auth。若需指定/api/Auth/test路径，需修改为[HttpGet("test")]。

解决方案 #

方案1：调整端点注册顺序 #

将控制器路由注册放在SPA端点之前，确保API请求优先被匹配：

修改后的Program.cs核心代码：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddDataProtection();
var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuth();

// 优先注册控制器路由，确保API请求被正确处理
app.MapControllers();

// 再注册SPA端点，处理非API请求
app.Map("", client =>
{
    var clientPath = Path.Combine(builder.Environment.ContentRootPath, "Client/dist");

    StaticFileOptions clientAppDist = new StaticFileOptions()
    {
        FileProvider = new PhysicalFileProvider(clientPath)
    };

    client.UseSpaStaticFiles(clientAppDist);

    client.UseSpa(spa =>
    {
        spa.Options.DefaultPageStaticFileOptions = clientAppDist;
    });
});

app.Run();

方案2：使用MapWhen区分API与SPA请求 #

通过MapWhen判断请求路径前缀，仅当请求不是/api开头时才走SPA逻辑，更精准地隔离API与SPA路由：

修改后的Program.cs核心代码：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddDataProtection();
var app = builder.Build();

app.UseHttpsRedirection();

app.UseAuth();

app.MapControllers();

// 仅拦截非/api开头的请求，交给SPA处理
app.MapWhen(context => !context.Request.Path.StartsWithSegments("/api"), client =>
{
    var clientPath = Path.Combine(builder.Environment.ContentRootPath, "Client/dist");

    StaticFileOptions clientAppDist = new StaticFileOptions()
    {
        FileProvider = new PhysicalFileProvider(clientPath)
    };

    client.UseSpaStaticFiles(clientAppDist);

    client.UseSpa(spa =>
    {
        spa.Options.DefaultPageStaticFileOptions = clientAppDist;
    });
});

app.Run();

验证 #

修改后启动项目，访问https://localhost:<端口>/api/Auth，应返回字符串test12345，说明控制器路由已生效。

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