Spring Cloud Gateway：一次不规范 URL 引发的路由转发404问题排查 - 教程

Spring Cloud Gateway：一次不规范 URL 引发的路由转发404问题排查

最近做网关 Spring Cloud Gateway功能开发，联调的时候，把本地网关代理出去了，遇到了一个令人困惑的问题：为什么同一个接口，用 IP 形式访问就正常，而换成域名就直接返回 404 Not Found？

这个问题抽象出来是这样的：

本地用 curl 模拟调用，无论是 IP 还是域名，都能正常转发。按理来说域名只是加了个代理转发，网关能够收到域名过来的请求，就正常的。这次分析了 Spring Cloud Gateway 的源码，一探究竟。

源码追踪：追查 404 的元凶

我的追查从 Spring WebFlux 的核心分发器 DispatcherHandler 开始。

DispatcherHandler#handle：请求分发入口

DispatcherHandler 负责将传入的 ServerWebExchange（代表一个 HTTP 请求）分发给正确的处理器（Handler）。

public Mono handle(ServerWebExchange exchange) {
if (this.handlerMappings == null) {
return createNotFoundError();
}
if (CorsUtils.isPreFlightRequest(exchange.getRequest())) {
return handlePreFlight(exchange);
}
return Flux.fromIterable(this.handlerMappings)
.concatMap(mapping -> mapping.getHandler(exchange))
.next()
.switchIfEmpty(createNotFoundError())
.flatMap(handler -> invokeHandler(exchange, handler))
.flatMap(result -> handleResult(exchange, result));
}

在这里插入图片描述

这段代码采用了响应式编程的链式调用，依次执行逻辑：

查找 Handler：Flux.fromIterable(this.handlerMappings)将所有注册的**HandlerMapping**（如 RoutePredicateHandlerMapping、SimpleUrlHandlerMapping 等）放入一个响应式流中。concatMap会顺序地调用每个mapping的getHandler()方法，尝试找到能够处理该请求的Handler。

接下来，我将目光锁定在了 Spring Cloud Gateway 自己的 Handler 上。

RoutePredicateHandlerMapping#getHandlerInternal：路由匹配核心

作为 Gateway 路由匹配的核心，RoutePredicateHandlerMapping 的主要任务就是根据配置的路由谓词，为请求找到对应的 Route。

RoutePredicateHandlerMapping实现了getHadnlerInternal方法，整体是一个模版设计模式，某些细节下放到子类实现。

protected Mono getHandlerInternal(ServerWebExchange exchange) {
// ...
return lookupRoute(exchange)
.flatMap((Function>) r -> {
// ... 找到路由后返回 FilteringWebHandler
return Mono.just(webHandler);
}).switchIfEmpty(Mono.empty().then(Mono.fromRunnable(() -> {
logger.trace("No RouteDefinition found for [" + getExchangeDesc(exchange) + "]");
})));
}
protected Mono<
Route> lookupRoute(ServerWebExchange exchange) {
return this.routeLocator.getRoutes()
// individually filter routes so that filterWhen error delaying is not a
// problem
.concatMap(route ->
Mono.just(route).filterWhen(r ->
{
// add the current route we are testing
exchange.getAttributes().put(GATEWAY_PREDICATE_ROUTE_ATTR, r.getId());
return r.getPredicate().apply(exchange);
})
// instead of immediately stopping main flux due to error, log and
// swallow it
.doOnError(e -> logger.error("Error applying predicate for route: " + route.getId(), e))
.onErrorResume(e ->
Mono.empty()))
// .defaultIfEmpty() put a static Route not found
// or .switchIfEmpty()
// .switchIfEmpty(Mono.<Route>empty().log("noroute"))
  .next()
  // TODO: error handling
  .map(route ->
  {
  if (logger.isDebugEnabled()) {
  logger.debug("Route matched: " + route.getId());
  }
  validateRoute(route, exchange);
  return route;
  });
  /*
  * TODO: trace logging if (logger.isTraceEnabled()) {
  * logger.trace("RouteDefinition did not match: " + routeDefinition.getId()); }
  */
  }

源码解读：

  • lookupRoute(exchange)：这是查找路由的核心方法。它会遍历所有已定义的路由，并用每个路由的谓词去判断是否与当前请求匹配。
  • .flatMap(...): 如果 lookupRoute 找到了 Route，就会返回一个 Mono.just(webHandler)，这里的 webHandler 就是 FilteringWebHandler，用于执行路由过滤器链。
  • .switchIfEmpty(...): 如果 lookupRoute 没有找到任何匹配的路由，它会返回一个空的 Mono，从而导致 getHandlerInternal 方法也返回 Mono.empty()，即它无法处理该请求。

RoutePredicateHandlerMapping 因为没有匹配到任何路由，无法返回有效的 FilteringWebHandler。
接下来，我们看遍历route，然后执行谓词匹配

GatewayPredicate#test：

我继续追踪，最终定位到了路由谓词判断的核心方法：org.springframework.cloud.gateway.handler.predicate.GatewayPredicate#test。

Java

public boolean test(ServerWebExchange exchange) {
PathContainer path = parsePath(exchange.getRequest().getURI().getRawPath());
PathPattern match = null;
for (PathPattern pathPattern : pathPatterns) {
if (pathPattern.matches(path)) {
match = pathPattern;
break;
}
}
// ...
return match != null;
}

源码解读：

  • exchange.getRequest().getURI().getRawPath(): 谜底就在这里！ 这行代码用于获取请求的 URI 路径。getRawPath() 方法获取的是未解码的、原始的路径字符串，这对于路径匹配至关重要。
  • pathPattern.matches(path): 这里就是进行路由匹配的最终判断，将从 getRawPath() 获取的路径与路由规则进行对比。

核心问题就出在 getRawPath() 的返回值上。

IP 形式的请求：http://localhost:9900/api-user/xxxx1

getRawPath() 得到 /api-user/xxxx1。该路径与我们配置的路由规则完美匹配，test 方法返回 true，路由成功。

域名形式的请求：http://xxx.xxx.xxx/:9900/api-user/xxxx1

这里的 URL 格式不规范，在主机名和端口号之间多了一个斜杠 /。根据 URI 规范，端口号后面不应有斜杠。当 Java 的 URI 解析器遇到这个不规范的格式时，它会将 :9900/ 当作路径的一部分，而端口视为80，

因此，getRawPath() 返回 /:9900/api-user/xxxx1。看到这个变量，长的非常奇怪，一下子问题点就发现了，这个不正确的路径自然无法匹配 /api-user/** 的路由规则以及任意其他的路由规则，test 方法返回 false，路由失败。
无法走网关的匹配逻辑，就无法使用RoutePredicateHandlerMapping的FilteringWebHandler
后续流程交给SimpleUrlHandlerMapping的ResourceWebhandler的逻辑，同样的在ResourceWebHandler里面也找不到:9900/api-user/xxxx1路径。
这个ResourceWebHandler是在

  • META-INF/resources/
  • resources/
  • static/
  • public/

这些地方找静态资源,导致无法找到资源，从而404。接口响应的404也是在这里返回的。

在这里插入图片描述

总结：问题的完整链路

  1. URL 格式不规范： 域名请求 http://xxx.xxx.xxx/:9900/ 多了一个不该存在的斜杠。
  2. 路径解析错误：getRawPath() 将 :9900/ 解析成了路径的一部分，导致路径变为 /:9900/api-user/xxxx1。
  3. 路由匹配失败： 错误的路径无法匹配任何路由规则，GatewayPredicate#test 返回 false。
  4. Handler 寻找失败：RoutePredicateHandlerMapping 因为没有找到匹配的路由，所以无法返回 FilteringWebHandler。
  5. 请求被 ResourceWebHandler 接管： 鉴于请求没有找到任何业务 Handler，Spring Boot 默认配置中的 SimpleUrlHandlerMapping 会将请求交给 ResourceWebHandler 处理，期望它能找到静态资源。
  6. 最终返回 404： 然而，在静态资源目录下，自然找不到 /:9900/api-user/xxxx1 这个文件。ResourceWebHandler 同样无法处理该请求，最终导致 DispatcherHandler 抛出 404 Not Found 错误。

最终结论与解决方案

问题的根源在于域名 URL 格式不规范，导致网关获取到错误的请求路径，进而无法匹配任何路由，最终返回 404 Not Found 错误。

  • 根本解决方案： 从源头修改请求 URL 格式，确保其符合规范，即 http://xxx.xxx.xxx:9900/api-user/xxxx1。
  • 临时解决方案（不推荐）： 如果无法修改前端，可以在网关内部编写自定义的全局过滤器（GlobalFilter），在路由匹配之前，手动修正这个不规范的路径。

这次排查不仅解决了实际问题，也让我深刻理解了 URI 规范的重要性，以及 Spring Cloud Gateway 路由匹配的底层机制。在未来，遇到类似的路由问题时，我们应该首先检查请求的原始路径是否符合预期。

posted @ 2025-09-18 12:56  yfceshi  阅读(99)  评论(0)    收藏  举报