JDK 26 HTTP/3 客户端怎样评估迁移影响

如果项目已经使用 java.net.http.HttpClient，迁移到 JDK 26 的第一步不是把所有请求强制改成 HTTP/3，而是确认“协议偏好能否被当前网络和服务端兑现”。JDK 26 新增了 HttpClient.Version.HTTP_3，但 HTTP/3 默认并不会主动选用；请求还必须使用 HTTPS，代理、TLS/SSL 配置和服务端能力也会改变最终结果。

官方地址：https://docs.oracle.com/en/java/javase/26/docs/api/java.net.http/java/net/http/HttpClient.html

因此，迁移影响可以分成三层：业务代码大多可复用；客户端构建和请求偏好需要增加配置；部署网络、证书策略、监控和回滚必须重新验证。

先判断：JDK 26 的 HTTP/3 到底改变了什么

HttpClient 仍然负责连接池、请求发送、同步或异步响应处理，HttpRequest 仍然承载 URI、请求头、请求体和超时。真正变化集中在协议选择：客户端或请求可以把 HTTP/3 作为偏好，HttpOption.H3_DISCOVERY 可以补充 HTTP/3 连接发现方式。

这不是“HTTP/2 换成 HTTP/3”的无条件替换。没有明确偏好时，默认选择仍以 HTTP/2 为主；URI 不是 https 时永远不能走 HTTP/3。代理场景下，普通发现模式可能降级到 HTTP/2 或 HTTP/1.1，而要求只能用 HTTP/3 时则应把失败暴露出来。

先用可回退配置做一轮迁移试运行

把协议偏好放在请求级别，便于只灰度一个接口；确认服务端和网络矩阵稳定后，再考虑客户端级别的统一策略。下面的示例选择 ANY，含义是允许实现根据条件建立 HTTP/3，条件不满足时保留可用的降级路径。

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

// 先使用小范围请求验证 HTTP/3 偏好，不把协议切换扩散到整个客户端池。
HttpClient client = HttpClient.newBuilder()
        // 连接建立超时只限制连接阶段，业务超时仍由请求单独控制。
        .connectTimeout(Duration.ofSeconds(5))
        .build();

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.example.com/health"))
        // HTTP/3 只对 HTTPS URI 有效，示例地址应替换为实际支持 HTTP/3 的服务。
        .version(HttpClient.Version.HTTP_3)
        // ANY 允许实现选择发现方式，失败时保留降级空间。
        .setOption(HttpOption.H3_DISCOVERY,
                HttpOption.Http3DiscoveryMode.ANY)
        .timeout(Duration.ofSeconds(8))
        .GET()
        .build();

try {
    HttpResponse response = client.send(
            request, HttpResponse.BodyHandlers.ofString());
    // 记录 status、response.version() 和耗时，不能只记录业务状态码。
    System.out.println(response.statusCode() + " " + response.version());
} catch (java.net.http.UnsupportedProtocolVersionException ex) {
    // HTTP/3 不可用时记录环境原因，交给灰度策略决定是否回退。
    System.err.println("HTTP/3 unavailable: " + ex.getMessage());
}

按四层矩阵评估迁移影响

迁移评估应把“代码能编译”与“生产链路能稳定使用”分开。可以按下面的顺序逐项验收：

其中最容易漏掉的是自定义 TLS 配置：即使 API 已经可以编译，客户端仍可能因为 SSLContext 或 SSLParameters 不适用于 HTTP/3 而抛出 UnsupportedProtocolVersionException。

需要强制 HTTP/3 时，再收紧失败边界

只有在业务明确要求 HTTP/3、并且已完成网络矩阵验证时，才使用 HTTP_3_URI_ONLY。它适合做验收门禁：代理或 TLS 条件不满足时直接失败，让问题进入监控，而不是悄悄退回旧协议。

HttpRequest strictRequest = HttpRequest.newBuilder()
        .uri(URI.create("https://api.example.com/stream"))
        // 只允许 HTTP/3，适合验收和受控灰度，不适合未经验证的全量流量。
        .version(HttpClient.Version.HTTP_3)
        .setOption(HttpOption.H3_DISCOVERY,
                HttpOption.Http3DiscoveryMode.HTTP_3_URI_ONLY)
        .timeout(Duration.ofSeconds(10))
        .GET()
        .build();

// 单独统计协议失败，避免把它和 HTTP 4xx/5xx 混成同一类业务错误。
try {
    client.send(strictRequest, HttpResponse.BodyHandlers.ofString());
} catch (java.net.http.UnsupportedProtocolVersionException ex) {
    // 触发灰度回滚或切换备用客户端，而不是无限重试同一条 QUIC 路径。
    recordProtocolFailure(ex);
}

补齐连接、日志和回滚指标

HTTP/3 迁移至少要新增三类可观测信息：实际响应协议 response.version()、协议协商失败次数、按目标服务拆分的连接建立耗时。JDK 26 的 HTTP Client 日志还提供 http3、quic 等高层事件选项，可在预发布环境短时开启，排查完成后再按日志成本关闭。

回滚不要依赖“重新部署旧版本”这一条路。更稳妥的做法是保留同一业务接口的 HTTP/2 客户端配置，把 HTTP/3 偏好放到灰度开关或请求策略中；当协议失败率、连接超时或代理错误超过门槛时，关闭开关即可恢复旧路径。

最终迁移清单

1. 用 JDK 26 编译并运行最小请求，确认 HTTP_3 与 H3_DISCOVERY 可用。
2. 只选择 HTTPS 目标，分别验证直连、代理、自定义 TLS 和服务端支持。
3. 先使用 ANY 做灰度，再用 HTTP_3_URI_ONLY 做受控验收。
4. 记录实际协议版本、连接耗时和 UnsupportedProtocolVersionException。
5. 保留 HTTP/2 回退开关，按服务和网络区域逐步扩大流量。

结论：JDK 26 HTTP/3 的迁移成本主要不在业务请求代码，而在运行环境和失败语义。能复用 HttpClient 不等于能直接切流；先验证 HTTPS、代理、TLS、服务端和观测闭环，再决定是否扩大 HTTP/3 范围。

常见问题

HTTP/3 偏好设置后一定会使用 HTTP/3 吗？

不一定。它是协议选择提示，实际结果还受 URI、代理、TLS 和服务端能力影响；需要强制验收时才考虑 HTTP_3_URI_ONLY。

旧的 HttpRequest 代码要全部重写吗？

通常不需要。URI、请求体、响应处理和业务接口可以复用，重点是把协议偏好、异常分类、日志和回滚纳入配置。

为什么测试环境成功，生产环境却回退？

常见原因是生产出口代理、UDP/QUIC 路径、TLS 参数或服务端入口与测试环境不同，应按环境分别建立验证矩阵。