Running Spring Cloud Gateway on Traditional Servlet Containers: MVC Support Explained

Gateway does not support traditional Servlet containers

Spring Cloud Gateway needs to run on the provided Netty runtime. It cannot work in traditional Servlet containers nor when built as a WAR. WebFlux uses an asynchronous non‑blocking programming model, which requires understanding reactive programming concepts and may have a steep learning curve compared to traditional MVC Servlet.

If a traditional container such as Tomcat is introduced to

spring-cloud-gateway

, the following exception is thrown:

<code> 14 Caused by: org.springframework.boot.web.server.WebServerException: Unable to start embedded Tomcat
 15     at org.springframework.boot.web.embedded.tomcat.TomcatWebServer.initialize(TomcatWebServer.java:124) ~[spring-boot-2.1.6.RELEASE.jar:2.1.6.RELEASE]
 16     at org.springframework.boot.web.embedded.tomcat.TomcatWebServer.<init>(TomcatWebServer.java:86) ~[spring-boot-2.1.6.RELEASE.jar:2.1.6.RELEASE]
 17     at org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory.getTomcatWebServer(TomcatServletWebServerFactory.java:414) ~[spring-boot-2.1.6.RELEASE.jar:2.1.6.RELEASE]
 18     at org.springframework.boot.web.embedded.tomcat.TomcatServletWebServerFactory.getWebServer(TomcatServletWebServerFactory.java:178) ~[spring-boot-2.1.6.RELEASE.jar:2.1.6.RELEASE]
 19     at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.createWebServer(ServletWebServerApplicationContext.java:179) ~[spring-boot-2.1.6.RELEASE.jar:2.1.6.RELEASE]
 20     at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.onRefresh(ServletWebServerApplicationContext.java:152) ~[spring-boot-2.1.6.RELEASE.jar:2.1.6.RELEASE]
 21 ... 8 common frames omitted</code>

MVC Servlet support

In the Spring Cloud 2023 release (Spring Cloud Gateway 4.1), official support for MVC Servlet is provided, allowing Tomcat and other containers to replace Netty and using synchronous Servlet Filters instead of the complex asynchronous event‑stream programming style.

Quick start

springboot 3.2

spring cloud 2023

<code><dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway-mvc</artifactId>
</dependency>
</code>

Configure routing rules

All client requests to

127.0.0.1:8080

are forwarded to

pig4cloud.com

:

<code>spring:
  cloud:
    gateway:
      mvc:
        routes:
          - id: pig
            uri: https://pig4cloud.com
            predicates:
              - Path=/
</code>

Note: When using

gateway-mvc

, you must add the

mvc

level configuration; otherwise the rules are ineffective.

How to customize gateway filter

Open the Spring Cloud Gateway official site; the MVC support section provides limited reference material, but you can implement filters exactly as you would in a Spring MVC project.

Be sure to specify the order of custom filters; the execution order of Spring Cloud Gateway filters matches that of WebFlux filters.

Summary

Support for synchronous MVC in Spring Cloud Gateway has long been discussed in the community (originally Zuul 1.x was MVC‑based). With the official release of Java 21 and its virtual threads, synchronous MVC gains performance benefits. After adapting to Java 21, the official version will simplify gateway development and greatly enrich gateway applications.

PIG microservice now supports SpringBoot 3.2 and SpringCloud 2023 Source code: https://gitee.com/log4j/pig.git -b 2023