Spring Cloud Gateway — Reactive API Gateway for Spring Microservices

Introduction

Spring Cloud Gateway is the official API gateway for the Spring ecosystem, built on Project Reactor and Spring WebFlux. It provides a non-blocking, reactive way to route and filter requests to backend microservices. As part of the Spring Cloud project, it integrates seamlessly with service discovery, circuit breakers, and distributed tracing in Spring Boot applications.

What Spring Cloud Gateway Does

• Routes incoming HTTP requests to backend services based on path, header, query parameter, and custom predicates
• Applies filters for request/response modification including header manipulation, rate limiting, and request rewriting
• Integrates with Spring Cloud LoadBalancer for client-side load balancing across service instances
• Provides circuit breaker integration through Resilience4j to handle downstream failures gracefully
• Supports WebSocket proxying for real-time communication through the gateway

Architecture Overview

Spring Cloud Gateway processes requests through a handler mapping and filter chain built on Spring WebFlux. When a request arrives, the gateway evaluates route predicates to find a matching route, then applies a chain of pre-filters before forwarding the request to the upstream service. Post-filters process the response before returning it to the client. The entire pipeline is non-blocking, using Netty as the underlying server. Routes can be defined statically in YAML or dynamically through a REST API or service discovery.

Self-Hosting & Configuration

• Add spring-cloud-starter-gateway to your Spring Boot project dependencies
• Define routes in application.yml with predicates, filters, and target URIs
• Enable service discovery integration by setting spring.cloud.gateway.discovery.locator.enabled=true
• Configure rate limiting with the Redis-backed RequestRateLimiter filter
• Use Spring Boot Actuator endpoints to inspect active routes and gateway metrics at runtime

Key Features

• Predicate-based routing with built-in matchers for path, host, method, header, query, cookie, and time ranges
• Filter factories for common operations: adding headers, rewriting paths, retry, circuit breaking, and request size limiting
• Dynamic route management through REST API or integration with config servers for zero-downtime route changes
• Reactive architecture handles high-concurrency workloads with minimal thread usage
• First-class integration with the Spring Cloud ecosystem including Eureka, Consul, Sleuth, and Micrometer

Comparison with Similar Tools

• Kong — Full-featured standalone gateway with plugin ecosystem, but adds operational complexity outside the Spring ecosystem
• Netflix Zuul — The predecessor gateway for Spring Cloud, now replaced by Spring Cloud Gateway due to its blocking architecture
• Apache ShenYu — Plugin-based Java gateway with broader protocol support, but heavier to configure for pure Spring applications
• Envoy — High-performance C++ proxy ideal for service meshes, but requires separate configuration management outside Spring

FAQ

Q: Should I use Spring Cloud Gateway or Zuul? A: Spring Cloud Gateway is the recommended choice. Zuul 1 uses blocking I/O and is in maintenance mode. Spring Cloud Gateway is reactive and actively developed.

Q: Can I define routes dynamically without restarting? A: Yes. Use the Actuator gateway endpoints to add, modify, or delete routes at runtime via REST API. Routes can also be loaded from a Spring Cloud Config Server.

Q: Does it support gRPC? A: Spring Cloud Gateway primarily handles HTTP and WebSocket traffic. For gRPC, consider using a dedicated gRPC proxy or a general-purpose gateway like Envoy.

Q: How do I add authentication? A: Integrate Spring Security with the gateway. Use the TokenRelay filter to forward OAuth2 tokens to downstream services, or implement a custom GatewayFilter for API key validation.

Sources

• https://github.com/spring-cloud/spring-cloud-gateway
• https://spring.io/projects/spring-cloud-gateway