Spring Cloud Gateway：建议收藏

▌ 技术引导 Spring Cloud Gateway 2024年版本对比Netflix Zuul已经不是简单的替代，而是具备更强的异步能力、更丰富的过滤器链和更清晰的路由策略。我之前在分布式微服务架构中用它重构网关，亲测配置动态路由、限流、鉴权这些功能在高并发场景下表现稳定，但细节上容易出问题。比如路由规则加载失败、请求转发时地址解析异常、动态配置更新无感知，这些是真实踩过的坑。启动日志里看到`RouteDefinitionLocator`无法获取路由信息，说明可能没正确注册配置源。如果配置了`spring.cloud.gateway.routes`，但没加上`load-balancer`依赖，负载均衡会失效。我见过很多项目因为没正确设置`predicates`和`filters`，导致请求转发到错误的服务，或者过滤器执行顺序混乱，最终引发认证失败、缓存不命中等问题。直接上干货，具体配置、命令、参数和真实场景问题。 ▌ 技术参考 一 配置动态路由时必须明确指定`RouteDefinitionLocator`的实现类 在Spring Cloud Gateway 2025年版本中，如果使用`spring.cloud.gateway.routes`属性定义路由规则，必须确保`RouteDefinitionLocator`被正确注入。比如在`@Bean`注解的`RouteDefinitionLocator`中，如果使用`ConfigurableRouteDefinitionLocator`，需要在启动时指定`@PropertySource`加载`application.yml`或`application.properties`。若未注入，即使配置了路由规则，也无法生效。实际操作中，可使用命令`curl http://localhost:8080/actuator/routes`查看路由是否加载成功，该命令在Spring Cloud Gateway 2024年版本后已内置。如果未加载，检查是否缺少`spring-cloud-starter-gateway`依赖，或者配置的`spring.cloud.gateway.routeDefinitions`未正确设置。 二 配置`predicates`时需注意`Path`和`RewritePath`的顺序 很多项目在使用`Path`或`RewritePath`时，顺序错误会导致路由规则失效。比如`Path`应该放在`RewritePath`之前，因为`RewritePath`会修改请求路径，而`Path`用于匹配原始路径。我之前处理过一个项目，因为`RewritePath`在前，导致所有请求都被重写成`/api/`，后续`Path`规则无法匹配到具体服务。具体的配置项应为`predicates[0].Path=/api/`，`predicates[1].RewritePath=/api/(?.), /$\{segment}`。在Spring Cloud Gateway 2026版本中，该行为已固化，不支持顺序自定义，所以配置时必须严格遵循。 三 `filters`配置中`StripPrefix`和`RewritePath`的组合使用需谨慎 在处理路径重写时，`StripPrefix`和`RewritePath`的组合容易造成路径解析错误。比如，如果请求是`/api/v1/user/123`，希望转发到`/user/123`，需要先使用`RewritePath=/api/(?.), /$\{segment}`，再用`StripPrefix=1`。如果顺序反过来，就会导致路径截断失败，服务无法访问。在Spring Cloud Gateway 2024年版本中，`StripPrefix`的参数是整数，表示截断的前缀个数，而非字符串。实际测试中发现，当使用`StripPrefix=1`时，路径`/api/v1/user/123`会被重写为`/v1/user/123`，而不是预期的`/user/123`。必须结合`RewritePath`使用，否则容易误判请求路径。 四 使用`LoadBalancerClient`时需确认是否启用`lb`前缀 Spring Cloud Gateway默认会在服务名称前添加`lb`前缀，例如`lb://service-name`，以便自动识别为负载均衡服务。如果未启用，服务调用会失败。在Spring Cloud Gateway 2025年版本中，`lb`前缀必须显式配置，否则无法解析服务名。可以通过配置`spring.cloud.gateway.routes[0].filters.add=lb://service-name`来确保服务名称被正确解析。如果服务名未被正确识别，可能会导致请求直接访问IP地址，从而引发跨域或认证问题。在真实场景中，我发现许多项目未配置`lb`前缀，导致服务调用失败，尤其是使用Nacos或Consul时，这点尤为重要。 五 `GlobalFilter`和`RouteFilter`的执行顺序会影响请求处理逻辑 在Spring Cloud Gateway中，`GlobalFilter`会在`RouteFilter`之前执行。这意味着，即使你在某个路由中配置了过滤器，如果全局过滤器中包含`StripPrefix`，可能会覆盖路由中定义的路径。我之前在一个项目中，全局过滤器中配置了`StripPrefix=0`，而某个路由中配置了`StripPrefix=1`，结果发现请求路径被错误地截断。解决办法是将`StripPrefix`放在`RouteFilter`中，或者调整全局过滤器的执行顺序。这需要在`spring.cloud.gateway.global-filters`中设置`order`属性，确保特定过滤器优先级正确。否则，容易引发逻辑混乱。 六 `Authorization`过滤器需要正确配置`Spring Security`模块 如果使用Spring Security进行鉴权，必须确保`Spring Security`模块被正确引入，并且`Gateway`与`Security`的配置不冲突。在Spring Cloud Gateway 2024年版本中，`SecurityConfig`需要手动配置，例如在`configure`方法中添加`SecurityWebFilterChain`。如果未正确配置，可能会导致所有请求都被拒绝，甚至出现`403 Forbidden`错误。此外，`Authorization`过滤器需要与`spring.cloud.gateway.routes`中的`filters`联动，例如添加`SecurityWebFiltersOrder`来调整执行顺序。在真实项目中，我发现很多团队直接使用`SecurityConfig`而不配置`Gateway`专用的过滤器，导致鉴权失败。 七 `CircuitBreaker`配置时需明确指定`fallback`方法 使用`CircuitBreaker`进行熔断时，必须配置`fallback`方法，否则异常不会被正确处理。在Spring Cloud Gateway 2026版本中，`CircuitBreaker`默认使用`Resilience4j`，需要在`application.yml`中添加`spring.cloud.gateway.circuitbreaker.enabled=true`并指定`fallback`类。比如`spring.cloud.gateway.filters.post=org.springframework.cloud.gateway.filter.factory.CircuitBreakerFilterFactory`。如果未配置，即使服务调用失败，也不会触发熔断机制，而是继续重试。实际调试中，我发现很多项目未配置`fallback`，导致熔断机制失效，反而加重了服务压力。 八 `RateLimiter`过滤器需要配合`Redis`进行分布式限流 如果使用`RateLimiter`进行请求限流，必须配置`Redis`作为存储介质，否则限流策略会失效。在Spring Cloud Gateway 2024年版本中，`RateLimiter`默认使用`Redis`，但需要在`application.yml`中设置`spring.redis.host`和`spring.redis.port`。如果未配置，会使用内存中的`Redis`实例，导致限流仅限于当前应用，无法跨节点生效。实际测试中，发现很多开发者未正确配置`Redis`，导致限流策略无法正常工作，尤其是在高并发场景下。必须确保`Redis`连接正常，并且`RateLimiter`的`key`配置正确，例如`rate-limiter.key-resolver=org.springframework.cloud.gateway.filter.ratelimit.KeyResolver#1`。 九 `RequestCache`过滤器在`OAuth2`鉴权中容易造成请求丢失 在使用`OAuth2`鉴权时，如果请求携带`Authorization`头，但未正确配置`RequestCache`，可能会导致请求被丢失。在Spring Cloud Gateway 2026版本中，`RequestCache`默认会缓存请求头信息，但如果未显式配置，一些请求会被重定向或丢失。例如，在`SecurityConfig`中需要添加`requestCache()`方法，并设置`RequestCache`为`RequestCache`类的实例。否则，用户在登录过程中可能会被强制跳转，导致原始请求路径丢失。这在实际项目中容易踩坑，尤其是在前后端分离架构中，必须确保`RequestCache`配置正确。 十 `WebSocket`支持需在`application.yml`中添加`spring.cloud.gateway.websocket`配置 如果使用`WebSocket`连接，必须在配置文件中添加`spring.cloud.gateway.websocket`相关的参数，否则无法启用支持。例如，需要设置`spring.cloud.gateway.websocket.routes[0].predicates[0].Path=/ws/`，同时配置`spring.cloud.gateway.websocket.routes[0].filters.add=WebsocketFilterFactory`。如果未正确配置，WebSocket连接会被拒绝，甚至导致`500 Internal Server Error`。在实际项目中，我发现很多团队未配置`WebSocket`相关参数，导致用户无法建立连接，尤其是当使用`Netty`作为底层传输协议时，必须确保配置完整。 十一 `Cookie`解析失败常因未配置`CookieName`或`CookieValue` 在使用`Cookie`进行认证时，如果配置错误，可能会导致`Cookie`无法被解析，进而引发鉴权失败。例如，在`SecurityConfig`中，需要正确设置`CookieName`和`CookieValue`，否则`Spring Security`无法识别请求头中的`Cookie`信息。在Spring Cloud Gateway 2025年版本中，`Cookie`解析默认不启用，必须手动添加`CookieFilter`或`CookieName`参数。如果未配置，用户登录后的`Cookie`会被忽略，导致所有请求都需要重新认证。在实际项目中，我见过很多因为`Cookie`配置错误，导致用户状态无法保持。 十二 `X-forwarded`头信息缺失导致`LoadBalancer`异常 在使用`LoadBalancer`时，如果请求中缺少`X-Forwarded-For`、`X-Forwarded-Proto`等头信息，可能导致`LoadBalancer`无法正确识别客户端IP和协议类型。在Spring Cloud Gateway 2024年版本中，`LoadBalancer`会自动添加这些头信息，但某些场景下，比如直接访问网关而未经过`Nginx`或`HAProxy`，这些头会被移除，导致`LoadBalancer`识别错误。实际测试中，我发现这种情况会导致日志中出现`Client IP is unknown`的错误，而`限流`或`日志记录`功能也会失效。因此，在某些高安全场景下，必须手动添加这些头，例如在`filters`中使用`AddRequestHeaderFilter`。 十三 `Logging`过滤器需要配置`pattern`和`file`路径 在使用`Logging`过滤器记录请求日志时，必须正确配置`pattern`和`file`路径，否则日志无法生成。例如，在`application.yml`中添加`spring.cloud.gateway.filters.logging.enabled=true`，并配置`spring.cloud.gateway.filters.logging.pattern=short`，同时指定`spring.cloud.gateway.filters.logging.file=logs/gateway.log`。如果未指定`file`路径，日志会写入控制台，导致在生产环境中无法有效追踪。此外，`pattern`设置为`full`时，会记录完整的请求信息，包括`headers`、`body`等，这对调试非常有用，但会增加日志量，需根据场景判断是否开启。 十四 `HTTPS`转发需配置`RewritePath`和`StripPrefix` 当使用`HTTPS`进行转发时，必须确保请求路径被正确重写，否则服务端可能无法识别请求。例如，在`predicates`中配置`Path=/api/`，在`filters`中使用`RewritePath=/api/(?.), /$\{segment}`，并添加`StripPrefix=1`，以确保路径被正确剥离。如果未配置，`HTTPS`请求可能会被错误地转发到非`HTTPS`端点，导致`SSLHandshakeException`。在Spring Cloud Gateway 2026版本中，`HTTPS`转发已支持自动识别，但某些情况下仍需手动处理，尤其是在请求路径复杂或服务端配置不一致时。 十五 `Routing`性能受`Ribbon`和`LoadBalancer`影响 在高并发场景下，`Routing`性能受`Ribbon`和`LoadBalancer`配置影响。例如，在`application.yml`中配置`spring.cloud.loadbalancer.ribbon.enabled=true`，可以优化`LoadBalancer`的响应速度。如果未启用，请求可能会被阻塞，导致`TTL`超时。`Ribbon`的`maxAttempts`和`retries`参数也会影响`Routing`效率，设置为`maxAttempts=3`和`retries=2`可以提升容错能力，但会增加延迟。实际测试中，发现某些服务调用响应速度慢，是因为`Ribbon`未正确配置，导致请求不断重试。必须合理调整参数，确保在可用性和性能之间取得平衡。 十六 `Integration`测试时需使用`TestRestTemplate`模拟请求 在进行集成测试时，`TestRestTemplate`是模拟`HTTP`请求的首选工具。例如可以通过`RestTemplate`发送`POST`请求，并设置`headers`模拟认证信息。例如`restTemplate.postForLocation("/api/user", body, headers)`，可以验证路由是否正确。如果未使用`TestRestTemplate`，而是直接启动应用，可能会因为配置错误导致测试无法覆盖所有场景。在Spring Cloud Gateway 2025年版本中，`TestRestTemplate`已支持更复杂的`headers`配置，包括`Cookie`和`Authorization`，这对测试鉴权和限流功能非常关键。 十七 `Fallback`场景下需确保`Bean`可用 在配置`Fallback`时，必须确保`Fallback`类被正确加载，否则会报`No bean`错误。例如，如果使用`@Component`注解定义`Fallback`，需要将其注册为`Bean`，否则无法被`Gateway`识别。在Spring Cloud Gateway 2026版本中，默认不加载`Fallback`，必须手动通过`@Bean`创建。例如`@Bean public FallbackProvider fallbackProvider() { return new CustomFallbackProvider(); }`。如果未正确配置，可能导致服务异常时无法返回默认响应。 十八 `WebSocket`过滤器需在`filters`中显式声明 在使用`WebSocket`时，必须在`filters`中显式声明`WebSocketFilter`，否则无法处理`WebSocket`连接。例如，可以通过`filters.add=WebSocketFilterFactory`来启用相关功能。在Spring Cloud Gateway 2024年版本中，`WebSocket`已内置支持，但需要配置`predicates`指向特定路径，例如`Path=/ws/`。如果未配置，连接会失败，甚至导致`404`错误。实际项目中，发现很多团队未正确配置`WebSocket`相关过滤器，导致用户无法连接。 十九 `Path`和`RewritePath`需结合`ServiceId`使用 在使用`ServiceId`时，必须确保`Path`和`RewritePath`的配置正确，否则请求无法被正确转发。例如，`Path=/api/`应与`RewritePath=/api/(?.), /$\{segment}`配合使用，确保路径被正确重写。如果`ServiceId`未被正确识别，可能会导致请求被转发到错误的服务实例。在Spring Cloud Gateway 2025年版本中，`ServiceId`必须与`LoadBalancer`配合使用，否则无法实现动态路由。因此，配置`LoadBalancer`是必要的前提条件。 二十 `Coercion`配置错误会导致`JSON`解析失败 在处理`JSON`请求时，如果`Coercion`配置错误，可能导致`JSON`解析失败。例如，在`application.yml`中配置`spring.codec.max-multipart-file-size=10MB`，可以避免文件过大导致解析失败。此外，如果`JSON`请求体包含特殊字符，必须确保`Coercion`规则正确，否则会抛出`JsonProcessingException`。在Spring Cloud Gateway 2026版本中，`Coercion`已支持更多格式，但仍需手动配置`max-size`和`encoding`参数，以避免请求体过大导致服务器崩溃。