如何利用 Java **信号量（Semaphore）**实现对下游第三方受限 API 的平滑并发限流

用 Semaphore 限流第三方 API，为什么你的方案总是“纸老虎”？

先聊一个实际开发中反复踩坑的场景：你用 Semaphore 来限制对下游第三方 API 的并发调用数，逻辑看起来很简单——拿到许可就去请求，请求完就归还许可。但一上线，下游开始大量返回 429（Too Many Requests）甚至直接超时，而你自己的线程池却还不知道怎么回事，依旧在那边堂而皇之地释放许可。问题出在哪？根本原因在于：Semaphore 只看“许可数量”，它根本不关心你调用到底成功了还是失败了。

照搬 Semaphore 做限流，为什么容易失效？

很多人会写成这样：

semaphore.acquire();
try {
    callThirdPartyApi(); // 这可能抛异常或超时
} finally {
    semaphore.release(); // ❌ 只要异常就 release，限流形同虚设
}

你是这么写的吗？那问题就来了。

假设下游服务已经处于过载状态，你的请求发过去后，很可能得到 503 Service Una vailable 或者直接超时。此时 release() 仍然执行——相当于你的许可被“误释放”了。在你看来，许可总数没减少，下一个请求还能拿到许可、继续打过去。结果就是：你以为限流了，实际上是“限了个寂寞”，实际请求量可能远超下游能承受的极限。

真实场景下，必须把「申请许可 → 发起请求 → 根据结果决定是否归还」做成一个原子化的决策流程。

正确做法：只有被下游接纳的请求，才算是“用掉了”一个许可

关键点在于：release() 这个操作，只能在确认“这次调用被下游真正处理”之后才执行。

具体来说，大多数第三方 API 的规范是：

• HTTP 状态码 200 + 业务返回码 code: 0（或其他约定值）才算真正成功
• 一旦遇到 429、503、timeout、IOException，就不要 release()——意味着这个许可被“废掉”了，不归还给许可池

当然，这么做的副作用也是显而易见的：如果失败次数多了，许可池里的许可数会越来越少，最终所有线程都拿不到许可。但这才是正确的行为——下游已经扛不住的时候，你就不该继续发起请求。相反，你应该考虑的是降级、重试或者等待。

另外，必须警惕的是：

• 使用 acquireUninterruptibly() ？别，它会让线程无限阻塞，推荐用 tryAcquire(long, TimeUnit) 带上超时时间
• 建议用 try-with-resources + 自定义 AutoCloseable 来封装许可的生命周期（参考下面例子）

一个简单又可靠的封装模板：

public class ApiPermit implements AutoCloseable {
    private final Semaphore semaphore;
    private final boolean acquired;

    public ApiPermit(Semaphore s) {
        this.semaphore = s;
        this.acquired = s.tryAcquire(1, 3, TimeUnit.SECONDS); // 最多等 3 秒
    }

    public boolean isValid() { return acquired; }

    @Override
    public void close() {
        if (acquired) semaphore.release(); // 仅当成功获取许可时才 release
    }
}

使用的时候就更清晰了：

try (ApiPermit permit = new ApiPermit(semaphore)) {
    if (!permit.isValid()) throw new RateLimitException("No API permit in 3s");

    Response r = httpClient.post(url, body);
    if (r.statusCode() == 200 && r.json().get("code").asInt() == 0) {
        // ✅ 成功，close() 会自动 release
        return r;
    } else {
        // ❌ 失败，不 release，相当于这次许可“作废”
        throw new ApiException(r);
    }
}

这才是一个能扛住生产压力的写法。

更复杂的挑战：如何处理下游的动态限流策略？

很多第三方 API 的限流窗口并不是固定的每秒 10 次，而是基于滑动时间窗口，或者依赖服务端令牌桶的动态填充策略。如果你硬编码一个 new Semaphore(10)，那很可能没过多久就失效了——比如下游把配额从 10 提升到 20，但你的限流器还卡在 10。

更常见的做法是：让 Semaphore 与外部信号源联动。

比如很多 API 会在响应头中返回当前剩余的配额和重置时间：

• X-RateLimit-Remaining: 2
• X-RateLimit-Reset: 1717021248（Unix 时间戳）

拿到这些信息后，你可以：

• 每次请求后，用 semaphore.drainPermits() 清空旧许可，再用 semaphore.release(n) 补充新的剩余配额数
• 如果 X-RateLimit-Reset 的时间戳临近，可以用 ScheduledExecutorService 提前触发许可重置
• 但注意并发安全：所有 drainPermits() 和 release() 的操作必须在同一个同步块内完成，推荐用 ReentrantLock 来包一层

这种思路下，你的限流器就不再是死板的“固定令牌数”，而是能实时感知下游的承载能力的动态限流器。

别忘了：线程泄漏和监控盲区才是真正的“隐形杀手”

说实话，在实际生产环境中，最让人头疼的往往不是逻辑本身，而是你想象不到的那些边边角角：

• tryAcquire 超时后没有拿到许可，release() 不会执行——没问题；但你要警惕 fallback 逻辑是否意外调用了 release()，那就会导致许可凭空增加。
• 在异步调用（比如 CompletableFuture）中，忘了在回调里处理许可的释放——这是最常见的泄漏场景。必须用 whenComplete 或其他统一收口策略。
• 没有把 semaphore.getQueueLength() 和 a vailablePermits() 暴露到 metrics 系统里——那你就永远无法判断：到底是下游变慢了，还是自己设置的许可数太小了？
• JVM 停机前要不要调用 semaphore.drainPermits()？一般不影响，但在单元测试中使用 mock 验证时需要注意。

真正难的不是写对那几行 acquire 和 release，而是让每次许可的“出生、存活、死亡”都全程可追溯。否则，当故障发生时，你只能反问自己：是下游崩了？配置错了？还是某段异常路径悄悄吞掉了许可？

这才是工程上的真正挑战。