Documents proper order for Servlet Filtters.

Fixes gh-3244

docs/modules/ROOT/nav.adoc

@@ -109,6 +109,7 @@
 *** xref:spring-cloud-gateway-server-mvc/filters/setrequesthostheader.adoc[]
 *** xref:spring-cloud-gateway-server-mvc/filters/tokenrelay.adoc[]
 ** xref:spring-cloud-gateway-server-mvc/writing-custom-predicates-and-filters.adoc[]
+** xref:spring-cloud-gateway-server-mvc/working-with-servlets-and-filters.adoc[]
 
 // begin Gateway Proxy Exchange
 

docs/modules/ROOT/pages/spring-cloud-gateway-server-mvc/working-with-servlets-and-filters.adoc

@@ -0,0 +1,30 @@
+[[working-with-servlets-and-filters]]
+= Working with Servlets and Servlet Filters
+
+Spring Cloud Gateway Server MVC is built for Servlet-stack web applications built on the Servlet API and deployed to Servlet containers. If your applications uses Servlets or Servlet Filters you may need to take care in their ordering.
+
+Because of the way Servlet Containers handle request parameters, when a Spring WebMVC application receives a content type of `application/x-www-form-urlencoded`, Servlet containers combine those with query parameters into "request" parameters. A special `FormFilter` bean is included in Spring Cloud Gateway Server MVC to rebuild the form body for downstream applications. Any Servlet Filter that reads request parameters before the filter chain is run will need to be ordered *before* `FormFilter`. See the example below.
+
+.MyFilter.java
+[source,java]
+----
+import jakarta.servlet.Filter;
+import org.springframework.cloud.gateway.server.mvc.filter.FormFilter;
+import org.springframework.core.Ordered;
+
+class MyFilter implements Filter, Ordered {
+
+    @Override
+    public int getOrder() {
+        return FormFilter.FORM_FILTER_ORDER - 1;
+    }
+
+    @Override
+    public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain)
+            throws IOException, ServletException {
+        // ...
+        filterChain.doFilter(request, response);
+        // ...
+    }
+}
+----

spring-cloud-gateway-server-mvc/src/test/java/org/springframework/cloud/gateway/server/mvc/ServerMvcIntegrationTests.java

@@ -16,6 +16,7 @@
 
 package org.springframework.cloud.gateway.server.mvc;
 
+import java.io.IOException;
 import java.net.URI;
 import java.nio.charset.StandardCharsets;
 import java.time.Duration;
@@ -30,6 +31,12 @@ import com.github.benmanes.caffeine.cache.Caffeine;
 import io.github.bucket4j.caffeine.CaffeineProxyManager;
 import io.github.bucket4j.distributed.proxy.AsyncProxyManager;
 import io.github.bucket4j.distributed.remote.RemoteBucketState;
+import jakarta.servlet.Filter;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.ServletRequest;
+import jakarta.servlet.ServletResponse;
+import jakarta.servlet.http.HttpServletRequest;
 import org.apache.commons.logging.Log;
 import org.apache.commons.logging.LogFactory;
 import org.assertj.core.api.Assertions;
@@ -42,7 +49,9 @@ import org.springframework.boot.test.context.SpringBootTest;
 import org.springframework.boot.test.context.SpringBootTest.WebEnvironment;
 import org.springframework.boot.test.web.client.TestRestTemplate;
 import org.springframework.boot.test.web.server.LocalServerPort;
+import org.springframework.boot.web.servlet.FilterRegistrationBean;
 import org.springframework.cloud.gateway.server.mvc.common.MvcUtils;
+import org.springframework.cloud.gateway.server.mvc.filter.FormFilter;
 import org.springframework.cloud.gateway.server.mvc.filter.ForwardedRequestHeadersFilter;
 import org.springframework.cloud.gateway.server.mvc.filter.XForwardedRequestHeadersFilter;
 import org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates;
@@ -53,9 +62,11 @@ import org.springframework.cloud.gateway.server.mvc.test.TestLoadBalancerConfig;
 import org.springframework.cloud.gateway.server.mvc.test.client.TestRestClient;
 import org.springframework.cloud.loadbalancer.annotation.LoadBalancerClient;
 import org.springframework.context.annotation.Bean;
+import org.springframework.core.Ordered;
 import org.springframework.core.io.ClassPathResource;
 import org.springframework.http.HttpEntity;
 import org.springframework.http.HttpHeaders;
+import org.springframework.http.HttpMethod;
 import org.springframework.http.HttpStatus;
 import org.springframework.http.MediaType;
 import org.springframework.http.RequestEntity;
@@ -1278,6 +1289,12 @@ public class ServerMvcIntegrationTests {
 			// @formatter:on
 		}
 
+		@Bean
+		public FilterRegistrationBean myFilter() {
+			FilterRegistrationBean<MyFilter> reg = new FilterRegistrationBean<>(new MyFilter());
+			return reg;
+		}
+
 		private Predicate<Event> eventPredicate(String foo) {
 			return new Predicate<>() {
 				@Override
@@ -1294,6 +1311,38 @@ public class ServerMvcIntegrationTests {
 
 	}
 
+	private static class MyFilter implements Filter, Ordered {
+
+		@Override
+		public int getOrder() {
+			return FormFilter.FORM_FILTER_ORDER - 1;
+		}
+
+		@Override
+		public void doFilter(ServletRequest request, ServletResponse response, FilterChain filterChain)
+				throws IOException, ServletException {
+			if (isFormPost((HttpServletRequest) request)) {
+				// test for formUrlencodedWorks and
+				// https://github.com/spring-cloud/spring-cloud-gateway/issues/3244
+				assertThat(request.getParameter("foo")).isEqualTo("fooquery");
+				assertThat(request.getParameter("foo")).isEqualTo("fooquery");
+			}
+			filterChain.doFilter(request, response);
+
+			if (isFormPost((HttpServletRequest) request)) {
+				assertThat(request.getParameter("foo")).isEqualTo("fooquery");
+				assertThat(request.getParameter("foo")).isEqualTo("fooquery");
+			}
+		}
+
+		static boolean isFormPost(HttpServletRequest request) {
+			String contentType = request.getContentType();
+			return (contentType != null && contentType.contains(MediaType.APPLICATION_FORM_URLENCODED_VALUE)
+					&& HttpMethod.POST.matches(request.getMethod()));
+		}
+
+	}
+
 	protected record Hello(String message) {
 
 	}