Blazor客户端HttpClient请求接口返回fallback的index.html问题求助

根因说明 #

你遇到的API请求返回index.html的问题，核心来自两个常见的配置疏漏：

• 服务端中间件顺序错误：/userinfo自定义中间件的优先级低于Blazor回退路由配置，服务端未完全启动时，请求未匹配到/userinfo路由，直接触发回退规则返回index.html
• 若启用了Blazor PWA能力，默认Service Worker规则会将所有带text/html接受头的GET请求判定为页面导航请求，直接返回缓存的index.html，完全绕过网络请求

具体修复步骤 #

1. 调整服务端中间件优先级与响应配置 #

将/userinfo中间件移到所有Blazor静态文件、回退路由配置之前，同时明确指定JSON响应类型，避免被识别为HTML：

// 优先级最高：先处理业务API请求
app.Use(async (context, next) => {
    if (context.Request.Path.Value?.ToLowerInvariant() == "/userinfo")
    {
        // 明确指定响应类型为JSON
        context.Response.ContentType = "application/json; charset=utf-8";
        // 禁用所有缓存
        context.Response.Headers.Add("Cache-Control", "no-cache, no-store, must-revalidate");
        
        var user = context.User as ClaimsPrincipal;
        if (!(user?.Identity?.IsAuthenticated ?? false))
        {
            await context.Response.WriteAsync("null");
            return;
        }

        var ident = user.Identity as ClaimsIdentity;
        var userinfo = new
        {
            Claims = user.Claims.Select(c => new
            {
                c.Type,
                c.Value,
                c.Issuer,
                c.OriginalIssuer,
                c.Properties,
                c.ValueType
            }),
            Identity = new
            {
                ident.AuthenticationType,
                ident.IsAuthenticated,
                ident.Label,
                ident.Name,
                ident.NameClaimType,
                ident.RoleClaimType
            }
        };

        var jici = System.Text.Json.JsonSerializer.Serialize(userinfo);
        await context.Response.WriteAsync(jici);
        return;
    }
    await next.Invoke();
});

// 后续再放Blazor相关静态文件、路由、回退配置
app.UseBlazorFrameworkFiles();
app.UseStaticFiles();
app.UseRouting();
// 认证、授权中间件放在此处
app.UseAuthentication();
app.UseAuthorization();

app.UseEndpoints(endpoints =>
{
    endpoints.MapControllers();
    // 回退路由放在最后，仅处理未匹配到任何路由的页面导航请求
    endpoints.MapFallbackToFile("index.html");
});

2. （若使用PWA）调整Service Worker规则 #

修改service-worker.published.js的请求拦截逻辑，排除所有API路径，避免将API请求误判为页面导航：

self.addEventListener('fetch', event => {
    const request = event.request;
    const requestUrl = new URL(request.url);
    // 仅对非API路径的页面导航请求走index.html回退逻辑
    if (request.method === 'GET' 
        && !requestUrl.pathname.startsWith('/api/') 
        && requestUrl.pathname !== '/userinfo'
        && request.headers.get('accept')?.includes('text/html')) {
        event.respondWith(
            fetch(request)
                .catch(() => caches.match('index.html'))
        );
        return;
    }
    // API请求直接走网络，不做缓存回退
    if (requestUrl.pathname.startsWith('/api/') || requestUrl.pathname === '/userinfo') {
        event.respondWith(fetch(request));
        return;
    }
    // 其他静态资源走原有缓存逻辑
});

3. 客户端加响应校验兜底 #

给HttpClient加拦截器，即使出现极端情况返回HTML，也能主动抛出异常触发你的错误处理逻辑：
首先定义拦截器：

public class ApiResponseValidationHandler : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(HttpRequestMessage request, CancellationToken cancellationToken)
    {
        var response = await base.SendAsync(request, cancellationToken);
        var path = request.RequestUri?.AbsolutePath;
        // 校验API类请求的响应类型
        if ((path?.StartsWith("/api/") == true || path == "/userinfo") 
            && response.IsSuccessStatusCode)
        {
            var contentType = response.Content.Headers.ContentType?.MediaType;
            if (contentType is not "application/json")
            {
                // 标记为服务不可用，触发异常逻辑
                response.StatusCode = System.Net.HttpStatusCode.ServiceUnavailable;
            }
        }
        return response;
    }
}

注入HttpClient时注册拦截器：

builder.Services.AddTransient<ApiResponseValidationHandler>();
builder.Services.AddHttpClient("ProofOfDelivery.ServerAPI",
    client => client.BaseAddress = new Uri(builder.HostEnvironment.BaseAddress))
    .AddHttpMessageHandler<ApiResponseValidationHandler>();

问题答疑 #

1. 是否需要实现更智能的fallback逻辑，来对外提供缓存数据？
   如果你的业务需要支持离线使用，建议在客户端拦截器中实现：当API请求失败时，直接从IDBStore读取缓存的用户信息返回即可，不需要修改服务端的fallback逻辑，服务端fallback仅需处理页面导航场景。

2. 服务端恢复可用后，如何让HttpClient的请求恢复正常的网络请求？
   完成上述配置后不需要额外处理：HttpClient默认不会缓存API请求，Service Worker也已经排除了API路径，服务端恢复后下一次请求会直接走网络获取最新数据。

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