Master Spring Cloud Gateway: Routing, Metrics, Filters & Debugging Tips

1. Mark Exchange as Already Routed

After the gateway routes a ServerWebExchange , it sets the gatewayAlreadyRouted flag so subsequent global filters skip routing. You can customize a global filter to control execution:

<code>@Component
public class PackGlobalRoutingFilter implements GlobalFilter {
    @Override
    public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
        if (!ServerWebExchangeUtils.isAlreadyRouted(exchange)) {
            System.out.println("还没被北路由...");
        }
        // set already routed, later filters will be skipped
        ServerWebExchangeUtils.setAlreadyRouted(exchange);
        return chain.filter(exchange);
    }
}
</code>

2. Routing Metrics

To enable RouteDefinition metrics, add spring-boot-starter-actuator . When spring.cloud.gateway.metrics.enabled is true, a metric named spring.cloud.gateway.routes.count is exposed via /actuator/metrics/spring.cloud.gateway.routes.count .

<code>spring:
  cloud:
    gateway:
      metrics:
        enabled: true
</code>

3. Route Metadata Configuration

Metadata can be attached to a route to store extra information.

<code>spring:
  cloud:
    gateway:
      routes:
      - id: params
        uri: http://localhost:8088
        predicates:
        - Path=/api-1/**
        metadata:
          x-key: xxxooo
          version: 1.0.0
</code>

Retrieve metadata in a filter:

<code>public Mono<Void> filter(ServerWebExchange exchange, GatewayFilterChain chain) {
    Route route = exchange.getAttribute(GATEWAY_ROUTE_ATTR);
    System.out.printf("路由元数据: %s%n", route.getMetadata());
    return chain.filter(exchange);
}
</code>

4. Reactor Netty Access Log

Enable access logs by setting the system property:

<code>-Dreactor.netty.http.server.accessLogEnabled=true</code>

The console will display request details, as shown in the image below.

5. Troubleshooting – Logging Levels

Configure detailed debug logs for gateway components:

<code>logging:
  level:
    web: debug
    '[org.springframework.cloud.gateway]': debug
    '[org.springframework.http.server.reactive]': debug
    '[org.springframework.web.reactive]': debug
    '[org.springframework.boot.autoconfigure.web]': debug
    '[reactor.netty]': debug
    '[redisratelimiter]': debug
</code>

After this configuration, every routed request will output extensive debug information.

6. Disable Route Refresh

From Spring Cloud Gateway 4.1.2 you can disable the automatic RouteRefreshListener :

<code>spring:
  cloud:
    gateway:
      route-refresh-listener:
        enabled: false
</code>

7. Global Filter Order with @Order

Since 4.1.2, GlobalFilter can use @Order to control execution order, replacing the need to implement Ordered .

<code>@Component
@Order(-1)
public class GlobalFilter1 implements GlobalFilter {}

@Component
@Order(-2)
public class GlobalFilter2 implements GlobalFilter {}
</code>

8. Actuator Gateway Sub‑paths

When Actuator is enabled, the following endpoints expose detailed route information:

/ac/gateway/refresh

/ac/gateway/routes

/ac/gateway/routedefinitions

/ac/gateway/routes/params

/ac/gateway/routefilters

/ac/gateway/routes/params/combinedfilters

/ac/gateway/globalfilters

/ac/gateway/routepredicates

9. Rewrite Request Parameter Filter

The new RewriteRequestParameterGatewayFilterFactory can rewrite a specific request parameter value.

<code>spring:
  cloud:
    gateway:
      routes:
      - id: params
        uri: http://localhost:8088
        filters:
        - name: RewriteRequestParameter
          args:
            name: a
            replacement: ac
</code>

After configuration, the request parameter a is changed from a1 to ac .