当前位置：首页 > news >正文

探索 Java 中的新 HTTP 客户端

news 2026/5/12 16:26:08

你是否也遇到过这样的时刻：只是想发个 HTTP 请求，却被连接管理、重定向、超时与线程阻塞折腾得不亦乐乎？那就试试 Java 11 正式标准化了全新的 HttpClient，原生支持 HTTP/2、异步与 WebSocket，极大简化了客户端网络编程。

1. 概览

本文将介绍 Java 11 对全新HTTP 客户端 API（支持 HTTP/2 与 WebSocket）的标准化。

它旨在替代 JDK 早期就存在的旧类HttpURLConnection（文档见：https://docs.oracle.com/en/java/javase/21/docs/api/java.base/...）。

在不久之前，Java 只有较为底层、功能有限且不够友好的HttpURLConnectionAPI。因此社区普遍使用第三方库，如 Apache HttpClient、Jetty 以及 Spring 的 RestTemplate。

2. 背景

该变更由 JEP 321 引入并最终在 Java 11 中定型。

2.1. JEP 321 的主要变更

Java 9 的孵化版 HTTP API 已正式并入 Java SE API。新的 HTTP APIs 位于java.net.http.*。
新版本的 HTTP 协议旨在提升客户端请求与服务器响应的整体性能，包括多路复用、头压缩与推送承诺（push promise）等特性。
自 Java 11 起，API 全面支持异步（相比之下，旧的 HTTP/1.1 实现是阻塞式的）。异步以CompletableFuture实现，阶段式流水线在前一阶段完成后自动衔接执行。
新的 HTTP 客户端提供了标准方式执行网络操作，原生支持现代 Web 能力（如 HTTP/2），无需引入第三方依赖。
新 API 原生支持 HTTP/1.1 与 HTTP/2 的 WebSocket。核心类型包括：
- HttpClient（java.net.http.HttpClient）
- HttpRequest（java.net.http.HttpRequest）
- HttpResponse<T>（java.net.http.HttpResponse）
- WebSocket（java.net.http.WebSocket）

2.2. Java 11 之前客户端的问题

旧版HttpURLConnection及其实现存在诸多问题：

URLConnection为多个如今已不再使用的协议（FTP、gopher 等）而设计；
API 早于 HTTP/1.1，抽象层级不合时宜；
仅支持阻塞模式（一次请求/响应占用一个线程）；
维护困难。

3. HTTP Client API 总览

与HttpURLConnection不同，新 HTTP 客户端同时提供同步与异步两种请求机制。

API 的三大核心：

HttpRequest：要发送的请求；
HttpClient：跨请求的通用配置容器；
HttpResponse：请求的响应结果。

下面分别展开，先从请求开始。

4. HttpRequest

HttpRequest表示将要发送的请求，可通过HttpRequest.newBuilder()获取构建器；构建器提供多种便捷方法配置请求。

注：JDK 16 新增HttpRequest.newBuilder(HttpRequest request, BiPredicate<String,String> filter)，可基于已有请求复制初始状态，再在构建前做修改（如移除部分头）：

HttpRequest.newBuilder(request, (name, value) -> !name.equalsIgnoreCase("Foo-Bar"));

4.1. 设置 URI

可直接用带URI的构造方式，或在构建器上调用uri(URI)：

HttpRequest.newBuilder(new URI("https://postman-echo.com/get")); HttpRequest.newBuilder() .uri(new URI("https://postman-echo.com/get"));

4.2. 指定 HTTP 方法

构建器提供以下方法：

GET()
POST(BodyPublisher body)
PUT(BodyPublisher body)
DELETE()

一个最简单的 GET 示例：

HttpRequest request = HttpRequest.newBuilder() .uri(new URI("https://postman-echo.com/get")) .GET() .build();

常见的附加参数包括：HTTP 协议版本、请求头与超时。

4.3. 设置协议版本

API 默认充分利用 HTTP/2，也可显式指定：

HttpRequest request = HttpRequest.newBuilder() .uri(new URI("https://postman-echo.com/get")) .version(HttpClient.Version.HTTP_2) .GET() .build();

注意：若对端不支持 HTTP/2，客户端会回退到 HTTP/1.1。

4.4. 设置请求头

可用headers(k1,v1,k2,v2,...)一次性传入，或多次调用header(k,v)：

HttpRequest request = HttpRequest.newBuilder() .uri(new URI("https://postman-echo.com/get")) .headers("key1", "value1", "key2", "value2") .GET() .build(); HttpRequest request2 = HttpRequest.newBuilder() .uri(new URI("https://postman-echo.com/get")) .header("key1", "value1") .header("key2", "value2") .GET() .build();

4.5. 设置超时

默认无穷大。可用Duration设置，超时会抛出HttpTimeoutException：

HttpRequest request = HttpRequest.newBuilder() .uri(new URI("https://postman-echo.com/get")) .timeout(Duration.ofSeconds(10)) .GET() .build();

5. 设置请求体

POST(BodyPublisher),PUT(BodyPublisher)可携带请求体（DELETE()也支持不带体的删除）。常用的BodyPublisher工厂有：

HttpRequest.BodyPublishers.ofString：基于字符串；
HttpRequest.BodyPublishers.ofInputStream：基于输入流（以Supplier<InputStream>形式延迟创建）；
HttpRequest.BodyPublishers.ofByteArray：基于字节数组；
HttpRequest.BodyPublishers.ofFile：基于文件路径内容；
无请求体：HttpRequest.BodyPublishers.noBody()。

JDK 16 新增BodyPublishers.concat(...)，可把多个 publisher 的内容顺序拼接为一个请求体。

5.1. 字符串请求体

HttpRequest request = HttpRequest.newBuilder() .uri(new URI("https://postman-echo.com/post")) .headers("Content-Type", "text/plain;charset=UTF-8") .POST(HttpRequest.BodyPublishers.ofString("Sample request body")) .build();

5.2. 输入流请求体

byte[] sampleData = "Sample request body".getBytes(); HttpRequest request = HttpRequest.newBuilder() .uri(new URI("https://postman-echo.com/post")) .headers("Content-Type", "text/plain;charset=UTF-8") .POST(HttpRequest.BodyPublishers .ofInputStream(() -> new ByteArrayInputStream(sampleData))) .build();

5.3. 字节数组请求体

byte[] sampleData = "Sample request body".getBytes(); HttpRequest request = HttpRequest.newBuilder() .uri(new URI("https://postman-echo.com/post")) .headers("Content-Type", "text/plain;charset=UTF-8") .POST(HttpRequest.BodyPublishers.ofByteArray(sampleData)) .build();

5.4. 文件请求体

HttpRequest request = HttpRequest.newBuilder() .uri(new URI("https://postman-echo.com/post")) .headers("Content-Type", "text/plain;charset=UTF-8") .POST(HttpRequest.BodyPublishers.ofFile( Paths.get("src/test/resources/sample.txt"))) .build();

6. HttpClient

所有请求都由HttpClient发送，可通过HttpClient.newBuilder()或HttpClient.newHttpClient()获取。下面看几个常用能力。

6.1. 处理响应体

新的BodyHandlers工厂提供常见类型的响应体处理器：

BodyHandlers.ofByteArray; BodyHandlers.ofString; BodyHandlers.ofFile; BodyHandlers.discarding; BodyHandlers.replacing; BodyHandlers.ofLines; BodyHandlers.fromLineSubscriber;

Java 11 之前：

HttpResponse<String> response = client.send(request, HttpResponse.BodyHandler.asString());

现在可简化为：

HttpResponse<String> response = client.send(request, BodyHandlers.ofString());

6.2. 设置代理

HttpResponse<String> response = HttpClient .newBuilder() .proxy(ProxySelector.getDefault()) .build() .send(request, BodyHandlers.ofString());

6.3. 跟随重定向策略

HttpResponse<String> response = HttpClient.newBuilder() .followRedirects(HttpClient.Redirect.ALWAYS) .build() .send(request, BodyHandlers.ofString());

6.4. 认证器（Authenticator）

HttpResponse<String> response = HttpClient.newBuilder() .authenticator(new Authenticator() { @Override protected PasswordAuthentication getPasswordAuthentication() { return new PasswordAuthentication( "username", "password".toCharArray()); } }) .build() .send(request, BodyHandlers.ofString());

6.5. 同步与异步发送

同步：send(...)（阻塞直到响应返回）
异步：sendAsync(...)（立即返回CompletableFuture<HttpResponse<T>>）

同步示例：

HttpResponse<String> response = HttpClient.newBuilder() .build() .send(request, BodyHandlers.ofString());

异步示例：

CompletableFuture<HttpResponse<String>> response = HttpClient.newBuilder() .build() .sendAsync(request, HttpResponse.BodyHandlers.ofString());

批量并发请求：

List<URI> targets = Arrays.asList( new URI("https://postman-echo.com/get?foo1=bar1"), new URI("https://postman-echo.com/get?foo2=bar2")); HttpClient client = HttpClient.newHttpClient(); List<CompletableFuture<String>> futures = targets.stream() .map(target -> client .sendAsync( HttpRequest.newBuilder(target).GET().build(), HttpResponse.BodyHandlers.ofString()) .thenApply(HttpResponse::body)) .collect(Collectors.toList());

6.6. 指定异步执行器（Executor）

ExecutorService executorService = Executors.newFixedThreadPool(2); CompletableFuture<HttpResponse<String>> response1 = HttpClient.newBuilder() .executor(executorService) .build() .sendAsync(request, HttpResponse.BodyHandlers.ofString()); CompletableFuture<HttpResponse<String>> response2 = HttpClient.newBuilder() .executor(executorService) .build() .sendAsync(request, HttpResponse.BodyHandlers.ofString());

默认执行器为Executors.newCachedThreadPool()。

6.7. CookieHandler

设置客户端级CookieHandler：

HttpClient.newBuilder() .cookieHandler(new CookieManager(null, CookiePolicy.ACCEPT_NONE)) .build();

若允许存储 Cookie，可从CookieManager读取：

((CookieManager) httpClient.cookieHandler().get()).getCookieStore();

7. HttpResponse

HttpResponse表示服务端响应，核心方法：

statusCode()：返回整型状态码；
body()：返回响应体（类型取决于发送时的BodyHandler）。

其他常用方法还包括uri()、headers()、trailers()与version()。

7.1. 响应的 URI

由于重定向，响应返回的uri()可能与请求不同：

assertThat(request.uri().toString(), equalTo("http://stackoverflow.com")); assertThat(response.uri().toString(), equalTo("https://stackoverflow.com/"));

7.2. 响应头

HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); HttpHeaders responseHeaders = response.headers();

7.3. 响应协议版本

即使请求设置为 HTTP/2，服务端也可能以 HTTP/1.1 响应，实际版本可从响应读取：

HttpRequest request = HttpRequest.newBuilder() .uri(new URI("https://postman-echo.com/get")) .version(HttpClient.Version.HTTP_2) .GET() .build(); HttpResponse<String> response = HttpClient.newHttpClient() .send(request, HttpResponse.BodyHandlers.ofString()); assertThat(response.version(), equalTo(HttpClient.Version.HTTP_1_1));

8. HTTP/2 推送承诺（Push Promise）

新的HttpClient通过PushPromiseHandler支持服务端主动推送。当客户端请求主资源时，服务器可以同时“推送”额外资源，从而减少往返次数、加快页面渲染。该能力得益于 HTTP/2 的多路复用。

如有推送承诺，将由提供的PushPromiseHandler处理；若传入null，则拒绝所有推送。

HttpClient的重载sendAsync可用于处理 push promise。先定义处理器：

private static PushPromiseHandler<String> pushPromiseHandler() { return (HttpRequest initiatingRequest, HttpRequest pushPromiseRequest, Function<HttpResponse.BodyHandler<String>, CompletableFuture<HttpResponse<String>>> acceptor) -> { acceptor.apply(BodyHandlers.ofString()) .thenAccept(resp -> { System.out.println("Pushed response: " + resp.uri() + ", headers: " + resp.headers()); }); System.out.println("Promise request: " + pushPromiseRequest.uri()); System.out.println("Promise request headers: " + pushPromiseRequest.headers()); }; }

再用sendAsync消费它：

httpClient.sendAsync(pageRequest, BodyHandlers.ofString(), pushPromiseHandler()) .thenAccept(pageResponse -> { System.out.println("Page response status code: " + pageResponse.statusCode()); System.out.println("Page response headers: " + pageResponse.headers()); String responseBody = pageResponse.body(); System.out.println(responseBody); }) .join();