为什么值得关注

它提供零配置、注解驱动的限流，并通过 Micrometer 实现自动可观测性，灵活的键解析（用户、IP、SpEL）以及弹性降级模式，专为生产级分布式系统设计。

适合谁使用

Spring Boot 开发者
微服务架构师
需要实现限流的后端工程师
寻求限流可观测性的运维/SRE 人员

典型使用场景

保护 REST API 端点免受滥用或过载
对每个用户或 IP 的认证尝试进行限流
对关键/高成本端点采用故障关闭模式控制访问
使用不同算法实现按用户或路由的限流

项目优势

注解式使用简化集成
原子 Lua 脚本消除高并发下的竞态条件
支持令牌桶（内存高效）和滑动窗口日志（精确）两种算法
内置 Micrometer 指标和符合 RFC 的限流头

使用前须知

需要运行中的 Redis 实例（外部依赖）
滑动窗口日志算法的内存消耗与窗口内请求量成正比
当前版本为 0.1.0-SNAPSHOT，处于早期开发阶段

README 快速开始

Limitly — Redis-Backed Rate Limiter Spring Boot Starter

Limitly is a production-grade, zero-config, annotation-based rate limiting library built for Spring Boot applications powered by Redis. Built with Java 21, Spring Boot 3, and Lua Scripting to ensure race-condition-free, atomic operations across distributed pod replicas.

⚡ Features

Annotation-based DX: Drop @RateLimit on any @RestController endpoint.
Atomic Redis Execution: Zero race conditions under high concurrent traffic using Redis Lua scripts (EVALSHA/EVAL).
Dual Algorithms Supported:
- Token Bucket: Smoothed traffic flow, configurable refill rates, low Redis memory footprint.
- Sliding Window Log: Exact request-count precision using Redis Sorted Sets (ZSET).
Flexible Key Resolution:
- USER: Resolves user Principal or X-User-ID header.
- IP: Resolves real client IP (aware of X-Forwarded-For proxy headers).
- SPEL: Dynamic SpEL expression support (e.g. #request.remoteAddr, #user.id).
Resilient Fallback Modes:
- FAIL_OPEN: (Default) Allows request traffic through when Redis is unreachable.
- FAIL_CLOSED: Throttles requests securely during Redis outages.
Production Observability: Built-in Micrometer metrics (ratelimiter.requests.allowed, ratelimiter.requests.denied, ratelimiter.redis.latency, ratelimiter.redis.failures) ready for Prometheus and Grafana dashboards.
RFC-compliant HTTP Headers: Automatically appends X-RateLimit-Limit, X-RateLimit-Remaining, and Retry-After HTTP headers on throttled 429 responses.

🏗️ High-Level Architecture

┌───────────────────────────────────────────────────────────┐
│                     Client Request                        │
└────────────────────────┬──────────────────────────────────┘
                         ▼
              ┌─────────────────────┐
              │ RateLimitInterceptor│  (HandlerInterceptor)
              └──────────┬──────────┘
                         │ resolves key via KeyResolver
                         ▼
              ┌─────────────────────┐
              │  RateLimiterService │
              └──────────┬──────────┘
                         │ executes Lua script atomically

项目描述

Production-grade Redis-backed rate limiter Spring Boot starter. Features atomic Lua execution, Token Bucket & Sliding Window algorithms, SpEL resolution, and Micrometer metrics.

limitly