# Spring Cloud Gateway

> Use when building or changing a Spring Cloud Gateway on Spring Boot 3. Covers route design, authentication, header hygiene, rate limiting, retries, timeouts, observability, and testing.

- Skill: `rrezartprebreza/spring-cloud-gateway` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add rrezartprebreza/spring-cloud-gateway`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rrezartprebreza/spring-cloud-gateway/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: rrezartprebreza (https://skillmd.com/u/rrezartprebreza)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rrezartprebreza/spring-cloud-gateway

---


# Spring Cloud Gateway

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

## Compatibility first

- Select the Spring Cloud release train compatible with the exact Boot 3 minor.
- Import the Spring Cloud BOM and omit individual Spring Cloud dependency versions.
- Prefer the reactive gateway unless the project deliberately uses the MVC variant.

## Route rules

- Use stable route IDs and explicit predicates.
- Strip untrusted forwarding, identity, and internal headers at the edge.
- Add correlation headers only after removing client-supplied values.
- Keep path rewriting and host changes visible in route configuration.
- Set connect and response timeouts globally, with narrow route overrides.

## Security and resilience

- Authenticate at the edge and authorize again in downstream services.
- Relay tokens only to intended audiences.
- Rate-limit by trusted identity or API key, not an unverified header.
- Retry only idempotent operations and only before response commitment.
- Use circuit breakers for failing dependencies; never hide sustained failure with unlimited retries.

## Testing and operations

- Test predicates, filters, header removal, status mapping, and timeouts.
- Use WireMock or a containerized upstream for integration tests.
- Emit route ID, outcome, latency, and upstream metrics with bounded tags.

## Examples

- See `examples/good-routes.yml` and `examples/bad-routes.yml`.

## Gotchas

- Agent trusts `X-User-Id` from the public request - derive identity after authentication.
- Agent retries POST requests by default - retry only operations proven idempotent.
- Agent adds business orchestration to a gateway filter - keep domain logic downstream.
- Agent omits response timeouts - stalled upstreams can exhaust gateway resources.
- Agent mixes incompatible Spring Cloud and Boot versions - use the official compatibility matrix.