Mastering Spring Cloud Gateway Filters: Add Header, Parameter, Retry, and More

Environment: Spring Boot 2.3.7 + Spring Cloud Hoxton.SR9. Spring Cloud Gateway provides route‑level filters that can modify incoming HTTP requests or outgoing responses.

AddRequestHeader filter

Adds a header to the request sent to the downstream service. Example configuration:

spring:
  cloud:
    gateway:
      enabled: true
      discovery:
        locator:
          enabled: true
          lowerCaseServiceId: true
      routes:
        - id: AddRequestHeader_filter
          uri: http://localhost:20001
          predicates:
            - Path=/api/{user}
          filters:
            - AddRequestHeader=access-token,123456789

Calling http://localhost:20001/api/xxx adds the header access-token: 123456789. The downstream controller prints the header value.

AddRequestParameter filter

Appends a query parameter to the request forwarded to the downstream service.

spring:
  cloud:
    gateway:
      enabled: true
      discovery:
        locator:
          enabled: true
          lowerCaseServiceId: true
      routes:
        - id: add_request_parameter_route
          uri: http://localhost:20001
          predicates:
            - Path=/api/query
          filters:
            - AddRequestParameter=username,admin

The target service receives the parameter username=admin and returns query admin.

AddResponseHeader filter

Injects a header into the HTTP response returned to the client.

spring:
  cloud:
    gateway:
      enabled: true
      discovery:
        locator:
          enabled: true
          lowerCaseServiceId: true
      routes:
        - id: add_response_header_route
          uri: http://localhost:20001
          predicates:
            - Path=/api/query
          filters:
            - AddResponseHeader=server-id,nginx-001

PrefixPath filter

Prepends a static prefix to the original request path before forwarding.

spring:
  cloud:
    gateway:
      enabled: true
      discovery:
        locator:
          enabled: true
          lowerCaseServiceId: true
      routes:
        - id: prefixpath_route
          uri: http://localhost:20001
          predicates:
            - Path=/api-1/**
          filters:
            - PrefixPath=/api-1
            - StripPrefix=2

Without StripPrefix, a request to http://xxx/api-1/api-1/api/query would be forwarded to a non‑existent path; StripPrefix=2 removes the extra segments.

StripPrefix filter

Removes a specified number of path segments before routing.

spring:
  cloud:
    gateway:
      enabled: true
      discovery:
        locator:
          enabled: true
          lowerCaseServiceId: true
      routes:
        - id: prefixpath_route
          uri: http://localhost:20001
          predicates:
            - Path=/api-1/**
          filters:
            - StripPrefix=1

Request http://xxx/api-1/api/query becomes http://xxx/api/query after stripping one segment.

Retry filter

Retries failed requests based on status codes, HTTP methods, or exceptions.

spring:
  cloud:
    gateway:
      enabled: true
      discovery:
        locator:
          enabled: true
          lowerCaseServiceId: true
      routes:
        - id: retry_test
          uri: http://localhost:20001
          predicates:
            - Path=/api-1/**
          filters:
            - StripPrefix=1
            - name: Retry
              args:
                retries: 3
                statuses: INTERNAL_SERVER_ERROR
                methods: GET,POST

The filter retries up to three times for 500 errors on GET or POST requests. Example controller throws an exception when username=dead, triggering the retry logic.

RedirectTo filter

Redirects the original request to a specified URL.

spring:
  cloud:
    gateway:
      enabled: true
      discovery:
        locator:
          enabled: true
          lowerCaseServiceId: true
      routes:
        - id: prefixpath_route
          uri: http://localhost:20001
          predicates:
            - Path=/api-1/**
          filters:
            - RedirectTo=302,http://localhost:20001/api/query

A request matching the predicate is redirected to http://localhost:20001/api/query.

Default filters

Applies a set of filters to all routes automatically.

spring:
  cloud:
    gateway:
      enabled: true
      discovery:
        locator:
          enabled: true
          lowerCaseServiceId: true
      default-filters:
        - PrefixPath=/api-1
        - AddRequestHeader=access-token,123

All routes will have the /api-1 prefix and the access-token:123 header added.

The configurations above cover the most commonly used built‑in filters in Spring Cloud Gateway.