HttpClient：标准化的 HTTP/1.1 与 HTTP/2 客户端

从 incubator 到标准模块01

HttpClient 最早以 incubator 形式出现在 JDK 9（JEP 110），模块名是 jdk.incubator.http，包名是 jdk.incubator.http。JDK 11 的 JEP 321 把它标准化为 java.net.http，API 也做了调整。JDK 10 里它仍然是 incubator，不能用 --release 10 编译 java.net.http。

java --describe-module java.net.http

java.net.http@11.0.28
exports java.net.http
requires java.base mandated

模块只导出 java.net.http，实现位于 jdk.internal.net.http，不属于公共 API。不要 import 或依赖内部类；升级 JDK 时它们随时可能变化。

javac --release 10 HttpApi.java

HttpApi.java:1: error: package java.net.http does not exist
import java.net.http.*;
^
HttpApi.java:4: error: cannot find symbol
        System.out.println(HttpClient.newHttpClient().version());
                           ^
  symbol:   variable HttpClient

三个对象：Client、Request、Response02

HttpClient 持有配置与连接池，HttpRequest 描述一次请求，HttpResponse 由 BodyHandler 决定响应体类型。Client 和 Request 都是不可变对象，可以安全复用。

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

public class HttpGet {
    public static void main(String[] args) throws Exception {
        HttpClient client = HttpClient.newBuilder()
                .connectTimeout(Duration.ofSeconds(2))
                .build();

        HttpRequest request = HttpRequest.newBuilder(URI.create("http://127.0.0.1:8080/hello"))
                .timeout(Duration.ofSeconds(5))
                .header("Accept", "text/plain")
                .GET()
                .build();

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

        System.out.println(response.statusCode());
        System.out.println(response.body());
        System.out.println(response.version());
    }
}

这段代码假设本地 8080 端口有一个返回 hello 的服务；本文后面的「连接池」示例会启动一个真实的本地 HttpServer。响应状态、body 和协议版本都由服务端决定。

• HttpClient.newHttpClient() 使用默认配置；需要超时、代理、认证、重定向策略时用 newBuilder()。
• HttpRequest.newBuilder(URI) 必须传 URI；GET()、POST(BodyPublisher)、PUT、DELETE 等方法二选一。
• BodyHandlers.ofString() 把响应体解码为字符串；还有 ofByteArray、ofFile、ofLines、discarding。
• response.headers() 是大小写不敏感的 HttpHeaders；用 firstValue("X-Test") 取第一个值。

sendAsync 与 CompletableFuture03

send 会阻塞调用线程直到响应完成；sendAsync 立刻返回 CompletableFuture<HttpResponse<T>>，由客户端内部线程池完成。两者走同一条异步 I/O 管线，区别只在调用方是否等待。

CompletableFuture<HttpResponse<String>> future =
        client.sendAsync(request, HttpResponse.BodyHandlers.ofString());

CompletableFuture<String> body = future
        .thenApply(HttpResponse::body)
        .exceptionally(e -> "fallback: " + e.getClass().getSimpleName());

System.out.println(body.get(2, TimeUnit.SECONDS));

返回的 CompletableFuture 在客户端 executor 上完成，不保证在调用线程执行。需要控制后续阶段使用哪个线程池时，用 thenApplyAsync(fn, executor) 显式传入 executor。

连接池：复用发生在 TCP 层04

HttpClient 内部维护连接池。HTTP/1.1 使用 keep-alive 复用连接；HTTP/2 在一条连接上多路复用多个 stream。连接池按目标地址、代理和 TLS 配置区分，属于单个 client 实例。

import com.sun.net.httpserver.HttpServer;
import java.io.OutputStream;
import java.net.InetSocketAddress;
import java.net.URI;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.util.Set;
import java.util.concurrent.*;

public class HttpPool {
    static final Set<Integer> PORTS = ConcurrentHashMap.newKeySet();

    public static void main(String[] args) throws Exception {
        HttpServer server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0);
        server.createContext("/", ex -> {
            PORTS.add(ex.getRemoteAddress().getPort());
            byte[] body = "ok".getBytes(StandardCharsets.UTF_8);
            ex.sendResponseHeaders(200, body.length);
            try (OutputStream os = ex.getResponseBody()) { os.write(body); }
        });
        server.start();

        String url = "http://127.0.0.1:" + server.getAddress().getPort() + "/";
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder(URI.create(url)).GET().build();

        client.send(request, HttpResponse.BodyHandlers.ofString());
        int before = PORTS.size();
        for (int i = 0; i < 5; i++) {
            client.send(request, HttpResponse.BodyHandlers.ofString());
        }
        System.out.println("ports.before=" + before + " after=" + PORTS.size());
        server.stop(0);
    }
}

ports.before=1 after=1

服务端按远端端口计数连接。预热后连续 5 次请求没有新增端口，说明连接被复用了。这个结果只证明 HTTP/1.1 的 keep-alive 复用；HTTP/2 的多路复用需要服务端支持 ALPN 或 h2c。

超时、重定向与受限请求头05

HttpClient 的默认值有几个容易记错的点：不跟重定向、没有默认超时、请求版本默认 HTTP/2。服务端不支持 HTTP/2 时会回落到 HTTP/1.1，但响应 version() 会告诉你实际用了什么。

HttpRequest slow = HttpRequest.newBuilder(URI.create(base + "/slow"))
        .timeout(Duration.ofMillis(100))
        .GET()
        .build();

try {
    client.send(slow, HttpResponse.BodyHandlers.ofString());
} catch (HttpTimeoutException e) {
    System.out.println("timeout=" + e.getClass().getSimpleName());
}

timeout=HttpTimeoutException

重定向默认不跟随。HttpClient.Redirect.NORMAL 会跟随 301/302/303/307/308，但不会把 HTTPS 降到 HTTP；ALWAYS 则连这种降级也跟随。

HttpClient follower = HttpClient.newBuilder()
        .followRedirects(HttpClient.Redirect.NORMAL)
        .build();

有些请求头由客户端管理，直接设置会抛 IllegalArgumentException。JDK 11 的受限头包括 Host、Connection、Content-Length、Expect、Upgrade 等；确有需要时可用系统属性 jdk.httpclient.allowRestrictedHeaders 放开，但不建议。

HttpRequest.newBuilder(uri).header("Host", "example.com").GET().build();

java.lang.IllegalArgumentException

try (HttpClient client = HttpClient.newHttpClient()) {
    // ...
}

error: incompatible types: try-with-resources not applicable to variable type
        try (HttpClient client = HttpClient.newHttpClient()) {
                        ^
    (HttpClient cannot be converted to AutoCloseable)

版本边界BOUNDARY

这张表比 API 本身更值得记。写代码时先确认你的运行时版本。

费曼自检SELF CHECK

先合上页面，用自己的话回答，再展开对照。能讲出因果和反例，才算真正掌握。