This version is still in development and is not considered stable yet. For the latest stable version, please use Spring Cloud Gateway 5.0.3!

Gateway Request Predicates

Spring Cloud Gateway MVC matches routes as part of the Spring WebMvc.fn HandlerMapping infrastructure. Spring Cloud Gateway reuses many RequestPredicate implementations from WebMvc.fn and includes other custom RequestPredicate implementations All of these predicates match on different attributes of the HTTP request. You can combine multiple route predicate factories with the RequestPredicate.and() and RequestPredicate.or() methods.

The After Request Predicate

The After route predicate factory takes one parameter, a datetime (which is a java ZonedDateTime). This predicate matches requests that happen after the specified datetime. The datetime can be specified as a ZonedDateTime string or as epoch milliseconds. The following example configures an after route predicate:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: after_route
              uri: https://example.org
              predicates:
              - After=2017-01-20T17:42:47.789-07:00[America/Denver]

The datetime can also be specified as epoch milliseconds:

application.yml
spring:
  cloud:
    gateway:
      mvc:
        routes:
        - id: after_route
          uri: https://example.org
          predicates:
          - After=1484968967789
GatewaySampleApplication.java
import java.time.ZonedDateTime;
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.after;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsAfter() {
        return route("after_route")
            .route(after(ZonedDateTime.parse("2017-01-20T17:42:47.789-07:00[America/Denver]")), http())
            .before(uri("https://example.org"))
            .build();
    }
}

This route matches any request made after Jan 20, 2017 17:42 Mountain Time (Denver).

The Before Request Predicate

The Before route predicate factory takes one parameter, a datetime (which is a java ZonedDateTime). This predicate matches requests that happen before the specified datetime. The datetime can be specified as a ZonedDateTime string or as epoch milliseconds. The following example configures a before route predicate:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: before_route
              uri: https://example.org
              predicates:
              - Before=2017-01-20T17:42:47.789-07:00[America/Denver]

The datetime can also be specified as epoch milliseconds:

application.yml
spring:
  cloud:
    gateway:
      mvc:
        routes:
        - id: before_route
          uri: https://example.org
          predicates:
          - Before=1484968967789
GatewaySampleApplication.java
import java.time.ZonedDateTime;
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.before;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsBefore() {
        return route("before_route")
            .route(before(ZonedDateTime.parse("2017-01-20T17:42:47.789-07:00[America/Denver]")), http()
            .before(uri("https://example.org"))
            .build();
    }
}

This route matches any request made before Jan 20, 2017 17:42 Mountain Time (Denver).

The Between Request Predicate

The Between route predicate factory takes two parameters, datetime1 and datetime2 which are java ZonedDateTime objects. This predicate matches requests that happen after datetime1 and before datetime2. The datetime2 parameter must be after datetime1. The datetimes can be specified as ZonedDateTime strings or as epoch milliseconds. The following example configures a between route predicate:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: between_route
              uri: https://example.org
              predicates:
              - Between=2017-01-20T17:42:47.789-07:00[America/Denver], 2017-01-21T17:42:47.789-07:00[America/Denver]

The datetimes can also be specified as epoch milliseconds:

application.yml
spring:
  cloud:
    gateway:
      mvc:
        routes:
        - id: between_route
          uri: https://example.org
          predicates:
          - Between=1484968967789, 1485055367789
GatewaySampleApplication.java
import java.time.ZonedDateTime;
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.between;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsBetween() {
        return route("between_route")
            .route(between(ZonedDateTime.parse("2017-01-20T17:42:47.789-07:00[America/Denver]"),
                ZonedDateTime.parse("2017-01-21T17:42:47.789-07:00[America/Denver]")), http())
            .before(uri("https://example.org"))
            .build();
    }
}

This route matches any request made after Jan 20, 2017 17:42 Mountain Time (Denver) and before Jan 21, 2017 17:42 Mountain Time (Denver). This could be useful for maintenance windows.

The Cookie route predicate factory takes two parameters, the cookie name and a regexp (which is a Java regular expression). This predicate matches cookies that have the given name and whose values match the regular expression. The following example configures a cookie route predicate factory:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: cookie_route
              uri: https://example.org
              predicates:
              - Cookie=chocolate, ch.p
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.cookie;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsCookie() {
        return route("cookie_route")
            .route(cookie("chocolate", "ch.p"), http())
            .before(uri("https://example.org"))
            .build();
    }
}

This route matches requests that have a cookie named chocolate whose value matches the ch.p regular expression.

The Header Request Predicate

The Header route predicate factory takes two parameters, the header and a regexp (which is a Java regular expression). This predicate matches with a header that has the given name whose value matches the regular expression. The following example configures a header route predicate:

application.yml
spring:
  cloud:
    server:
      webmvc:
        routes:
            - id: header_route
              uri: https://example.org
              predicates:
              - Header=X-Request-Id, \d+
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.header;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsHeader() {
        return route("header_route")
            .route(header("X-Request-Id", "\\d+"), http())
            .before(uri("https://example.org"))
            .build();
    }
}

This route matches if the request has a header named X-Request-Id whose value matches the \d+ regular expression (that is, it has a value of one or more digits).

The Host Request Predicate

The Host route predicate factory takes one parameter: a list of host name patterns. The pattern is an Ant-style pattern with . as the separator. This predicates matches the Host header that matches the pattern. The following example configures a host route predicate:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: host_route
              uri: https://example.org
              predicates:
              - Host=**.somehost.org,**.anotherhost.org
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.host;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsHost() {
        return route("host_route")
            .route(host("**.somehost.org", "**.anotherhost.org"), http())
            .before(uri("https://example.org"))
            .build();
    }
}

URI template variables (such as {sub}.myhost.org) are supported as well.

This route matches if the request has a Host header with a value of www.somehost.org or beta.somehost.org or www.anotherhost.org.

This predicate extracts the URI template variables (such as sub, defined in the preceding example) as a map of names and values and places it in the ServerRequest.attributes() with a key defined in MvcUtils.URI_TEMPLATE_VARIABLES_ATTRIBUTE. Those values are then available for use by Gateway Handler Filter Functions.

The Method Request Predicate

The Method Request Predicate takes a methods argument which is one or more parameters: the HTTP methods to match. The following example configures a method route predicate:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: method_route
              uri: https://example.org
              predicates:
              - Method=GET,POST
GatewaySampleApplication.java
import org.springframework.http.HttpMethod;
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.method;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsMethod() {
        return route("method_route")
            .route(method(HttpMethod.GET, HttpMethod.POST), http())
            .before(uri("https://example.org"))
            .build();
    }
}

This route matches if the request method was a GET or a POST.

GatewayRequestPredicates.method is a simple alias for RequestPredicates.methods. Also, the RouterFunctions.Builder API includes convenience methods that combine the method and path RequestPredicates.

GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsMethodAndPath() {
        return route("method_and_path_route")
            .GET("/mypath", http())
            .before(uri("https://example.org"))
            .build();
    }
}

This route matches if the request method was a GET and the path was /mypath.

The Path Request Predicate

The Path Request Predicate takes two parameters: a list of Spring PathPattern patterns. This Request Predicate uses RequestPredicates.path() as the underlying implementation. The following example configures a path route predicate:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: path_route
              uri: https://example.org
              predicates:
              - Path=/red/{segment},/blue/{segment}
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.path;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsPath() {
        return route("path_route")
            .route(path("/red/{segment}", "/blue/{segment}"), http())
            .before(uri("https://example.org"))
            .build();
    }
}

This route matches if the request path was, for example: /red/1 or /red/1/ or /red/blue or /blue/green.

This predicate extracts the URI template variables (such as segment, defined in the preceding example) as a map of names and values and places it in the ServerRequest.attributes() with a key defined in RouterFunctions.URI_TEMPLATE_VARIABLES_ATTRIBUTE. Those values are then available for use by Gateway Handler Filter Functions.

A utility method (called get) is available to make access to these variables easier. The following example shows how to use the get method:

Map<String, Object> uriVariables = MvcUtils.getUriTemplateVariables(request);

String segment = uriVariables.get("segment");

The Query Request Predicate

The Query route predicate factory takes two parameters: a required param and an optional regexp (which is a Java regular expression). The following example configures a query route predicate:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: query_route
              uri: https://example.org
              predicates:
              - Query=green
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.query;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsQuery() {
        return route("query_route")
            .route(query("green"), http())
            .before(uri("https://example.org"))
            .build();
    }
}

The preceding route matches if the request contained a green query parameter.

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: query_route
              uri: https://example.org
              predicates:
              - Query=red, gree.
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.query;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctionsQuery() {
        return route("query_route")
            .route(query("red", "gree."), http())
            .before(uri("https://example.org"))
            .build();
    }
}

The preceding route matches if the request contained a red query parameter whose value matched the gree. regexp, so green and greet would match.

The Weight Request Predicate

The Weight route predicate factory takes two arguments: group and weight (an int). The weights are calculated per group. The following example configures a weight route predicate:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
            - id: weight_high
              uri: https://weighthigh.org
              predicates:
              - Weight=group1, 8
            - id: weight_low
              uri: https://weightlow.org
              predicates:
              - Weight=group1, 2
GatewaySampleApplication.java
import static org.springframework.cloud.gateway.server.mvc.filter.BeforeFilterFunctions.uri;
import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.path;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.weight;

@Configuration
class RouteConfiguration {

	@Bean
	public RouterFunction<ServerResponse> gatewayRouterFunctionsWeights() {
        return route("weight_high")
                .route(weight("group1", 8).and(path("/**")), http())
                .before(uri("https://weighthigh.org"))
                .build().and(
            route("weight_low")
                .route(weight("group1", 2).and(path("/**")), http())
                .before(uri("https://weightlow.org"))
                .build());
	}
}

This route would forward ~80% of traffic to weighthigh.org and ~20% of traffic to weightlow.org.

The Version Request Predicate

The version predicate matches requests based on the API version extracted from the incoming request. The version is resolved and parsed by the ApiVersionStrategy that is configured through Spring Framework’s API versioning support (spring.mvc.apiversion.*).

Configuring the API Version Strategy

Before using the version predicate you must configure at least one version resolver so that Spring (and Gateway MVC) knows how to extract the version from each incoming request. The following example configures version resolution from an HTTP header, a query parameter, and an application/json media-type parameter:

application.yml
spring:
  mvc:
    apiversion:
      use:
        header: X-API-Version          # extract version from this header
        query-parameter: apiVersion    # or from this query parameter
        media-type-parameter:          # or from the named media-type parameter
          "[application/json]": version
      required: false                  # allow requests without an explicit version

To extract the version from a path segment instead, set path-segment to the zero-based index of the segment that carries the version:

application.yml
spring:
  mvc:
    apiversion:
      use:
        path-segment: 1    # /v1/users → version = "1"

Using the Version Predicate

The predicate accepts a single version argument and supports two forms:

  • Fixed version — the route matches only requests whose resolved version equals the given version exactly.

  • Baseline version (version+) — the route matches requests whose resolved version is greater than or equal to the given version.

The following example configures a fixed-version route predicate:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
          - id: version_13_route
            uri: https://example.org
            predicates:
            - Path=/api/**
            - Version=1.3

This route matches only requests that carry exactly version 1.3.

The following example uses a baseline version:

application.yml
spring:
  cloud:
    gateway:
      server:
        webmvc:
          routes:
          - id: version_11_plus_route
            uri: https://example.org
            predicates:
            - Path=/api/**
            - Version=1.1+

This route matches requests with version 1.1 or any later version (for example 1.2, 1.5, or 2.0). A baseline version lets a single route continue to serve requests across multiple API versions until a breaking change makes a new route necessary.

The predicate can also be used in the Java DSL with GatewayRequestPredicates.version(String):

import static org.springframework.cloud.gateway.server.mvc.handler.GatewayRouterFunctions.route;
import static org.springframework.cloud.gateway.server.mvc.handler.HandlerFunctions.http;
import static org.springframework.cloud.gateway.server.mvc.predicate.GatewayRequestPredicates.version;

@Configuration
class RouteConfiguration {

    @Bean
    public RouterFunction<ServerResponse> gatewayRouterFunctions() {
        return route("version_13_route")
            .route(version("1.3"), http())
            .before(uri("https://example.org"))
            .build();
    }
}
If no ApiVersionStrategy bean is present (that is, no spring.mvc.apiversion.use.* property is set), the version predicate always passes — any request without a resolved version is treated as matching.