A Guide to Spring Cloud Gateway

Posted on 2025-08-04 Edited on 2025-08-16 In Microservices , Spring Cloud

Spring Cloud Gateway aims to provide a simple, yet effective way to route to APIs and provide cross-cutting concerns to them, such as security, monitoring/metrics, and resiliency.

In this post, I will cover common uses of Spring Cloud Gateway. This post is based on Java 21, Spring Boot 3.5.3, and Spring Cloud 2025.0.0.

Next, I will use a simple example application to show it in action.

Spring Cloud Gateway Server WebFlux

1. Create Project and Add Dependencies

Using Gradle

1. Create a Java application with the gradle init command.

$ mkdir spring-cloud-gateway && cd spring-cloud-gateway
$ gradle --configuration-cache \
    init --use-defaults \
    --type java-application \
    --package com.taogen.springcloud

2. Gradle configuration

app/build.gradle.kts

plugins {
    java
    id("org.springframework.boot") version "3.5.3"
    // Use the Spring Dependency Management plugin to manage Spring Cloud dependencies.
    id("io.spring.dependency-management") version "1.1.7"
}

extra["springCloudVersion"] = "2025.0.0"

java {
    toolchain {
        languageVersion = JavaLanguageVersion.of(21)
    }
}

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.cloud:spring-cloud-starter-gateway-server-webflux")
    implementation("org.springframework.boot:spring-boot-starter-webflux")
    implementation("org.springframework.cloud:spring-cloud-starter-netflix-eureka-client")
    implementation("org.springframework.boot:spring-boot-starter-actuator")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
    testRuntimeOnly("org.junit.platform:junit-platform-launcher")
}

dependencyManagement {
    imports {
        mavenBom("org.springframework.cloud:spring-cloud-dependencies:${property("springCloudVersion")}")
    }
}

tasks.withType<Test> {
    useJUnitPlatform()
}

Using Maven

1. Create a Java application with mvn command.

$ mvn -B archetype:generate \
    -DgroupId=com.taogen.springcloud \
    -DartifactId=spring-cloud-gateway \
    -DarchetypeArtifactId=maven-archetype-quickstart \
    -DarchetypeVersion=1.5

2. Maven configuration

pom.xml

<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.taogen.springcloud</groupId>
    <artifactId>spring-cloud-gateway</artifactId>
    <version>1.0-SNAPSHOT</version>

    <name>spring-cloud-gateway</name>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.release>21</maven.compiler.release>
        <java.version>21</java.version>
        <spring-boot.version>3.5.3</spring-boot.version>
        <spring-cloud.version>2025.0.0</spring-cloud.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webflux</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-starter-netflix-eureka-client</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.cloud</groupId>
                <artifactId>spring-cloud-dependencies</artifactId>
                <version>${spring-cloud.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Using Spring Initializr

Go to https://start.spring.io/

Project Metadata

Group: com.taogen.springcloud
Artifact: spring-cloud-gateway

Add dependencies

Reactive Gateway
Eureka Discovery Client
Spring Reactive Web
Spring Boot Actuator

2. Spring Configuration

The spring configuration mainly contains Eureka client configurations and Spring Cloud Gateway configurations.

application.yml

# Eureka client
eureka:
  instance:
    preferIpAddress: true
    instanceId: ${spring.application.name}:${vcap.application.instance_id:${spring.application.instance_id:${random.value}}}
  client:
    registerWithEureka: true
    fetchRegistry: true
    serviceUrl:
      defaultZone: http://localhost:8761/eureka/
    healthcheck:
      enabled: true

server:
  port: 8072

# Actuator
management:
  endpoint:
    gateway:
      access: read_only
  endpoints:
    web:
      exposure:
        include: health,info,beans,gateway

# Spring Cloud Gateway
# Automated mapping of routes via service discovery
spring:
  application:
    name: my-spring-cloud-gateway
  cloud:
    gateway:
      server:
        webflux:
          discovery:
            locator:
              enabled: true
              lower-case-service-id: true

3. The Application

1. Spring Boot application entry point

1. SpringCloudGatewayApplication.java

package com.taogen.springcloud;  
  
import org.springframework.boot.SpringApplication;  
import org.springframework.boot.autoconfigure.SpringBootApplication;  
  
@SpringBootApplication  
public class SpringCloudGatewayApplication {  
    public static void main(String[] args) {  
        SpringApplication.run(SpringCloudGatewayApplication.class, args);  
    }  
}

2. RestTemplate config

RestTemplateConfig.java

package com.taogen.springcloud;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestTemplate;

@Configuration
public class RestTemplateConfig {
    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

3. Request Eureka client services through Spring Cloud Gateway

MyController.java

package com.taogen.springcloud;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.cloud.client.discovery.DiscoveryClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.client.RestTemplate;

@RestController
@RequestMapping("/")
public class MyController {
    @Autowired
    private DiscoveryClient discoveryClient;

    @Autowired
    private RestTemplate restTemplate;

    @GetMapping("/callEurekaClientThroughGateway")
    public String callEurekaClientThroughGateway() {
        // the same with the value of spring.application.name in Spring Coud Gateway application
        String serviceId = "my-spring-cloud-gateway";
        String serviceUrl = discoveryClient.getInstances(serviceId).get(0).getUri().toString();
        String response = restTemplate.getForObject(serviceUrl + "/eureka-client-1/greeting", String.class);
        return response;
    }
}

Eureka client service API URL: http://{gateway-service-id}/{eureka-service-id}/{endpoint}. For example, http://my-spring-cloud-gateway/eureka-client-1/greeting.

4. Start and Verification

Starting Spring Cloud Eureka Client

Running the main() method in the SpringCloudGatewayApplication to start the Spring Cloud Gateway server.

Verification

Request the /callEurekaClientThroughGateway endpoint to see the result of requesting Eureka client services through Spring Cloud Gateway.

5. Gateway Actuator API

The /gateway actuator endpoint lets you monitor and interact with a Spring Cloud Gateway application.

To enable Gateway Actuator API, you need to add the following configuration:

application.properties

management.endpoint.gateway.access=read_only
management.endpoints.web.exposure.include=gateway

Or application.yml

management:
  endpoint:
    gateway:
      access: read_only
  endpoints:
    web:
      exposure:
        include: gateway

Open http://localhost:8072/actuator/gateway to view Gateway Actuator endpoints.

References

[1] Spring Microservices in Action, Second Edition

[2] Spring Cloud Gateway Documentation