Java Semaphore 在虚拟线程中如何限制下游并发

把 Java 应用切到虚拟线程后，最容易混淆的是“任务可以很多”和“下游也能同时处理很多”并不是一回事。比如订单服务可以为每个请求创建虚拟线程，但画像服务只允许同时处理 20 个请求，这时应该限制进入画像服务的数量，而不是再建一个大小为 20 的平台线程池。

官方文档：https://docs.oracle.com/en/java/javase/25/core/virtual-threads.html

Semaphore API：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/concurrent/Semaphore.html

虚拟线程很多，为什么下游并发仍要单独限流

虚拟线程适合承载大量会等待 I/O 的任务，它的优势是提高吞吐，不是让单次 HTTP 调用变快。固定线程池确实能把同时发出的请求压到 20 个，但它同时把“线程资源管理”和“画像服务容量管理”绑在了一起：池里的 20 个平台线程会被占住，其他不访问画像服务的工作也可能排队。

更清晰的结构是：每个请求仍然由独立虚拟线程执行，只有真正进入画像服务的那一小段代码需要 permit。等待 permit 的是虚拟线程，不是被占满的固定平台线程池；获得 permit 后才进入下游调用区，调用结束再归还。

正确的 Semaphore 保护区应该包住哪里

保护区要尽量窄，只包住受下游容量约束的调用。准备参数、组装本地对象和处理响应可以放在外面；否则 permit 会被无关工作长期占用。下面的示例给画像服务设置 20 个许可，并让每个提交的任务运行在虚拟线程中。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.concurrent.*;

final class ProfileGateway {
    // permit 表示画像服务允许同时处理的请求数，不代表虚拟线程总数。
    private final Semaphore permits = new Semaphore(20, true);
    private final HttpClient client = HttpClient.newHttpClient();

    String load(URI endpoint) throws Exception {
        // 可中断等待，取消请求时不会悄悄吞掉中断信号。
        permits.acquire();
        try {
            HttpRequest request = HttpRequest.newBuilder(endpoint)
                    .timeout(java.time.Duration.ofSeconds(2))
                    .GET()
                    .build();
            // 这里只把真正受下游容量约束的 HTTP 调用放进保护区。
            return client.send(request, HttpResponse.BodyHandlers.ofString()).body();
        } finally {
            // 无论响应成功、异常还是超时，都必须归还 permit。
            permits.release();
        }
    }
}

try (var executor = Executors.newVirtualThreadPerTaskExecutor()) {
    // 每个任务使用一个虚拟线程，限流职责交给 Semaphore。
    var gateway = new ProfileGateway();
    var future = executor.submit(() -> gateway.load(URI.create("https://profile.example/api")));
    String body = future.get();
}

示例中的 fair=true 让等待者按接近 FIFO 的顺序获得许可，适合不希望某些请求长期插队的资源访问。若更看重吞吐而不要求排队顺序，可以评估非公平模式，但不要把公平性误解为严格的请求到达时间排序。

等待 permit 的超时和下游超时要分开处理

acquire() 可能一直等待，适合调用方愿意排队的场景；如果请求有明确截止时间，可以使用 tryAcquire。注意它只控制“等许可”的时间，HTTP 请求自己的 timeout 仍然要单独设置。

boolean acquired = false;
try {
    // 只等待 300 毫秒，避免排队时间耗尽整个请求预算。
    acquired = permits.tryAcquire(300, TimeUnit.MILLISECONDS);
    if (!acquired) {
        throw new TimeoutException("等待画像服务并发许可超时");
    }
    return callProfileService();
} catch (InterruptedException e) {
    // 恢复中断状态，让上层取消逻辑仍然可见。
    Thread.currentThread().interrupt();
    throw e;
} finally {
    // 只有获取成功才释放，避免把许可数错误地增加。
    if (acquired) {
        permits.release();
    }
}

监控时至少区分三类信号：等待 permit 的时间、拿到 permit 后的下游响应时间，以及 availablePermits() 和队列长度的趋势。若连接池已经只有 20 个连接，连接池本身就会阻塞第 21 个访问者，此时再加一个相同上限的 Semaphore 通常只会增加等待层次；只有当两个限制代表不同资源时，才有理由分别保留。

什么时候不该用这套限流方式

Semaphore 适合限制外部服务、文件句柄或其他可计数资源，不适合用来解决 CPU 密集型计算。CPU 工作应根据处理器和压测结果安排平台线程或专门执行器。还要确认下游客户端是否真的支持虚拟线程中的阻塞调用，并观察是否存在长时间持有锁、原生调用或其他导致载体线程被固定的代码。

落地时可以按这个顺序检查：先写出受限资源的真实上限；再把 permit 放在最窄的调用边界；随后给等待和下游调用分别设定超时；最后用指标观察是否是 Semaphore、连接池、远端配额还是 CPU 真正成为瓶颈。这样虚拟线程保持任务表达能力，Semaphore 只承担它擅长的资源闸门职责。

相关问题

Semaphore 的 permit 数应该等于虚拟线程数吗？

不应该。permit 数应来自下游服务、连接数或配额等受限资源；虚拟线程数对应并发任务数，两者通常不是同一个量。

获取 permit 后为什么一定要在 finally 释放？

因为网络异常、超时、取消和业务异常都会让调用提前离开。只在成功分支释放会逐渐耗尽 permit，最后表现为所有新任务都在等待。