What are GatewayFilter factories in Spring Cloud Gateway, and how do you configure one like AddRequestHeader on a route?
answer
- Per-route predicates + filters
- Named factories: AddRequestHeader, RewritePath, StripPrefix
- Shortcut syntax maps to shortcutFieldOrder
- Adds header to DOWNSTREAM request
- WebFlux/Netty, reactive
basics
~10 sThey are reusable filters you attach to a single route to change its request or response. For example, AddRequestHeader=X-Env,prod adds that header to every request forwarded through that route.
solid answer
~40 sIn Spring Cloud Gateway a route has predicates (when it matches) and filters (what to do with the matched request). GatewayFilter factories are the named, parameterized building blocks for those per-route filters. You configure them declaratively, usually in application.yml under spring.cloud.gateway.routes[].filters. Built-in examples include AddRequestHeader, RewritePath, StripPrefix, RedirectTo and SetStatus. Each factory reads its arguments (e.g. AddRequestHeader=X-Request-Env, prod) and produces a GatewayFilter that runs when the route matches. AddRequestHeader specifically adds a header to the request sent to the downstream service, not to the client's original view. Because filters are per-route, the same factory can be reused with different arguments on different routes, which keeps routing configuration declarative and composable.
code
kotlin · 10 lines// application.yml equivalent expressed via the Java/Kotlin route DSL
@Bean
fun routes(builder: RouteLocatorBuilder): RouteLocator =
builder.routes()
.route("users-route") { r ->
r.path("/api/users/**")
.filters { f -> f.addRequestHeader("X-Request-Env", "prod") }
.uri("http://users-service:8080")
}
.build()go deeper
Should know filters are per-route and AddRequestHeader adds a header to the forwarded request.
Should know shortcut vs expanded syntax and Add vs Set semantics.
Should relate factories to the GatewayFilter/predicate model and reactive stack.
Frames filters as declarative edge policy and knows the factory/shortcutFieldOrder mechanism.
**Spring Cloud Gateway** is an API gateway built on Spring WebFlux and Project Reactor (non-blocking, runs on Netty). It routes incoming requests to downstream services. A **route** has three parts: an id, a set of **predicates** (conditions like path, host, method that decide whether the route matches), and a set of **filters** (logic that mutates the request/response as it passes through). A **GatewayFilter factory** is a component that produces a `GatewayFilter` for one route. Each built-in factory is named `<Name>GatewayFilterFactory` and is referenced in config by its short name (`AddRequestHeader`, `RewritePath`, `StripPrefix`, `RedirectTo`, `SetStatus`, etc.). The factory pattern lets you parameterize the filter: you give it arguments and it returns a configured filter instance. **Typical YAML configuration:** ```yaml spring: cloud: gateway: routes: - id: users-route uri: http://users-service:8080 predicates: - Path=/api/users/** filters: - AddRequestHeader=X-Request-Env, prod ``` Here `AddRequestHeader=X-Request-Env, prod` means: for any request matching this route, add the header `X-Request-Env: prod` **to the request that is forwarded downstream**. This is the key semantic — it modifies the outbound (proxied) request, so the downstream service sees the header. The original client never set it and does not see it added to their own copy. **Shortcut vs full syntax.** The compact form `AddRequestHeader=X-Request-Env, prod` is a *shortcut*; the factory declares a `shortcutFieldOrder()` so positional args map to config fields. The equivalent expanded form is: ```yaml - name: AddRequestHeader args: name: X-Request-Env value: prod ``` **Per-route vs global.** GatewayFilter factories are per-route. A different mechanism, `GlobalFilter`, applies to every route (that is a separate concern and out of scope here). You can attach many filters to one route; they run in a chain. **When to use.** Use built-in GatewayFilter factories for common edge concerns without writing code: injecting headers for downstream services, rewriting/stripping path prefixes so the gateway's public path differs from the backend's internal path, issuing redirects, or overriding response status. **Gotchas.** AddRequestHeader *adds* (it does not replace) — a duplicate header can result if the client already sent one; use `SetRequestHeader` to overwrite. YAML values with commas or special characters may need quoting. The value supports property placeholders and, since it produces a request header, it affects only the proxied request.
- What is the difference between AddRequestHeader and SetRequestHeader?AddRequestHeader appends a header value (can create duplicates if one already exists); SetRequestHeader overwrites/replaces any existing value for that header name.
- Does AddRequestHeader modify the response the client receives?No. It modifies the request forwarded to the downstream service. For response headers you'd use AddResponseHeader.
- Thinking AddRequestHeader modifies the client's original request or the response
- Confusing per-route GatewayFilter factories with GlobalFilters
- Believing AddRequestHeader replaces an existing header (it appends)