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

接口 HttpRequest.Builder

封闭类：
HttpRequest
public static interface HttpRequest.Builder
HTTP 请求 的建设者。

HttpRequest.Builder 的实例是通过调用 HttpRequest.newBuilder() 、 HttpRequest.newBuilder(URI) 或 HttpRequest.newBuilder(HttpRequest, BiPredicate) 创建的。

构建器可用于配置每个请求的状态，例如：请求 URI、请求方法（除非明确设置，否则默认为 GET）、特定请求标头等。每个设置方法都会修改构建器的状态并返回同一个实例。这些方法不是同步的，不应该在没有外部同步的情况下从多个线程调用。 build 方法每次被调用时都会返回一个新的 HttpRequest。一旦构建， HttpRequest 是不可变的，可以多次发送。

请注意，并非所有请求标头都可以由用户代码设置。有些是出于安全原因而受到限制，而其他一些（例如与身份验证、重定向和 cookie 管理相关的标头）可能由特定的 API 管理，而不是通过直接用户设置的标头。

自从：
11

  • 方法详情

    • uri

      HttpRequest.Builder  uri(URI  uri)
      设置此 HttpRequest 的请求 URI。
      参数：
      uri - 请求 URI
      返回：
      这个建设者
      抛出：
      IllegalArgumentException - 如果不支持 URI 方案

    • expectContinue

      HttpRequest.Builder  expectContinue(boolean enable)
      请求服务在发送正文之前确认请求。默认情况下禁用。如果启用，则请求服务在客户端发送请求正文之前发送错误响应或100 Continue响应。这意味着在收到此临时响应之前不会调用请求的请求发布者。
      参数：
      enable - true 如果 Expect 继续发送
      返回：
      这个建设者

    • version

      HttpRequest.Builder  version(HttpClient.Version  version)
      为此请求设置首选HttpClient.Version 。

      应检查相应的HttpResponse 是否为实际使用的版本。如果未在请求中设置版本，则请求的版本将是发送 HttpClient 的版本。

      参数：
      version - 请求的 HTTP 协议版本
      返回：
      这个建设者

    • header

      HttpRequest.Builder  header(String  name, String  value)
      将给定的名称值对添加到此请求的标头集中。给定的值被添加到该名称的值列表中。
      实现注意事项：
      实现可能会选择限制某些标头名称或值，因为 HTTP 客户端可能会自行确定它们的值。例如，“Content-Length”，这将由请求发布者确定。在这种情况下，HttpRequest.Builder 的实现可能会选择抛出一个 IllegalArgumentException 如果这样的标头被传递给构建器。
      参数：
      name - 标头名称
      value - 标头值
      返回：
      这个建设者
      抛出：
      IllegalArgumentException - 如果标头名称或值无效，请参阅 RFC 7230 第 3.2 节 ，或者标头名称或值受实现限制。

    • headers

      HttpRequest.Builder  headers(String ... headers)
      将给定的名称值对添加到此请求的标头集中。提供的 String 实例必须交替作为标头名称和标头值。要将多个值添加到相同的名称，则必须为每个新值提供相同的名称。
      参数：
      headers - 名称值对列表
      返回：
      这个建设者
      抛出：
      IllegalArgumentException - 如果有奇数个参数，或者如果标头名称或值无效，请参阅 RFC 7230 第 3.2 节 ，或者标头名称或值是 受限制的 由实现。

    • timeout

      HttpRequest.Builder  timeout(Duration  duration)
      为此请求设置超时。如果在指定的超时时间内未收到响应，则从 HttpClient::send 抛出 HttpTimeoutException 或 HttpClient::sendAsync 异常完成并带有 HttpTimeoutException 。不设置超时的效果和设置一个无限大的Duration是一样的，即永远阻塞。
      参数：
      duration - 超时持续时间
      返回：
      这个建设者
      抛出：
      IllegalArgumentException - 如果持续时间为非正数

    • setHeader

      HttpRequest.Builder  setHeader(String  name, String  value)
      将给定的名称值对设置为此请求的标头集。这会重写之前为名称设置的任何值。
      参数：
      name - 标头名称
      value - 标头值
      返回：
      这个建设者
      抛出：
      IllegalArgumentException - 如果标头名称或值无效，请参阅 RFC 7230 第 3.2 节 ，或者标头名称或值是 受限制的 由实现。

    • GET

      HttpRequest.Builder  GET()
      将此构建器的请求方法设置为 GET。这是默认值。
      返回：
      这个建设者

    • POST

      HttpRequest.Builder  POST(HttpRequest.BodyPublisher  bodyPublisher)
      将此构建器的请求方法设置为 POST，并将其请求正文发布者设置为给定值。
      参数：
      bodyPublisher - 主体发布者
      返回：
      这个建设者

    • PUT

      HttpRequest.Builder  PUT(HttpRequest.BodyPublisher  bodyPublisher)
      将此构建器的请求方法设置为 PUT，并将其请求正文发布者设置为给定值。
      参数：
      bodyPublisher - 主体发布者
      返回：
      这个建设者

    • DELETE

      HttpRequest.Builder  DELETE()
      将此构建器的请求方法设置为 DELETE。
      返回：
      这个建设者

    • HEAD

      default HttpRequest.Builder  HEAD()
      将此构建器的请求方法设置为 HEAD。
      实现要求：
      默认实现预期具有与以下相同的行为：return method("HEAD", BodyPublishers.noBody());
      返回：
      这个建设者
      自从：
      18

    • method

      HttpRequest.Builder  method(String  method, HttpRequest.BodyPublisher  bodyPublisher)
      将此构建器的请求方法和请求主体设置为给定值。
      API 注意：
      noBody 请求主体发布者可以在不需要或不适合请求主体的情况下使用。方法是否受限是特定于实现的。例如，某些实现可能会选择限制 CONNECT 方法。
      参数：
      method - 使用方法
      bodyPublisher - 主体发布者
      返回：
      这个建设者
      抛出：
      IllegalArgumentException - 如果方法名称无效，请参阅 RFC 7230 第 3.1.1 节 ，或者该方法受实现限制。

    • build

      HttpRequest  build()
      构建并返回一个 HttpRequest 。
      实现要求：
      每次调用此方法时都会返回一个新的 HttpRequest。构建后，HttpRequest 是不可变的，可以多次发送。
      返回：
      一个新的HttpRequest
      抛出：
      IllegalStateException - 如果未设置 URI

    • copy

      HttpRequest.Builder  copy()
      根据当前状态返回此 Builder 的精确副本。然后可以独立于此构建器修改新构建器。
      返回：
      此构建器的精确副本