使用Resilience4j实现基于API Key的接口限流可行性问询

结论 #

完全可以实现。Resilience4j本身支持多限流实例管理，天然适配API Key、IP这类自定义维度的精细化限流需求，不需要依赖额外扩展组件即可完成单机场景下的限流逻辑。

核心实现思路 #

• Resilience4j的RateLimiter组件没有强制要求全局单实例，你可以通过RateLimiterRegistry容器管理不同维度的独立限流实例
• 每个API Key对应唯一的限流实例ID（如api-key:xxx），每个实例独立统计调用次数、遵循独立的限流规则
• 你也可以统一配置全局默认限流规则，所有新创建的自定义维度实例自动复用该规则

具体实现步骤（Spring Boot场景为例） #

1. 引入依赖 #

如果是Spring Boot 3项目，在pom.xml中引入Resilience4j限流starter：

<dependency>
    <groupId>io.github.resilience4j</groupId>
    <artifactId>resilience4j-spring-boot3</artifactId>
    <version>最新稳定版</version>
</dependency>

2. 配置默认限流规则 #

在application.yml中配置通用限流参数，也可以针对特定API Key单独配置：

resilience4j:
  rate-limiter:
    configs:
      default:
        limit-for-period: 100 # 每个时间窗口允许的调用次数
        limit-refresh-period: 60s # 时间窗口长度
        timeout-duration: 0 # 拿不到许可直接返回错误，不需要等待
    instances:
      # 可以单独给某个高频API Key配置特殊规则
      api-key:special-abc123:
        limit-for-period: 500
        limit-refresh-period: 60s
    registry:
      instance-ttl: 3600s # 闲置1小时的限流实例自动回收，避免内存占用过高

3. 实现请求拦截校验 #

在全局Filter或者拦截器中，获取请求头的API Key，调用对应限流实例校验：

@Component
public class ApiKeyRateLimitFilter extends OncePerRequestFilter {
    private final RateLimiterRegistry rateLimiterRegistry;
    private final ObjectMapper objectMapper;

    // 构造注入
    public ApiKeyRateLimitFilter(RateLimiterRegistry rateLimiterRegistry, ObjectMapper objectMapper) {
        this.rateLimiterRegistry = rateLimiterRegistry;
        this.objectMapper = objectMapper;
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        String apiKey = request.getHeader("X-API-Key");
        // 此处可添加API Key合法性校验逻辑，省略
        String rateLimiterId = "api-key:" + apiKey;
        // 获取对应API Key的限流实例，不存在则自动按默认配置创建
        RateLimiter rateLimiter = rateLimiterRegistry.rateLimiter(rateLimiterId);
        // 尝试获取许可
        if (rateLimiter.acquirePermission()) {
            filterChain.doFilter(request, response);
        } else {
            response.setStatus(HttpStatus.TOO_MANY_REQUESTS.value());
            response.setContentType(MediaType.APPLICATION_JSON_VALUE);
            Map<String, Object> result = new HashMap<>();
            result.put("code", 429);
            result.put("msg", "请求过于频繁，请稍后再试");
            response.getWriter().write(objectMapper.writeValueAsString(result));
        }
    }
}

扩展说明 #

• 如果需要按照IP、用户ID等其他维度限流，只需要修改rateLimiterId的生成规则即可，逻辑完全一致
• 上述实现为单机限流，如果集群部署需要全局统一维度的限流，可以结合Redis实现Resilience4j的自定义RateLimiter，或者在网关层统一处理限流逻辑
• 生产环境建议开启限流指标监控，方便排查异常调用问题

内容的提问来源于stack exchange，提问作者metalhead696