Spring Cloud Gateway: Routing and Filters

Why Spring Cloud Gateway replaced Zuul

• Zuul 1 was blocking — one thread per request; thread pools exhausted under load
• Gateway runs on Netty and Project Reactor — non-blocking, a small thread pool handles thousands of concurrent connections
• Critical: Gateway requires a reactive runtime; do not add spring-boot-starter-web alongside webflux or the app fails to start

How routes are defined

• Each route has an id, a URI, predicates (match rules), and filters (transformations)
• Predicates match on path, method, headers, query params, cookies, or time windows
• lb://order-service triggers Spring Cloud LoadBalancer resolution via the service registry
• StripPrefix=1 removes path segments before forwarding — miscounting silently routes to wrong downstream paths
• YAML for static routes; programmatic RouteLocatorBuilder when logic depends on runtime state

Pre-filter and post-filter execution order

• Pre-filters run in ascending order number — lower order runs first
• Post-filters run in descending order — higher order runs first
• The outermost pre-filter is also the outermost post-filter, like nested parentheses
• Auth filter at order -1 runs before logging at order 1 in the pre-phase; in post-phase the logging runs first

GlobalFilter vs GatewayFilter

• GlobalFilter applies to every route automatically — use for auth, request-id injection, tracing setup
• GatewayFilter applies to routes that list it — use for route-specific path rewriting, rate limiting, circuit breaking
• Custom GatewayFilterFactory classes become reusable filter names referenced from YAML

Writing a JWT GlobalFilter

• Read the Authorization header, validate signature, short-circuit with 401 if invalid
• Mutate the request with extracted claims as X-User-Id / X-User-Roles headers for downstream services
• Validation must be non-blocking — JWT signature check is CPU-only; a JDBC lookup in the filter blocks the Netty event loop and destroys throughput
• For I/O-dependent validation, return a Mono and chain with flatMap/switchIfEmpty

The event-loop trap

• Any blocking call inside a filter holds a Netty thread handling hundreds of connections
• Symptoms: throughput collapses, connection queues grow, p99 latency balloons
• Use BlockHound or Reactor checkpoint() in dev to catch accidental blocks
• Prefer WebClient over RestTemplate inside filters

Production essentials

• Always chain with CircuitBreaker filter — one slow backend otherwise blocks the event loop and starves healthy routes
• Rate limit with RedisRateLimiter for distributed fleets; local rate limiters per pod don't coordinate
• Run at least three gateway instances behind a cloud load balancer with readiness probes
• Monitor gateway-internal latency separately from downstream latency — above 10ms means the gateway itself is under resource pressure

The strategic answer

• Spring Cloud Gateway is non-blocking; Netty event loop handles thousands of concurrent connections
• Routes compose predicates and filters; lb:// integrates service discovery
• Pre-filters ascend, post-filters descend — order bugs cause auth to fire after business logic
• Keep the gateway thin — auth, rate limit, route — business logic stays downstream
• Never block inside a filter; the event loop is the throughput