Framework
spring-cloud/spring-cloud-gateway avatar
spring-cloud/spring-cloud-gateway

Spring Cloud Gateway: route matching inside Spring Handler Mapping

An API Gateway built on Spring Framework and Spring Boot providing routing and more.

4,920 stars3,485 forksJavaApache-2.0

At a glance

What is it?
Spring Cloud Gateway is a Spring Boot API gateway whose routing is part of the handler mapping rather than a servlet filter, and whose repository is mostly build instructions for contributors. Here is what the module layout tells you, what the routing features actually do, and which build step people forget.
Who is it for?
Use it if your services are Spring based and you want routing, per route filters and circuit breaking in one place, with routes coming from configuration, the API, or a DiscoveryClient. Do not pick a 5.1.0 pre-release for production work: v5.1.0-RC1 is dated 2026-10-23, the same day as v5.0.4 on the patch line.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 3 days ago.
What is it written in?
Mainly Java, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • spring-cloud/spring-cloud-gateway4,920 ★ · +12
Star history
Repository2026-09-232026-11-15
spring-cloud/spring-cloud-gateway4.9k4.9k

12 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

README.adoc is generated, so edits belong in src/main/asciidoc

The first thing the file tells you is that you should not edit it. The header says DO NOT EDIT THIS FILE, IT WAS GENERATED, warns that manual changes are lost when it is generated again, and points contributors at the files in the src/main/asciidoc/ directory instead. The documentation section explains the round trip: the spring-cloud-build module has a docs profile that builds asciidoc sources with Antora from modules/ROOT/, finds docs/src/main/asciidoc/README.adoc, loads its includes without parsing or rendering them, and copies the result to the project root. After a Maven build the change appears as a modified README.adoc for you to commit. So a documentation fix that only touches README.adoc disappears at the next regeneration.

The spring Maven profile is not optional for a local build

Spring Cloud projects need the spring Maven profile active, because that profile carries the repository declarations for spring milestone and snapshot artifacts. Skip it and dependency resolution fails, or in an IDE you get a screen full of POM errors that look like a broken checkout. The README puts it plainly: set the profile active in your IDE or you may experience build errors. It matters most when you install Maven yourself instead of using the wrapper. The wrapper handles it, but a local Maven of 3.3.3 or newer running in place of ./mvnw may need -P spring added if your settings do not declare those repositories. Older m2e releases do not support Maven 3.3 either, so the profile has to be selected inside Eclipse as well.

Route matching lives in the handler mapping, not in a filter

The routing design decision is stated in one feature line: route matching is built into Spring Handler Mapping. Matching looks at the HTTP request itself, with Path, Method, Header and Host named as the criteria, and filters are scoped to the route that matched, so a filter only runs on traffic its own route selected. Those filters can modify both directions of the call: add or remove headers, add or remove parameters, rewrite the path, set the path, or act as a circuit breaker. Routes can come from the API or from configuration, and Spring Cloud's DiscoveryClient can supply them from service registration.

webflux and webmvc ship as parallel module sets

The top level directory tells you the gateway is maintained in two stacks rather than one. There is spring-cloud-gateway-server alongside spring-cloud-gateway-server-webflux and spring-cloud-gateway-server-webmvc, a proxyexchange module for each of those two, and a matching starter: spring-cloud-starter-gateway-server-webflux and spring-cloud-starter-gateway-server-webmvc. Around them sit spring-cloud-gateway-dependencies for version alignment, spring-cloud-gateway-integration-tests, and spring-cloud-gateway-sample. The practical consequence is that the reactive or servlet choice is made when you add a dependency, not later at runtime. Reading the sample module is the fastest way to see which starter belongs with the stack you already run.

JDK 17 is the floor, and 5.1.0 is still a milestone

The build needs JDK 17, and the feature list pins the stack above that: Java 17, Spring Framework 6, Spring Boot 3. Cloning and running the wrapper is the documented path.

bash
./mvnw install

The release tags show where the project actually is. v5.1.0-RC1 and v5.0.4 were published on 2026-10-23, after v5.1.0-M1 on 2026-09-24. An RC1 suffix means the 5.1.0 line is still a pre-release, so a production dependency belongs on the 5.0.x patch line unless you intend to test pre-release behaviour. The default branch is main and the last push is dated 2026-10-26.

Tests that need Redis assume a Docker you started yourself

The build instructions are honest about environment requirements. Projects that need middleware for testing, Redis being the example named, expect a local Docker instance installed and running before the tests start. That is a failure mode worth recognising: a red test in one of those modules can mean no container rather than broken code. The memory advice in the same section is dated, since it suggests setting MAVEN_OPTS to a value like -Xmx512m -XX:MaxPermSize=128m, and MaxPermSize is not an option current JVMs honour. The project tries to cover this in the .mvn configuration and asks you to raise a ticket if a build still fails on memory, so the setting belongs in source control rather than in your shell profile.

Contributions need a Signed-off-by trailer, not a CLA

Every commit must carry a Signed-off-by trailer at the end of the message, which is the Developer Certificate of Origin, and the project links a blog post titled Hello DCO, Goodbye CLA about moving to that model. A pull request without the trailer cannot merge, which is the one contribution rule with no workaround. The rest is convention: use the Spring Framework code format, importing eclipse-code-formatter.xml from Spring Cloud Build, or the Eclipse Code Formatter Plugin if you are in IntelliJ. New .java files need a simple Javadoc class comment with at least an @author tag, preferably a paragraph on what the class does, and the ASF license header copied from existing files. Issues are tracked on the tracker and pull requests merge into main.

The root carries a settings.xml and two LICENSE files

A few root files explain build friction before you hit it. .settings.xml is checked in, and .sdkmanrc is the file SDKMAN reads to select a JDK version. release-train-settings.xml sits beside pom.xml, and by its name ties this module to the scheduled Spring Cloud release train. There are also two licence files, LICENSE and LICENSE.txt, and the contributing section states the project is released under Apache 2.0. Generating Eclipse metadata without the m2e plugin takes one command.

bash
./mvnw eclipse:eclipse

Afterwards you import them through import existing projects in the file menu.

Editorial conclusion

Use it if your services are Spring based and you want routing, per route filters and circuit breaking in one place, with routes coming from configuration, the API, or a DiscoveryClient. Do not pick a 5.1.0 pre-release for production work: v5.1.0-RC1 is dated 2026-10-23, the same day as v5.0.4 on the patch line. Before your first clone, install JDK 17, keep the spring Maven profile active or your dependency resolution will fail, and start a local Docker if the module you touch needs Redis for its tests. And if you plan to edit the README, change the asciidoc sources instead, since README.adoc is generated and overwritten.

Frequently asked questions

What is Spring Cloud Gateway and what does it do?

It is an API gateway built on Spring Framework and Spring Boot that provides routing, with route matching built into Spring Handler Mapping and filters scoped to the route that matched.

What criteria does Spring Cloud Gateway match a route on?

The feature list names Path, Method, Header and Host as the request criteria, and says filters are scoped to the matching route, so a filter only runs on traffic that route selected.

What is spring-cloud-gateway-server-webflux in this project?

It is the reactive half of a parallel module set: spring-cloud-gateway-server-webflux and spring-cloud-gateway-server-webmvc each have a proxyexchange module and a starter, and the repository also holds a dependencies module, integration tests, and a sample.

How do I build Spring Cloud Gateway from source?

Install JDK 17, clone, and run ./mvnw install. Installing Maven 3.3.3 or newer yourself and using mvn in place of ./mvnw also works, and you may need -P spring if your settings do not declare the spring pre-release repositories.

How do I test Spring Cloud Gateway?

Tests run through the Maven build, and the projects that need middleware such as Redis expect a local Docker instance installed and running. Coverage for the main branch is reported through Codecov, and the build status comes from the Actions Build workflow.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/spring-cloud-spring-cloud-gateway.svg)](https://hysenlabs.com/projects/spring-cloud-spring-cloud-gateway)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/spring-cloud-spring-cloud-gateway.svg)](https://hysenlabs.com/projects/spring-cloud-spring-cloud-gateway)

Was this useful?