基于React的单页应用使用akka-http服务器时刷新返回404问题

这问题我之前帮同事排查过好几次，本质是Akka-HTTP的静态资源条件请求逻辑和SPA路由 fallback 的冲突。咱们一步步拆解原因和解决方案：

问题根源 #

React SPA刷新时，浏览器会根据当前URL（比如/user/profile）向服务器请求资源，但服务器上根本没有这个路径的文件——本来应该返回index.html让前端路由接管，但当请求带有If-Modified-Since头时，Akka-HTTP会先检查对应路径的文件是否存在，发现不存在后直接返回404，完全跳过了我们配置的fallback到index.html的路由逻辑。

而强制刷新（Ctrl+F5）时，浏览器会跳过缓存检查，不带If-Modified-Since头，所以Akka-HTTP会正常走到fallback路由，返回index.html。

解决方案：调整路由逻辑，手动处理条件请求 #

核心思路是：确保所有非静态资源的请求，无论是否带缓存头，最终都能 fallback 到index.html，同时正确处理缓存校验。

步骤1：基础路由结构（先静态资源，后fallback） #

首先要保证静态资源路由优先级最高，然后所有其他路径指向index.html：

import akka.http.scaladsl.server.Directives._
import akka.http.scaladsl.server.Route

// 静态资源路由（比如CSS、JS、图片等）
val staticRoute = pathPrefix("static") {
  getFromResourceDirectory("static") // 假设你的静态资源放在resources/static下
}

// 根路径直接返回index.html
val rootRoute = pathSingleSlash {
  getFromResource("index.html")
}

// 初始的SPA路由，但还没处理条件请求问题
val basicSpaRoute = staticRoute ~ rootRoute

步骤2：添加条件请求处理，修复404问题 #

我们需要手动处理If-Modified-Since头，确保即使请求路径不存在，也能返回index.html或正确的304响应：

import akka.http.scaladsl.model.{HttpResponse, StatusCodes}
import akka.http.scaladsl.model.headers._
import java.time.ZonedDateTime
import java.time.format.DateTimeFormatter

// 先获取index.html的最后修改时间（可以从资源文件元数据读取，这里硬编码示例）
val indexLastModified = ZonedDateTime.parse("2024-05-20T14:30:00Z")
val rfc1123Formatter = DateTimeFormatter.RFC_1123_DATE_TIME

// 处理条件请求的工具路由
val conditionalIndexRoute = get {
  optionalHeaderValueByName("If-Modified-Since") { maybeIfModifiedSince =>
    // 解析客户端传来的时间，处理格式错误的情况
    val clientModifiedTime = maybeIfModifiedSince.flatMap { dateStr =>
      try Some(ZonedDateTime.parse(dateStr, rfc1123Formatter))
      catch { case _: Exception => None }
    }

    clientModifiedTime match {
      // 如果客户端缓存的时间晚于等于文件最后修改时间，返回304
      case Some(clientTime) if clientTime.isAfter(indexLastModified.minusSeconds(1)) =>
        complete(HttpResponse(StatusCodes.NotModified))
      // 否则返回最新的index.html
      case _ =>
        getFromResource("index.html")
    }
  }
}

// 最终的SPA路由：静态资源 -> 根路径 -> 所有其他路径走条件处理的index.html
val finalSpaRoute = staticRoute ~ rootRoute ~ conditionalIndexRoute

步骤3：验证修复效果 #

用curl模拟带缓存头的请求测试：

# 模拟正常刷新的请求（带If-Modified-Since）
curl -v -H "If-Modified-Since: Mon, 20 May 2024 14:30:00 GMT" http://localhost:8080/user/profile

如果修复成功，你会看到返回200（如果缓存过期）或304（缓存有效），而不是404。

额外注意点 #

• 静态资源路径要正确：确保你的React打包后的静态资源（比如static/js/main.xxx.js）和Akka-HTTP的getFromResourceDirectory路径匹配。
• 不要忽略资源元数据：上面的示例硬编码了indexLastModified，实际项目中可以通过读取资源文件的lastModifiedTime来动态获取，避免手动更新。

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