Skip to content

rrezartprebreza/spring-boot-skills / skills/spring-boot-4/spring-cloud-gateway

spring-cloud-gateway

Verified

Use when building Spring Cloud Gateway 5 on Spring Boot 4, including WebFlux or Web MVC routes, edge authentication, trusted headers, rate limits, timeouts, and resilience. Do not use for ordinary outbound HTTP clients or domain orchestration.

FileKindSize
SKILL.mdskill md4.2 KB
agents/openai.yamlconfig204 B
examples/bad-routes.ymlconfig281 B
examples/good-routes.ymlconfig374 B
examples/good-webmvc-routes.ymlconfig284 B
---
name: spring-cloud-gateway
description: >
  Use when building Spring Cloud Gateway 5 on Spring Boot 4, including WebFlux or Web MVC routes,
  edge authentication, trusted headers, rate limits, timeouts, and resilience. Do not use for
  ordinary outbound HTTP clients or domain orchestration.
---

# Spring Cloud Gateway 5

Keep the gateway an edge adapter. Do not move domain workflows into filters.

## Compatibility and dependencies

- Use the latest Spring Cloud `2025.1.x` release train for Spring Boot 4.
- Boot 4.1 support starts with Spring Cloud `2025.1.2`.
- Import `spring-cloud-dependencies` as a BOM and omit versions from individual Cloud dependencies.
- Choose exactly one gateway runtime.

```xml
<!-- Reactive Netty gateway -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-gateway-server-webflux</artifactId>
</dependency>

<!-- OR servlet gateway: spring-cloud-starter-gateway-server-webmvc -->
```

Do not use the old `spring-cloud-starter-gateway` coordinate or force a Boot 3 release train onto
Boot 4. WebFlux requires Reactor Netty and cannot run as a traditional servlet WAR; Web MVC uses a
servlet runtime and WebMvc.fn.

## Gateway 5 configuration namespaces

Gateway 5 separates server implementations in configuration:

- WebFlux: `spring.cloud.gateway.server.webflux.*`
- Web MVC: `spring.cloud.gateway.server.webmvc.*`

```yaml
spring:
  cloud:
    gateway:
      server:
        webflux:
          httpclient:
            connect-timeout: 2000
            response-timeout: 5s
          routes:
            - id: orders-api
              uri: http://orders.internal
              predicates:
                - Path=/api/orders/**
              filters:
                - RemoveRequestHeader=X-User-Id
```

The Boot 3-era `spring.cloud.gateway.routes` and `spring.cloud.gateway.httpclient` paths do not bind
to Gateway 5's WebFlux server properties.

## Route and security rules

- Use stable route IDs and explicit predicates.
- Remove client-provided forwarding, identity, and internal headers before creating trusted values.
- Keep path and host rewriting visible and covered by tests.
- Authenticate at the edge and authorize again in downstream services.
- Relay tokens only to services with the intended audience.
- Rate-limit by authenticated identity or a verified API key, not an untrusted address header.
- Set global connection and response timeouts with narrow route overrides.
- Retry only proven idempotent operations and only before response commitment.
- Keep fallbacks bounded and expose sustained upstream failure.

## Testing and operations

- Test predicates, filters, trusted headers, CORS, timeouts, body limits, and status mapping.
- Use a controlled upstream server rather than mocking gateway internals.
- Record route ID, outcome, latency, and upstream failure with bounded metric tags.
- Test each selected runtime with its matching Spring Cloud Gateway test support.

## Examples

- `examples/good-routes.yml` shows Gateway 5 WebFlux configuration.
- `examples/good-webmvc-routes.yml` shows Gateway 5 Web MVC configuration.
- `examples/bad-routes.yml` preserves the stale configuration as a warning.

## Official sources

- Spring Cloud compatibility: https://spring.io/projects/spring-cloud/
- Gateway WebFlux starter: https://docs.spring.io/spring-cloud-gateway/reference/spring-cloud-gateway-server-webflux/starter.html
- Gateway Web MVC starter: https://docs.spring.io/spring-cloud-gateway/reference/spring-cloud-gateway-server-webmvc/starter.html
- Gateway configuration properties: https://docs.spring.io/spring-cloud-gateway/reference/configprops.html

## Gotchas

- Agent uses `spring.cloud.gateway.routes` on Gateway 5 - use the server-specific namespace.
- Agent uses `spring-cloud-starter-gateway` on Boot 4 - select the WebFlux or Web MVC server starter.
- Agent selects a Cloud train without checking the exact Boot line - use the compatibility matrix.
- Agent trusts a public identity header - derive identity after authentication.
- Agent retries POST requests automatically - retry only proven idempotent operations.
- Agent puts business orchestration in filters - keep domain logic downstream.
- Agent omits response timeouts - stalled upstreams can exhaust resources.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall