Implementing Distributed Rate Limiting in Spring Cloud Gateway with Token Bucket and Lua Script

In distributed high‑concurrency systems, rate limiting is essential to prevent overload during traffic spikes such as Double‑11 sales or ticket‑booking bursts.

The article first reviews common rate‑limiting algorithms: simple counter/window, leaky bucket, and token bucket, highlighting their advantages and drawbacks.

Spring Cloud Gateway provides a built‑in rate‑limiting filter that implements the token‑bucket algorithm using Redis and a Lua script.

The Java class RedisRateLimiter (gateway/filter/ratelimit/RedisRateLimiter.java) prepares Redis keys, builds script arguments, executes the Lua script via redisTemplate.execute, and processes the result to determine whether the request is allowed and how many tokens remain.

The accompanying Lua script ( request_rate_limiter.lua) defines keys for token count and timestamp, reads parameters (rate, capacity, now, requested), calculates the fill time, token refill based on elapsed time, decides if the request can be served, updates Redis with the new token count and timestamp, and returns {allowed_num, new_tokens}.

A line‑by‑line analysis explains the meaning of each argument (tokens key, timestamp key, rate, capacity, now, requested) and the core logic: compute bucket fill time, retrieve and initialize token count, calculate elapsed time, refill tokens, check allowance, decrement tokens if allowed, and persist the state.

The article concludes with a call to share the content and join a technical community.