Master Spring Cloud Gateway: Real‑World Cases, Configurations, and Code Samples

1. Introduction

Spring Cloud Gateway is the official API‑gateway solution in the Spring Cloud ecosystem, built on Spring Framework 5, Spring Boot, and Project Reactor. It offers dynamic routing, monitoring, resilience, rate limiting, path rewriting, and filtering for micro‑service architectures, providing non‑blocking, asynchronous processing for high‑concurrency requests.

The gateway allows developers to configure routing, load balancing, security authentication, rate limiting, monitoring, and logging through simple configurations. It supports various routing predicates (path, request parameters, headers, host, etc.) and includes many built‑in filters such as rate limiting and circuit breaking, while also supporting custom filters.

Actuator integration enables management APIs; after adding the spring-boot-starter-actuator dependency, the gateway’s actuator endpoints become available.

<code>&lt;dependency&gt;
  &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
  &lt;artifactId&gt;spring-boot-starter-actuator&lt;/artifactId&gt;
&lt;/dependency&gt;</code>

2. Practical Cases

2.1 View Route Details

GET /actuator/gateway/route returns detailed JSON for each route, including predicates, metadata, route ID, filters, URI, and order.

<code>[
  {
    "predicate": "Paths: [/cloud-gateway/**], match trailing slash: true",
    "metadata": {
      "nacos.instanceId": null,
      "nacos.weight": "1.0",
      "nacos.cluster": "DEFAULT",
      "nacos.ephemeral": "true",
      "nacos.healthy": "true",
      "management.port": "8188",
      "preserved.register.source": "SPRING_CLOUD"
    },
    "route_id": "ReactiveCompositeDiscoveryClient_cloud-gateway",
    "filters": [
      "[[StripPrefix parts = 1], order = 1]",
      "[[RewritePath /cloud-gateway/(?<remaining>.*) = '/${remaining}'], order = 1]"
    ],
    "uri": "lb://cloud-gateway",
    "order": 0
  },
  ...
]</code>

To disable this verbose output, set:

<code>spring:
  cloud:
    gateway:
      actuator:
        verbose:
          enabled: false</code>

2.2 View Global Filters

GET /actuator/gateway/globalfilters returns a map of global filter class names to their execution order (smaller numbers execute earlier).

<code>{
    "org.springframework.cloud.gateway.filter.WebsocketRoutingFilter@1d1deb11": 2147483646,
    "org.springframework.cloud.gateway.filter.ReactiveLoadBalancerClientFilter@221961af": 10150,
    "org.springframework.cloud.gateway.filter.ForwardRoutingFilter@1cfb7450": 2147483647,
    "org.springframework.cloud.gateway.filter.RemoveCachedBodyFilter@1e288c76": -2147483648,
    "org.springframework.cloud.gateway.filter.RouteToRequestUrlFilter@738ed8f5": 10000,
    "org.springframework.cloud.gateway.filter.GatewayMetricsFilter@18d1d137": 0,
    "com.pack.common.filters.SecondFilter@38874eb5": 0,
    "com.pack.gray.loadbalancer.GrayReactiveLoadBalancerClientFilter@76b019c4": 10150,
    "org.springframework.cloud.gateway.filter.AdaptCachedBodyGlobalFilter@41463c56": -2147482648,
    "org.springframework.cloud.gateway.filter.LoadBalancerServiceInstanceCookieFilter@32ddcca": 10151,
    "org.springframework.cloud.gateway.filter.NettyRoutingFilter@1ddc8fc": 2147483647,
    "com.pack.common.filters.BrushProofFilter@55202ba6": -2,
    "org.springframework.cloud.gateway.filter.NettyWriteResponseFilter@77d58f3a": -1,
    "com.pack.common.filters.FirstFilter@2ef1fc8a": 1,
    "org.springframework.cloud.gateway.filter.ForwardPathFilter@478c84aa": 0
}</code>

2.3 Route Filters

GET /actuator/gateway/routefilters lists all available GatewayFilter factories, including default and custom ones (e.g., CustomGatewayFilterFactory ).

2.4 Refresh Routes

POST /executor/gateway/refresh clears the route cache and returns a 200 response with no body. The gateway uses RouteLocator (implemented by CachingRouteLocator ) to locate routes and caches them in a map. It listens for RefreshRoutesEvent to reload routes when the event is published.

2.5 Get Defined Routes

GET /executor/gateway/routes returns the list of routes defined in the gateway.

<code>[
  {
    "predicate": "Paths: [/cloud-gateway/**], match trailing slash: true",
    "metadata": {
      "nacos.instanceId": null,
      "nacos.weight": "1.0",
      "nacos.cluster": "DEFAULT",
      "nacos.ephemeral": "true",
      "nacos.healthy": "true",
      "management.port": "8188",
      "preserved.register.source": "SPRING_CLOUD"
    },
    "route_id": "ReactiveCompositeDiscoveryClient_cloud-gateway",
    "filters": [
      "[[StripPrefix parts = 1], order = 1]",
      "[[RewritePath /cloud-gateway/(?<remaining>.*) = '/${remaining}'], order = 1]"
    ],
    "uri": "lb://cloud-gateway",
    "order": 0
  },
  ...
]</code>

Field description:

route_id (String): Route identifier.

route_object.predicate (Object): Route predicate.

route_object.filters (Array): GatewayFilter factories applied to the route.

order (Number): Route order.

2.6 Get Specific Route Information

GET /actuator/gateway/routes/{id} (e.g., /actuator/gateway/routes/first_route ) returns the details of a single route.

Field description:

id (String): Route ID.

predicates (Array): Collection of route predicates.

filters (Array): Filters applied to the route.

uri (String): Target URI of the route.

order (Number): Route order.

2.7 Create & Delete Routes

To create a route, POST JSON to /gateway/routes/{id_route_to_create} with the same fields described in section 2.6.

To delete a route, send a DELETE request to /gateway/routes/{id_route_to_delete} .

Note: By default, created routes are stored in memory and disappear after a service restart.

2.8 Route Sharing

Spring Cloud Gateway provides two RouteDefinitionRepository implementations:

InMemoryRouteDefinitionRepository : Stores routes only in a single gateway instance’s memory; unsuitable for clustered environments.

RedisRouteDefinitionRepository : Enables route sharing across multiple gateway instances. Enable it by setting spring.cloud.gateway.redis-route-definition-repository.enabled=true and adding the spring-boot-starter-data-redis-reactive dependency.

<code>&lt;dependency&gt;
  &lt;groupId&gt;org.springframework.boot&lt;/groupId&gt;
  &lt;artifactId&gt;spring-boot-starter-data-redis-reactive&lt;/artifactId&gt;
&lt;/dependency&gt;</code>

<code>spring:
  cloud:
    gateway:
      redis-route-definition-repository:
        enabled: true</code>

The article concludes with a reminder to like, share, and collect the content.