Java HttpClient HTTP2 连接复用的配置方法

Java HttpClient 的 HTTP/2 连接复用，关键不是每次请求都“打开一个 HTTP/2 连接”，而是长期持有并复用同一个 HttpClient。显式设置 version(HttpClient.Version.HTTP_2) 只是协议偏好；如果代理、TLS/ALPN 或服务端条件不满足，实际响应仍可能回落到 HTTP/1.1。判断结果要看 HttpResponse.version()，不要只看构造器配置。

官方文档：https://docs.oracle.com/en/java/javase/25/docs/api/java.net.http/java/net/http/HttpClient.html

先把客户端生命周期放对位置

HttpClient 通常管理自己的连接池，而且不同客户端实例之间通常不共享连接池。因此，把客户端放在服务对象、组件或应用级单例中，再反复创建 HttpRequest，才有机会复用同源连接。下面的代码展示了配置与结果判断，代码中的客户端不是每次调用都重新创建。

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public final class Http2Client {
    // 客户端保持较长生命周期，便于同源请求共享实现管理的连接资源。
    private static final HttpClient CLIENT = HttpClient.newBuilder()
            // 表达优先使用 HTTP/2；协商不成时允许实现回落到 HTTP/1.1。
            .version(HttpClient.Version.HTTP_2)
            // 这里只限制建立连接的等待时间，不是响应读取超时。
            .connectTimeout(Duration.ofSeconds(5))
            .build();

    public static HttpResponse get(String url) throws Exception {
        // 每次只创建请求对象，客户端实例继续复用。
        HttpRequest request = HttpRequest.newBuilder(URI.create(url))
                .timeout(Duration.ofSeconds(15))
                .GET()
                .build();
        HttpResponse response = CLIENT.send(
                request, HttpResponse.BodyHandlers.ofString());

        // 以响应报告的版本为准，不能把 preferred version 当成实际结果。
        System.out.println("实际协议：" + response.version());
        return response;
    }
}

这里的复用边界有两个：客户端实例要复用，请求目标还要属于同一个 origin。不同主机、端口或协议的请求不能因为共用了 Java 对象，就被当成同一条 HTTP/2 连接。

HTTP/2 连接复用和多路复用是什么关系

HTTP/2 的价值在于同一条连接可以承载多个并发 stream，所以并发请求不必机械地一请求一连接。Java HttpClient 的 API 没有提供一个名为“HTTP/2 最大连接数”的 Builder 方法；连接选择、创建和复用由实现结合 origin、服务端设置和连接状态管理。应用侧最重要的动作是共享客户端，并且完整消费响应体。

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

// 多个同源请求共享同一个客户端，HTTP/2 才有机会在连接上复用 stream。
HttpClient client = HttpClient.newBuilder()
        .version(HttpClient.Version.HTTP_2)
        .build();

List urls = List.of(
        "https://api.example.com/profile",
        "https://api.example.com/orders");

List>> futures = urls.stream()
        .map(url -> {
            // BodyHandlers.ofString 会消费响应体，避免留下未完成的响应资源。
            HttpRequest request = HttpRequest.newBuilder(URI.create(url)).GET().build();
            return client.sendAsync(request, HttpResponse.BodyHandlers.ofString());
        })
        .toList();

上面的示例只表达复用关系，不承诺两个请求一定落在同一条物理连接上。服务端的最大并发流数、连接是否健康、代理模式以及请求是否同源，都会影响最终选择。

哪些系统参数可以调，哪些不能混用

Oracle 的 java.net.http 文档列出了实现使用的系统属性。需要缩短 HTTP/2 空闲连接保留时间时，可以在 JVM 启动参数中设置：

# 让 HTTP/2 空闲连接最多保留 60 秒；具体行为属于 JDK 实现配置。
java -Djdk.httpclient.keepalive.timeout.h2=60 -jar app.jar

jdk.httpclient.connectionPoolSize 容易被误读：官方说明它是 HTTP/1.1 keep-alive 缓存保留的最大连接数，默认 0 表示不设缓存上限；它不是 HTTP/2 连接池大小开关。需要调 HTTP/2 流量时，应先确认服务端的并发流限制、请求体/响应体消费和 origin 划分，再决定是否调整实现级参数。

这些属性是 JDK 实现使用的配置，其他 HttpClient 实现不一定支持。官方文档也不保证通过 System.setProperty() 在程序运行中设置后一定生效，所以生产环境优先使用 JVM 启动参数或部署配置。

最小判断：配置成功不等于响应就是 HTTP/2

排查时把“偏好配置”和“实际协议”分开记录。client.version() 返回客户端偏好的版本；response.version() 才是该次响应报告的版本。若返回 HTTP_1_1，先检查服务端是否支持 HTTP/2、TLS/ALPN 是否完成、请求是否经过不支持 HTTP/2 的代理，再检查是否误把不同 origin 当成同一连接。

常见问题

Q：把 HttpClient 声明成 static 就一定只有一条连接吗？
不一定。它只是让请求共享同一个客户端实例；实际连接数量仍由 origin、协议协商、服务端设置和连接状态决定。

Q：能否用 connectionPoolSize 控制 HTTP/2 多路复用数量？
不能按这个含义理解。该属性的官方定义针对 HTTP/1.1 keep-alive 缓存；HTTP/2 应先关注 stream 并发和连接空闲策略。

总结：长期复用同一个 HttpClient，显式表达 HTTP/2 偏好，使用 HttpResponse.version() 观察实际结果；不要把 HTTP/1.1 的连接缓存参数当作 HTTP/2 连接数配置。