Spring Cloud Gateway: a Java API gateway with two server stacks

What Spring Cloud Gateway actually replaces

An API gateway sits between clients and backend services and decides, per request, where the request goes and what is done to it on the way. Spring Cloud Gateway does that inside a Spring Boot application. The README lists the feature set plainly: dynamic routing, route matching built into Spring Handler Mapping, matching on HTTP request attributes such as Path, Method, Header and Host, filters scoped to the matching route, and filters that can modify the downstream request and response (adding or removing headers and parameters, rewriting or setting the path, circuit breaking).

The intended user is a team already running Spring Boot services that wants the edge to be another Spring Boot application rather than a separate proxy product with its own configuration language. Routes can be defined through an API or through configuration, and Spring Cloud DiscoveryClient can supply the route targets, so an existing service registry can drive the routing table instead of a hand-maintained list of hosts. The baseline is Java 17, Spring Framework 6 and Spring Boot 3, which is stated at the top of the README and is not negotiable.

Handler Mapping as the routing engine

The design choice that separates this project from most gateways is that route matching is not a bespoke matcher bolted onto the front of the framework. It is built into Spring Handler Mapping. A gateway route is therefore expressed in the same request-matching vocabulary Spring MVC and WebFlux developers already use, and a predicate that does not match simply means the route does not handle the request.

Filters are the second half of the mechanism. They are scoped to the matching route, and the README states they can modify the downstream HTTP request and the HTTP response: add or remove headers, add or remove parameters, rewrite the path, set the path, or apply a circuit breaker. That is the whole data flow: an incoming request is matched against route predicates, the winning route's filters run, the request is forwarded, and response filters run on the way back.

The repository layout shows how this is packaged. There is spring-cloud-gateway-server plus separate spring-cloud-gateway-server-webflux and spring-cloud-gateway-server-webmvc modules, matching proxyexchange modules for each, and two starters: spring-cloud-starter-gateway-server-webflux and spring-cloud-starter-gateway-server-webmvc. That is a meaningful change from the single-stack history of the project. Two server implementations mean two sets of runtime behaviour to reason about, and the README does not explain when to pick which.

Installing Spring Cloud Gateway and writing a first route

The README documents how to build the project itself, not how to consume it. For that, the repository layout is the guide: the consumable artifacts are the starters. Building from source requires JDK 17 and the Maven wrapper, and the README notes that projects requiring middleware such as Redis for testing generally need a local Docker instance running.

To build the source tree:

./mvnw install

The README adds that you can install Maven yourself (version 3.3.3 or later) and use mvn instead of ./mvnw, and that if your local Maven settings lack repository declarations for Spring pre-release artifacts you may need to add -P spring. It also warns that you may need to raise Maven memory through the MAVEN_OPTS environment variable, with an example value of -Xmx512m -XX:MaxPermSize=128m, though the .mvn configuration is intended to cover this.

For documentation, the README describes a docs profile that builds asciidoc sources with Antora from modules/ROOT/:

./mvnw -pl docs -P docs antora:antora

What the README does not contain is an application-level quickstart: no route YAML, no example of a predicate, no port number. Those live in the generated documentation rather than the README, and the README itself is generated from src/main/asciidoc/ and warns that manual edits to it will be lost. A reader looking for a copy-pasteable first route should go to the project documentation, not the README.

Two server stacks and the cost of choosing

The most consequential limitation is structural. The repository carries spring-cloud-gateway-server-webflux and spring-cloud-gateway-server-webmvc as distinct modules with distinct starters. A reactive stack and a servlet stack do not share a runtime model, and the README does not document feature parity between them, nor how to move an existing route and filter configuration from one to the other. Anyone starting today has to make that decision up front, and the README gives no criteria for making it.

The second limitation is the platform floor. Java 17, Spring Framework 6 and Spring Boot 3 are the stated baseline. A team on an older Spring Boot line cannot adopt this version without a framework upgrade, and the README does not present a compatibility matrix for older lines. That is not a defect, but it is a real constraint that shows up as a migration project rather than a dependency addition.

The third is documentation placement. The README is generated from asciidoc sources, and its own instructions say to edit files in src/main/asciidoc/ instead. That is a sensible pipeline, but it means the README is a build artifact and a poor place to look for API detail. Configuration keys, predicate names and filter names are not enumerated there.

Where Spring Cloud Gateway is the wrong tool

If the services behind the gateway are not JVM services, the main advantage disappears. The value here is that routes, predicates and filters live in the same Spring programming model as the rest of the system. A polyglot estate gets less from that, and pays the cost of running a JVM at the edge.

It is also the wrong choice when the edge must be configured by people who do not write Java. Route configuration is supported, but the deeper customisation path is Java filters, and the README frames the project as configuration or API driven within a Spring application, not as a standalone proxy with an operator-facing control plane.

Finally, if you need a gateway whose documentation is a single self-contained reference with an application quickstart in the front matter, this project's README will frustrate you. It documents building and contributing to Spring Cloud Gateway, and defers usage to generated docs. That is a deliberate split, not an oversight, but it changes where you spend your first hour.

Comparing it with a language-agnostic proxy

The obvious alternative class is a standalone proxy such as Envoy or NGINX, or a gateway built on one of them. The difference in approach is where the routing logic lives. Those tools run as their own process with their own configuration format and extension mechanism, typically independent of the application language, and they can front services written in anything.

Spring Cloud Gateway inverts that. It is a library-shaped gateway: your gateway is a Spring Boot application you build, and routing behaviour is expressed through Spring Handler Mapping and filters. That buys direct access to the Spring ecosystem, including DiscoveryClient for route targets, and it means gateway logic can be unit tested like any other Spring component. It costs you the operational maturity and language neutrality of a dedicated proxy binary. Neither is strictly better; the deciding question is whether the gateway is part of your Spring application or infrastructure that outlives it.

Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-09-18. Recent releases are v5.0.3 on 2026-08-20, v5.0.2 and v4.3.5 both on 2026-06-11. The presence of a 4.3.x line alongside 5.0.x indicates that two release trains are being published, so an upgrade plan should name the train you are on rather than the project as a whole.

Upgrade cost is dominated by the framework baseline. Because the README states Java 17, Spring Framework 6 and Spring Boot 3, a major version bump here is entangled with a Spring Boot upgrade, and the two should be planned together. The README does not document a rollback procedure or a compatibility matrix for older Spring Boot lines, so verify that against the release notes before committing.

The licence is Apache-2.0, described in the README as non-restrictive. Contributions follow a standard GitHub process with a Developer Certificate of Origin: commits must carry a Signed-off-by trailer, and the README points to a Spring blog post titled "Hello DCO, Goodbye CLA" for the reasoning. If you fork and modify, the DCO requirement applies to contributions back, not to private use. This is a description of what the repository states, not legal advice.

Editorial conclusion

Adopt Spring Cloud Gateway when your services are already Spring Boot applications and you want routing, predicates and filters defined in the same programming model, with DiscoveryClient wiring for route targets. Do not adopt it if your edge needs a language-agnostic proxy with a mature plugin ecosystem, or if you cannot commit to the Spring Framework 6 and Java 17 baseline. Before writing routes, verify which stack your dependency pulls in: the repository now ships spring-cloud-starter-gateway-server-webflux and spring-cloud-starter-gateway-server-webmvc, and the README does not document a migration path between them.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. spring-cloud/spring-cloud-gateway on GitHub