如何在Spring RestClient中处理API的限流响应头？

你调用的API返回的限流响应头如下：

HTTP/1.1 200 OK
X-Rate-Limit-Limit: 1200
X-Rate-Limit-Remaining: 1199
X-Rate-Limit-Reset: 1609459200

针对这个场景，Resilience4j是更合适的方案，Spring RestClient内置机制仅能实现基础重试，动态限流控制需要额外开发。具体实现方式如下：

一、用Resilience4j实现动态限流与智能重试 #

Resilience4j的RateLimiter和Retry组件可以完美适配该需求，核心逻辑是从响应头提取限流参数，动态调整限流规则，同时在触发限流时精准执行重试。

1. 拦截响应提取限流参数，更新RateLimiter配置 #

通过Spring RestClient的ExchangeFilterFunction拦截每一次响应，解析限流头并动态修改RateLimiter的规则：

@Bean
public ExchangeFilterFunction rateLimitHeaderUpdater(RateLimiterRegistry rateLimiterRegistry) {
    return ExchangeFilterFunction.ofResponseProcessor(clientResponse -> {
        // 从响应头提取限流参数
        String limit = clientResponse.headers().firstHeader("X-Rate-Limit-Limit");
        String remaining = clientResponse.headers().firstHeader("X-Rate-Limit-Remaining");
        String reset = clientResponse.headers().firstHeader("X-Rate-Limit-Reset");
        
        if (limit != null && remaining != null && reset != null) {
            int totalQuota = Integer.parseInt(limit);
            int leftQuota = Integer.parseInt(remaining);
            long resetTime = Long.parseLong(reset);
            long currentEpoch = System.currentTimeMillis() / 1000;
            long refreshWindow = Math.max(resetTime - currentEpoch, 1); // 避免负数
            
            // 更新指定RateLimiter的配置
            RateLimiter apiLimiter = rateLimiterRegistry.rateLimiter("apiRequestLimiter");
            RateLimiterConfig updatedConfig = RateLimiterConfig.custom()
                    .limitForPeriod(leftQuota)
                    .limitRefreshPeriod(Duration.ofSeconds(refreshWindow))
                    .build();
            apiLimiter.changeConfig(updatedConfig);
        }
        return Mono.just(clientResponse);
    });
}

2. 配置Retry组件，根据重置时间延迟重试 #

当响应头显示剩余配额为0时触发重试，重试等待时间直接基于X-Rate-Limit-Reset计算：

@Bean
public Retry apiRateLimitRetry() {
    RetryConfig retryConfig = RetryConfig.custom()
            .maxAttempts(3)
            .waitDurationFunction(retryCtx -> {
                // 从上下文获取之前提取的重置时间
                Long resetEpoch = retryCtx.getAttributes().get("X-Rate-Limit-Reset");
                if (resetEpoch != null) {
                    long waitSeconds = Math.max(resetEpoch - System.currentTimeMillis() / 1000, 2);
                    return Duration.ofSeconds(waitSeconds);
                }
                return Duration.ofSeconds(5); // 兜底等待时间
            })
            .retryOnResult(response -> {
                // 判断是否触发限流条件
                ClientResponse resp = (ClientResponse) response;
                String remainingQuota = resp.headers().firstHeader("X-Rate-Limit-Remaining");
                return remainingQuota != null && Integer.parseInt(remainingQuota) == 0;
            })
            .build();
    return Retry.of("apiRateLimitRetry", retryConfig);
}

3. 整合到Spring RestClient #

把过滤器和Resilience4j的装饰逻辑注入到RestClient构建流程中：

@Bean
public RestClient apiRestClient(RestClient.Builder builder,
                                ExchangeFilterFunction rateLimitHeaderUpdater,
                                Retry apiRateLimitRetry) {
    RateLimiterRegistry registry = RateLimiterRegistry.ofDefaults();
    RateLimiter apiLimiter = registry.rateLimiter("apiRequestLimiter");
    
    return builder
            .filter(rateLimitHeaderUpdater)
            // 请求前先经过RateLimiter校验
            .requestInterceptor(request -> {
                CheckedRunnable limitedRequest = RateLimiter.decorateCheckedRunnable(apiLimiter, () -> {});
                try {
                    limitedRequest.run();
                } catch (RateLimitExceededException e) {
                    throw new RuntimeException("请求超出API限流配额", e);
                }
            })
            // 用Resilience4j的Retry包装请求工厂
            .requestFactory(new Resilience4jClientHttpRequestFactory(apiRateLimitRetry))
            .build();
}

二、Spring RestClient内置机制的现状 #

Spring RestClient本身没有提供基于响应头的动态限流能力，它的内置重试（结合RetryTemplate）仅能实现固定策略的重试，无法根据API返回的限流参数动态调整等待时间或限流规则。如果硬要用内置机制，需要手动编写限流逻辑再结合RetryTemplate，但这种方式代码冗余、维护成本高，远不如Resilience4j的组件化方案高效。

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