Java HttpClient 通过 ProxySelector 配置代理连接

Java 的 JDK HttpClient 配置代理，核心不是给 HttpRequest 添加一个代理字段，而是在构建客户端时调用 HttpClient.Builder.proxy(ProxySelector)。固定代理可以直接使用 ProxySelector.of；需要明确绕过系统代理时使用 HttpClient.Builder.NO_PROXY。这样得到的 HttpClient 可以复用，代理策略也不会散落在每个请求里。

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

先把代理配置放在正确的对象上

HttpClient 的 Builder 可以设置协议版本、重定向、认证器和代理选择器，客户端构建完成后是不可变对象，适合被多个请求复用。相对地，HttpRequest.Builder 负责 URI、方法、请求头和单个请求的超时，不提供代理选择入口。

因此，下面的结构关系更接近实际设计：请求提交给客户端，客户端持有代理选择策略，策略再决定直连或代理地址。代理配置的变化通常意味着构建另一个客户端，而不是修改已经构建的实例。

用 ProxySelector.of 配置固定代理

如果所有请求都应经过同一台 HTTP 代理，可以把代理地址交给 ProxySelector.of。示例使用文档中的标准 API，不在代码里运行代理连接；真正可用的主机和端口应替换为部署环境提供的值。

import java.net.InetSocketAddress;
import java.net.ProxySelector;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

// 代理只配置在客户端，后续请求可以共享同一套连接策略。
HttpClient client = HttpClient.newBuilder()
        // 把代理主机和端口替换成当前网络环境的配置。
        .proxy(ProxySelector.of(new InetSocketAddress("proxy.example.com", 8080)))
        .build();

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create("https://api.example.com/data"))
        .GET()
        .build();

// send 会沿用 client 的 ProxySelector；响应状态仍需由业务代码判断。
HttpResponse response = client.send(
        request, HttpResponse.BodyHandlers.ofString());
if (response.statusCode() >= 400) {
    // HTTP 错误不是 Java 异常，按业务需要记录或转换。
    throw new IllegalStateException("HTTP status: " + response.statusCode());
}

这里的 ProxySelector.of 表示单一代理选择器。它不会替你完成代理账号认证，也不会把 HTTP 状态码自动当成异常；网络连接失败、代理不可达等问题仍由 send 或 sendAsync 的异常结果体现。

不想走代理时显式使用 NO_PROXY

未调用 proxy 时，JDK 实现可能使用默认代理选择器及系统代理属性。若某个客户端必须直连，直接传入 HttpClient.Builder.NO_PROXY，比依赖机器当前的环境变量或系统设置更清楚。

import java.net.http.HttpClient;

// 明确禁用代理，避免系统默认 ProxySelector 影响这个客户端。
HttpClient directClient = HttpClient.newBuilder()
        .proxy(HttpClient.Builder.NO_PROXY)
        .build();

// directClient 的请求仍可设置请求级 timeout，但那和代理选择是两件事。

可以把代理和直连客户端看成两种稳定配置：同一组请求若需要切换网络出口，按配置创建并复用对应的客户端；不要在循环里为每个 URL 临时 new 一个客户端，否则连接池复用和资源管理都会变得难以观察。

多目标请求再使用自定义 ProxySelector

当不同 URI 需要不同代理时，固定的 ProxySelector.of 就不够了。可以实现 ProxySelector.select(URI)，根据目标 URI 返回代理列表；返回 Proxy.NO_PROXY 表示该目标直连。实现时要把规则写成可测试的配置对象，并在 connectFailed 中记录失败，而不是静默切换到未经允许的出口。

无论使用哪种选择器，代理策略都由客户端持有。自定义选择器只负责选择代理，不等于代理认证器；如果环境需要 HTTP 基本认证，还要单独评估 Authenticator 和凭据的安全保存方式。

上线前的四项检查

还要注意 Builder 本身不是线程安全对象，不应在多个线程中共同修改；构建完成后的 HttpClient 才适合被多个请求共享。代理地址、认证信息和失败原因属于运行配置，生产环境应放在受控配置中心或密钥管理系统中。

常见问题

HttpRequest 能不能单独指定代理？

JDK HttpClient API 的代理选择入口在 HttpClient.Builder。若请求需要不同代理，通常按路由策略使用自定义 ProxySelector，或使用不同配置构建客户端。

NO_PROXY 会不会修改系统代理设置？

不会。它只让当前构建的 HttpClient 使用直连选择器，不会改变操作系统或其他客户端的代理属性。

配置代理后还需要设置 connectTimeout 吗？

需要时应单独设置。代理连接建立、请求响应等待和业务重试是不同边界，不能用代理配置替代超时策略。