Implement SpringBoot API Rate Limiting with Gateway and Redis

In high‑concurrency systems, uncontrolled traffic can quickly overwhelm CPU, threads, and databases, so rate limiting is the first and most critical defense line.

The optimal placement for rate limiting in a microservice architecture is the gateway layer rather than business code or controllers, because it offers a unified entry point, can block invalid requests before they reach backend services, supports distributed limits via Redis, and runs on WebFlux with near‑zero throughput loss.

The article outlines three common limiting algorithms:

Fixed counter (simple window) : counts requests per second and blocks when the threshold is exceeded; suffers from a burst‑at‑boundary problem where traffic spikes at the end of one second and the start of the next can double the load.

Leaky bucket : queues incoming requests and releases them at a constant rate; provides smooth flow but cannot handle sudden spikes, making it unsuitable for many internet services.

Token bucket (default in Gateway) : continuously generates tokens at a fixed rate; a request proceeds only when it obtains a token, allowing bursts up to the bucket’s capacity. It is the standard algorithm for high‑concurrency internet systems.

Spring Cloud Gateway implements rate limiting through RequestRateLimiterGatewayFilterFactory, which relies on RedisRateLimiter and a KeyResolver. The underlying mechanism combines Redis with a Lua script to guarantee atomic token operations.

The execution flow is:

Client request enters the gateway.

After route matching, the request passes through the rate‑limiting filter.

The KeyResolver extracts the limiting dimension (IP, token, or path).

A Lua script runs in Redis to fetch or generate tokens.

If a token is available, the request is forwarded; otherwise a 429 response is returned.

Project dependencies must include the reactive Redis starter ( spring-boot-starter-data-redis-reactive) alongside spring-cloud-starter-gateway and service‑discovery libraries.

Core parameters are redis-rate-limiter.replenishRate (tokens added per second) and redis-rate-limiter.burstCapacity (maximum bucket size). For example, replenishRate: 10 and burstCapacity: 20 allow a steady 10 req/s with occasional bursts up to 20.

Four concrete limiting scenarios are demonstrated:

IP‑based limiting using a custom KeyResolver that returns the client IP.

User‑token limiting for precise per‑user control, falling back to IP when the token is absent.

Path‑based limiting to protect high‑risk endpoints such as login or order APIs.

Combined IP + path limiting for the highest precision, counting each IP‑path pair separately.

Each scenario includes YAML route configuration and Java bean definitions, preserving the exact code snippets.

Because the default 429 response is a blank page, a global exception handler ( RateLimitExceptionHandler) is added to return a JSON body like {"code":429,"msg":"请求过于频繁，请稍后再试"}, improving front‑end user experience.

The Lua script executed by Redis follows four steps: (1) initialize the token bucket if absent, (2) compute the number of tokens to add based on elapsed time, (3) refill the bucket without exceeding the maximum capacity, and (4) consume one token, allowing the request only when the remaining token count stays above zero. This atomic execution eliminates concurrency errors.

Finally, the article stresses that gateway rate limiting combined with circuit breaking and blacklist filtering forms a three‑layer protection strategy essential for high‑availability, avalanche‑resistant systems, and it is a frequent interview topic for backend engineers.