Migrating from Spring Cloud Gateway MVC to Server Web MVC (2025.0.0+)

As of Spring Cloud version 2025.0.0, the Spring Cloud Gateway MVC project has been officially deprecated. It will be removed in future releases and has been replaced by Spring Cloud Gateway Server Web MVC.

If you’re maintaining a Spring Boot project using the Gateway MVC module, it’s important to migrate to the new server-webmvc module to ensure ongoing compatibility and access to future improvements. This guide walks through the steps required to perform the migration while preserving existing functionality.

1. Update Project Dependencies

First, update your Maven configuration to use the latest Spring Cloud BOM.

Add Spring Cloud dependency management

In your pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.cloud</groupId>
      <artifactId>spring-cloud-dependencies</artifactId>
      <version>2025.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Replace the deprecated module

Remove the old Gateway MVC dependency and replace it with the new Server Web MVC module:

<dependency>
  <groupId>org.springframework.cloud</groupId>
  <artifactId>spring-cloud-gateway-server-webmvc</artifactId>
</dependency>

2. Update application.yml Configuration

The configuration structure has changed in the new module. Specifically, the prefix for gateway settings is different, and some properties have been reorganized.

Route configuration changes

Previously, routes were defined under:

spring:
  cloud:
    gateway:
      mvc:
        routes:

This now becomes:

spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:

Example:

spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: example
              uri: http://example.com
              predicates:
                - Path=/example/**
              filters:
                - AddRequestHeader=X-Example-Header, ExampleValue

Make sure all your routes are refactored to match the new structure.

HTTP client configuration changes

In earlier versions, HTTP client settings were nested under the mvc namespace:

spring:
  cloud:
    gateway:
      mvc:
        http-client:
          connect-timeout: 5000
          read-timeout: 5000

With the new version, they are moved to the top-level gateway configuration:

spring:
  cloud:
    gateway:
      httpclient:
        connect-timeout: 5000
        read-timeout: 5000

Be sure to double-check all configuration keys, as some have been renamed or relocated.

Reference Documentation

For a complete and up-to-date list of supported configuration properties, refer to the official Spring Cloud Gateway documentation.

Conclusion

The deprecation of Spring Cloud Gateway MVC in version 2025.0.0 marks a shift toward a more unified and maintainable gateway module. Migrating to Spring Cloud Gateway Server Web MVC ensures your application remains compatible with future versions of Spring Cloud and benefits from continued support and improvements.

By updating your dependencies and adjusting your configuration, you can complete the migration smoothly without changing the core behavior of your gateway routes.