模块 java.net.http
包 java.net.http

类 HttpClient

java.lang.Object
java.net.http.HttpClient
public abstract class HttpClient extends Object
一个 HTTP 客户端。

HttpClient 可用于发送 要求 并检索它们的 反应。 HttpClient 是通过 builder 创建的。 newBuilder 方法返回一个构建器，该构建器创建默认 HttpClient 实现的实例。构建器可用于配置每个客户端的状态，例如：首选协议版本（ HTTP/1.1 或 HTTP/2 ）、是否遵循重定向、代理、身份验证器等。一旦构建，HttpClient 是不可变的，并且可用于发送多个请求。

HttpClient 为通过它发送的所有请求提供配置信息和资源共享。

必须为每个发送的 HttpRequest 提供一个 BodyHandler 。 BodyHandler 确定如何处理响应正文（如果有）。收到 HttpResponse 后，标头、响应代码和正文（通常）可用。是否已读取响应主体字节取决于响应主体的类型 T 。

可以同步或异步发送请求：

Synchronous 示例

  HttpClient client = HttpClient.newBuilder()
    .version(Version.HTTP_1_1)
    .followRedirects(Redirect.NORMAL)
    .connectTimeout(Duration.ofSeconds(20))
    .proxy(ProxySelector.of(new InetSocketAddress("proxy.example.com", 80)))
    .authenticator(Authenticator.getDefault())
    .build();
  HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
  System.out.println(response.statusCode());
  System.out.println(response.body());

异步示例

  HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://foo.com/"))
    .timeout(Duration.ofMinutes(2))
    .header("Content-Type", "application/json")
    .POST(BodyPublishers.ofFile(Paths.get("file.json")))
    .build();
  client.sendAsync(request, BodyHandlers.ofString())
    .thenApply(HttpResponse::body)
    .thenAccept(System.out::println);

安全检查

如果存在安全管理器，则由 HTTP 客户端的发送方法执行安全检查。需要适当的 URLPermission 才能访问目标服务和代理服务（如果已配置的话）。访问代理所需的 URLPermission 形式具有 "CONNECT" 的 method 参数（用于所有类型的代理）和形式为 "socket://host:port" 的 URL 字符串，其中主机和端口指定代理的地址。

实现注意事项：
如果未为 HttpClient 设置显式 executor，并且已安装安全管理器，则默认执行程序将在未授予任何权限的上下文中执行异步和相关任务。自定义 请求正文发布者 、 响应体处理程序 、 响应主体订阅者 和 WebSocket 监听器 ，如果执行需要特权的操作，应该在适当的 特权上下文 内执行。
自从：
11

  • 构造方法详细信息

    • HttpClient

      protected HttpClient()
      创建一个 HttpClient。

  • 方法详情

    • newHttpClient

      public static HttpClient  newHttpClient()
      返回具有默认设置的新 HttpClient。

      相当于 newBuilder().build() 。

      默认设置包括：“GET”请求方法、HTTP/2 的首选项、NEVER 的重定向策略、默认代理选择器 和 默认 SSL 上下文。

      实现注意事项：
      在构建 HttpClient 实例时检索系统范围的默认值。在构建 HttpClient 实例后更改系统范围的值，例如，通过调用 ProxySelector.setDefault(ProxySelector) 或 SSLContext.setDefault(SSLContext) ，对已构建的实例没有影响。
      返回：
      一个新的 HttpClient
      抛出：
      UncheckedIOException - 如有必要，无法分配 建立一个新的HttpClient 所需的底层 IO 资源。

    • newBuilder

      public static HttpClient.Builder  newBuilder()
      创建一个新的 HttpClient 构建器。

      此方法返回的构建器创建默认 HttpClient 实现的实例。

      返回：
      HttpClient.Builder

    • cookieHandler

      public abstract Optional <CookieHandler > cookieHandler()
      返回包含此客户端的 CookieHandler 的 Optional。如果在此客户端的构建器中未设置 CookieHandler，则 Optional 为空。
      返回：
      一个 Optional 包含这个客户的 CookieHandler

    • connectTimeout

      public abstract Optional <Duration > connectTimeout()
      返回一个 Optional 包含连接超时时间对于这个客户。如果 连接超时时间 未在客户端的构建器中设置，则 Optional 为空。
      返回：
      一个 Optional 包含此客户端的连接超时持续时间

    • followRedirects

      public abstract HttpClient.Redirect  followRedirects()
      返回此客户端的以下重定向策略。未指定重定向策略的构建器构建的客户端的默认值为 NEVER 。
      返回：
      此客户的关注重定向设置

    • proxy

      public abstract Optional <ProxySelector > proxy()
      返回包含提供给此客户端的 ProxySelector 的 Optional。如果此客户端的构建器中未设置代理选择器，则 Optional 为空。

      即使此方法可能返回一个空的可选值， HttpClient 仍可能有一个未公开的 默认代理选择器 用于发送 HTTP 请求。

      返回：
      Optional 包含提供给此客户端的代理选择器。

    • sslContext

      public abstract SSLContext  sslContext()
      返回此客户的 SSLContext 。

      如果在此客户端的构建器中未设置 SSLContext，则返回 默认上下文。

      返回：
      此客户端的 SSLContext

    • sslParameters

      public abstract SSLParameters  sslParameters()
      返回此客户的 SSLParameters 的副本。

      如果在客户端的构建器中未设置SSLParameters，则返回客户端将使用的特定于实现的默认参数集。

      返回：
      这个客户的SSLParameters

    • authenticator

      public abstract Optional <Authenticator > authenticator()
      返回包含此客户端上的 Authenticator 集的 Optional。如果在客户端的构建器中没有设置 Authenticator，则 Optional 为空。
      返回：
      一个 Optional 包含这个客户的 Authenticator

    • version

      public abstract HttpClient.Version  version()
      返回此客户端的首选 HTTP 协议版本。默认值为HttpClient.Version.HTTP_2
      实现注意事项：
      约束也可能影响协议版本的选择。例如，如果通过代理请求 HTTP/2，如果实现不支持这种模式，则可以使用 HTTP/1.1
      返回：
      请求的 HTTP 协议版本

    • executor

      public abstract Optional <Executor > executor()
      返回包含此客户端的 Executor 的 Optional。如果在客户端的构建器中没有设置 Executor，则 Optional 为空。

      即使此方法可能返回一个空的可选值， HttpClient 仍可能有一个未公开的 默认执行者 用于执行异步和相关任务。

      返回：
      一个 Optional 包含这个客户的 Executor

    • send

      public abstract <T> HttpResponse <T> send(HttpRequest  request, HttpResponse.BodyHandler <T> responseBodyHandler) throws IOException , InterruptedException
      使用此客户端发送给定请求，必要时阻塞以获得响应。返回的 HttpResponse <T> 包含响应状态、标头和主体（由给定的响应主体处理程序处理）。

      如果操作中断，默认的 HttpClient 实现会尝试取消 HTTP 交换并抛出 InterruptedException 。不保证准确when取消请求可能会被考虑在内。特别是，请求可能仍会发送到服务，因为它的处理可能已经在另一个线程中异步开始，并且底层资源可能只会异步释放。

      • 使用 HTTP/1.1，尝试取消可能会导致基础连接突然关闭。
      • 使用 HTTP/2，尝试取消可能会导致流被重置，或者在某些情况下，也可能会导致连接突然关闭，例如，如果线程当前正在尝试写入底层套接字。
      类型参数：
      T - 响应主体类型
      参数：
      request - 请求
      responseBodyHandler - 响应主体处理程序
      返回：
      响应
      抛出：
      IOException - 如果在发送或接收时发生 I/O 错误
      InterruptedException - 如果操作中断
      IllegalArgumentException - 如果 request 参数不是可以按照 HttpRequest.Builder 指定的方式有效构建的请求。
      SecurityException - 如果安装了安全管理器并且它拒绝 access 给定请求中的 URL，或者代理（如果已配置）。有关详细信息，请参阅 安全检查。

    • sendAsync

      public abstract <T> CompletableFuture <HttpResponse <T>> sendAsync(HttpRequest  request, HttpResponse.BodyHandler <T> responseBodyHandler)
      使用此客户端和给定的响应主体处理程序异步发送给定的请求。

      相当于：sendAsync(request, responseBodyHandler, null)。

      类型参数：
      T - 响应主体类型
      参数：
      request - 请求
      responseBodyHandler - 响应主体处理程序
      返回：
      CompletableFuture<HttpResponse<T>>
      抛出：
      IllegalArgumentException - 如果 request 参数不是可以按照 HttpRequest.Builder 指定的方式有效构建的请求。

    • sendAsync

      public abstract <T> CompletableFuture <HttpResponse <T>> sendAsync(HttpRequest  request, HttpResponse.BodyHandler <T> responseBodyHandler, HttpResponse.PushPromiseHandler <T> pushPromiseHandler)
      使用具有给定响应主体处理程序和推送承诺处理程序的此客户端异步发送给定请求。

      返回的可完成未来，如果成功完成，将以 HttpResponse <T> 完成，其中包含响应状态、标头和正文（由给定的响应正文处理程序处理）。

      推动承诺 收到（如果有）由给定的 pushPromiseHandler 处理。 null 值 pushPromiseHandler 拒绝任何推送承诺。

      返回的可完成未来异常完成：

      默认的 HttpClient 实现返回 CompletableFuture 对象是 cancelable 。来自可取消期货的 CompletableFuture 对象 衍生的 本身就是 cancelable 。在未完成的可取消未来调用 cancel(true)，尝试取消 HTTP 交换以尽快释放底层资源。不保证准确when取消请求可能会被考虑在内。特别是，请求可能仍会发送到服务，因为它的处理可能已经在另一个线程中异步开始，并且底层资源可能只会异步释放。

      • 使用 HTTP/1.1，尝试取消可能会导致基础连接突然关闭。
      • 使用 HTTP/2，尝试取消可能会导致流被重置。
      类型参数：
      T - 响应主体类型
      参数：
      request - 请求
      responseBodyHandler - 响应主体处理程序
      pushPromiseHandler - 推送承诺处理程序，可能为空
      返回：
      CompletableFuture<HttpResponse<T>>
      抛出：
      IllegalArgumentException - 如果 request 参数不是可以按照 HttpRequest.Builder 指定的方式有效构建的请求。

    • newWebSocketBuilder

      public WebSocket.Builder  newWebSocketBuilder()
      创建一个新的 WebSocket 构建器（可选操作）。

      示例

        HttpClient client = HttpClient.newHttpClient();
  CompletableFuture<WebSocket> ws = client.newWebSocketBuilder()
      .buildAsync(URI.create("ws://websocket.example.com"), listener);

      可以通过使用自定义 HttpClient 来实现对 WebSocket 打开握手的更好控制。

      示例

        InetSocketAddress addr = new InetSocketAddress("proxy.example.com", 80);
  HttpClient client = HttpClient.newBuilder()
      .proxy(ProxySelector.of(addr))
      .build();
  CompletableFuture<WebSocket> ws = client.newWebSocketBuilder()
      .buildAsync(URI.create("ws://websocket.example.com"), listener);
      实现要求：
      此方法的默认实现抛出 UnsupportedOperationException 。通过 newHttpClient() 或 newBuilder() 获得的客户端返回一个 WebSocket 构建器。
      实现注意事项：
      构建器和用它创建的 WebSocket 都以非阻塞方式运行。也就是说，它们的方法在返回 CompletableFuture 之前不会阻塞。异步任务在这个 HttpClient 的执行器中执行。

      当从 Listener.onClose 返回的 CompletionStage 完成时，WebSocket 将发送一个 Close 消息，该消息具有与接收到的消息相同的代码和一个空的原因。

      返回：
      WebSocket.Builder
      抛出：
      UnsupportedOperationException - 如果这个 HttpClient 不提供 WebSocket 支持