如何在 Spring 应用中实现每 15 秒一次的外部 API 调用限流

在 Spring 应用开发中，经常会遇到这样一个场景：业务需要响应不定频次的事件（比如用户操作、消息到达），然后触发一次外部 API 调用，而且要求非常严格——每 15 秒最多只能执行一次。听起来很常规，但真正落地时却容易踩坑。如果直接用默认配置的 Token Bucket 算法（比如 RateLimiter.create(1.0 / 15)），它本质上是平滑平均速率，而不是硬性间隔控制——换句话说，它允许“突发”，但你的需求恰恰是“不允许任何突发”，要的是每两次调用之间至少间隔 15 秒，一秒都不能少。

其实完全没必要自己从头实现一个 Leaky Bucket 算法。关键是搞懂一个思路：利用现有限流器的阻塞能力（acquire()），将它当作同步门控，再配合单线程调度，就能等效实现“固定间隔漏出”的效果。下面直接上方案和代码，都是生产环境验证过的。

✅ 推荐方案：阻塞式 RateLimiter + 单线程执行器

@Component
public class ApiRateLimitedCaller {
    // 每 15 秒发放 1 个令牌 → 平均速率 1/15 QPS，acquire() 将自动阻塞至令牌可用
    private final RateLimiter rateLimiter = RateLimiter.create(1.0 / 15.0);

    // 使用单线程执行器确保调用串行化，避免并发竞争导致“瞬时双调用”
    private final ExecutorService executor = Executors.newSingleThreadExecutor(
        r -> new Thread(r, "api-rate-limited-caller-thread")
    );

    public void triggerApiCall(String payload) {
        executor.submit(() -> {
            try {
                // 阻塞等待获取令牌（实际等待至距上次调用 ≥15s）
                rateLimiter.acquire();
                // 此处发起真实 HTTP 调用（如 RestTemplate / WebClient）
                callExternalApi(payload);
            } catch (Exception e) {
                // 记录错误，避免异常中断线程池
                log.error("Failed to call external API", e);
            }
        });
    }

    private void callExternalApi(String payload) {
        // 示例：使用 WebClient 异步调用（注意：此处为同步阻塞调用，符合单线程上下文）
        // webClient.post().uri("https://api.example.com").bodyValue(payload).retrieve().toBodilessEntity().block();
        System.out.println("API called at " + Instant.now());
    }
}

⚠️ 关键注意事项

• 千万别用多线程并发调用 acquire()：如果多个线程同时调用 acquire()，RateLimiter 只能保证平均速率，无法防止两个请求在边界时刻（比如第 14.9 秒和第 15.1 秒）被连续放行。必须通过单线程串行化执行来强制间隔，这是整个方案的核心。
• acquire() 是阻塞的，不是轮询：它会精确休眠至下一个可用时间点（例如上次调用后第 15 秒），不消耗 CPU，时间精度由 JVM 的 System.nanoTime() 保障，完全够用。
• 线程安全与资源释放：RateLimiter 本身是线程安全的；ExecutorService 需要在应用关闭时优雅关闭，可以通过 @PreDestroy 来实现：

@PreDestroy
public void shutdown() {
    executor.shutdown();
    try {
        if (!executor.awaitTermination(10, TimeUnit.SECONDS)) {
            executor.shutdownNow();
        }
    } catch (InterruptedException e) {
        executor.shutdownNow();
        Thread.currentThread().interrupt();
    }
}

• 监控与可观测性（进阶）：可以包装 RateLimiter，统计 acquire() 的等待时长，上报到 Prometheus 指标，这样能及时识别下游延迟升高或配置偏差，对生产运维非常有用。

✅ 总结

Gua va RateLimiter 和 Bucket4j 虽然都是 Token Bucket 的实现，但它们的 acquire() 方法提供了确定性阻塞语义，再配合单线程执行模型，就能完美复现 Leaky Bucket 的“恒定间隔输出”效果。相比自己写定时器或者用 ScheduledTask 来硬凑，这个方案更轻量、更精准、也更容易测试和维护。对于“固定间隔 + 事件触发”这类典型场景，它算得上简洁、可靠、可直接上生产的首选实践。