Module java.net.http
Package java.net.http

Interface HttpRequest.Builder

封闭类:
HttpRequest
public static interface HttpRequest.Builder
HTTP请求的构建器。

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

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

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

自 JDK 版本:
11

  • Method Details

    • uri

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

    • expectContinue

      HttpRequest.Builder expectContinue(boolean enable)
      请求服务器在发送主体之前确认请求。默认情况下已禁用。如果启用，则请求服务器在客户端发送请求主体之前发送错误响应或100 Continue响应。这意味着在接收到这个临时响应之前，请求的发布器不会被调用。
      参数:
      enable - 如果要发送Expect continue，则为true
      返回:
      此构建器

    • 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 - 超时持续时间
      返回:
      此构建器
      抛出:
      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());相同的行为。
      返回:
      此构建器
      自 JDK 版本:
      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的精确副本。然后可以独立于此构建器修改新构建器。
      返回:
      此构建器的精确副本