Module bus.http
Package org.miaixz.bus.http

Class Response

java.lang.Object
org.miaixz.bus.http.Response
All Implemented Interfaces:
Closeable, AutoCloseable
public class Response extends Object implements Closeable
HTTP 响应类，封装 HTTP 响应的所有信息，包括请求、协议、状态码、头部、响应体等。

注意：除响应体外，所有属性都是不可变的。响应体是一次性资源，必须在读取后关闭，且只能消费一次。

Since:
Java 17+
Author:
Kimi Liu

  • Method Details

    • request

      public Request request()
      获取发起此响应的原始请求。

      注意：此请求可能与应用程序发出的请求不同，可能被 HTTP 客户端修改（如添加 Content-Length 头部） 或因重定向/认证生成新请求（URL 可能不同）。

      Returns:
      发起响应的 Request 对象

    • protocol

      public org.miaixz.bus.core.net.Protocol protocol()
      获取使用的 HTTP 协议。
      Returns:
      协议，如 HTTP/1.1、HTTP/2

    • code

      public int code()
      获取 HTTP 状态码。
      Returns:
      状态码（如 200、404）

    • isSuccessful

      public boolean isSuccessful()
      检查响应是否成功（状态码在 [200..300) 范围内）。
      Returns:
      true 如果请求被成功接收、理解和接受

    • message

      public String message()
      获取 HTTP 状态消息。
      Returns:
      状态消息（如 "OK"、"Not Found"）

    • handshake

      public Handshake handshake()
      获取 TLS 握手信息。
      Returns:
      Handshake 对象（非 TLS 连接为 null）

    • headers

      public List<String> headers(String name)
      获取指定名称的头部值列表。
      Parameters:
      name - 头部名称
      Returns:
      头部值列表（可能为空）

    • header

      public String header(String name)
      获取指定名称的第一个头部值。
      Parameters:
      name - 头部名称
      Returns:
      头部值（不存在时为 null）

    • header

      public String header(String name, String defaultValue)
      获取指定名称的第一个头部值，带默认值。
      Parameters:
      name - 头部名称
      defaultValue - 默认值（不存在时返回）
      Returns:
      头部值或默认值

    • headers

      public Headers headers()
      获取所有响应头部。
      Returns:
      Headers 对象

    • trailers

      public Headers trailers() throws IOException
      获取响应尾部（trailer headers）。

      注意：必须在响应体完全消费后调用，否则抛出 IllegalStateException。

      Returns:
      尾部 Headers 对象（可能为空）
      Throws:
      IOException - 如果无法获取尾部
      IllegalStateException - 如果响应体未完全消费

    • peekBody

      public ResponseBody peekBody(long byteCount) throws IOException
      预览响应体内容，最多读取指定字节数。

      返回新的 ResponseBody，包含最多 byteCount 字节的响应体内容。如果响应体不足 byteCount 字节， 返回全部内容；如果超过，则截断。

      注意：此方法会将请求的字节加载到内存，建议设置合理的 byteCount（如 1MB）。 在响应体消费后调用会抛出错误。

      Parameters:
      byteCount - 最大预览字节数
      Returns:
      新的 ResponseBody 对象
      Throws:
      IOException - 如果读取响应体失败

    • body

      public ResponseBody body()
      获取响应体。

      注意：响应体是一次性资源，必须关闭且只能消费一次。对于 cacheResponse、networkResponse、 priorResponse 返回的响应，此方法返回 null。

      Returns:
      ResponseBody 对象（可能为 null）

    • newBuilder

      public Response.Builder newBuilder()
      创建新的 Builder 实例，基于当前 Response。
      Returns:
      Builder 实例

    • isRedirect

      public boolean isRedirect()
      检查响应是否为重定向。
      Returns:
      true 如果状态码表示重定向（300、301、302、303、307、308）

    • networkResponse

      public Response networkResponse()
      获取网络响应。

      如果响应直接从网络获取（未使用缓存），返回原始响应；否则返回 null。 返回的响应体不应被读取。

      Returns:
      网络 Response 对象（可能为 null）

    • cacheResponse

      public Response cacheResponse()
      获取缓存响应。

      如果响应从缓存获取，返回缓存响应；否则返回 null。对于条件 GET 请求， 可能同时存在缓存和网络响应。返回的响应体不应被读取。

      Returns:
      缓存 Response 对象（可能为 null）

    • priorResponse

      public Response priorResponse()
      获取前一个响应。

      如果响应由重定向或认证挑战触发，返回前一个响应；否则返回 null。 返回的响应体不应被读取（已消费）。

      Returns:
      前一个 Response 对象（可能为 null）

    • challenges

      public List<Challenge> challenges()
      获取 RFC 7235 认证挑战列表。

      对于状态码 401（未授权），返回 "WWW-Authenticate" 挑战； 对于状态码 407（代理未授权），返回 "Proxy-Authenticate" 挑战； 其他状态码返回空列表。

      Returns:
      认证挑战列表（可能为空）

    • cacheControl

      public CacheControl cacheControl()
      获取缓存控制指令。

      即使响应不包含 "Cache-Control" 头部，也返回非 null 的 CacheControl 对象。 使用延迟初始化以提高性能。

      Returns:
      CacheControl 对象

    • sentRequestAtMillis

      public long sentRequestAtMillis()
      获取发送请求的时间戳。
      Returns:
      发送请求的毫秒时间戳（System.currentTimeMillis）

    • receivedResponseAtMillis

      public long receivedResponseAtMillis()
      获取接收响应头部的时间戳。
      Returns:
      接收响应的毫秒时间戳（System.currentTimeMillis）

    • close

      public void close()
      关闭响应体。

      等价于调用 body().close()。对于无响应体的响应（如 cacheResponse、 networkResponse、priorResponse），调用会抛出异常。

      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IllegalStateException - 如果响应无响应体

    • toString

      public String toString()
      返回响应的字符串表示。
      Overrides:
      toString in class Object
      Returns:
      包含协议、状态码、消息和 URL 的字符串