Class HttpRequest

java.lang.Object
com.sure.tool.http.HttpRequest

public class HttpRequest extends Object
HTTP 请求(链式构建):URL/请求头/query/表单/body/超时/重定向,基于 HttpURLConnection 的零依赖封装, 参考 Hutool 的 HttpRequest 设计。
String body = HttpRequest.get("https://api.example.com/users")
        .query("page", 1)
        .header("Authorization", "Bearer xxx")
        .execute().body();
与 HttpUtil 的差异:execute() 不因非 2xx 状态码抛异常,响应状态由 HttpResponse.isOk() 判断。

English: A fluent HTTP request builder with headers, query parameters and body handling.

Since:
0.1.0
Author:
suretool
  • Field Details

    • DEFAULT_CONNECT_TIMEOUT

      public static final int DEFAULT_CONNECT_TIMEOUT
      默认连接超时(毫秒)
      See Also:
    • DEFAULT_READ_TIMEOUT

      public static final int DEFAULT_READ_TIMEOUT
      默认读取超时(毫秒)
      See Also:
  • Method Details

    • get

      public static HttpRequest get(String url)
      GET 请求。
      Parameters:
      url - URL
      Returns:
      请求构建器
    • post

      public static HttpRequest post(String url)
      POST 请求。
      Parameters:
      url - URL
      Returns:
      请求构建器
    • put

      public static HttpRequest put(String url)
      PUT 请求。
      Parameters:
      url - URL
      Returns:
      请求构建器
    • delete

      public static HttpRequest delete(String url)
      DELETE 请求。
      Parameters:
      url - URL
      Returns:
      请求构建器
    • of

      public static HttpRequest of(String url, String method)
      任意方法请求(JDK HttpURLConnection 仅支持 GET/POST/PUT/DELETE/HEAD/OPTIONS/TRACE 等标准方法, 传入 PATCH 等 JDK 不支持的方法将在 execute() 时抛 HttpException)。
      Parameters:
      url - URL
      method - HTTP 方法(自动转大写)
      Returns:
      请求构建器
    • url

      public HttpRequest url(String url)
      修改 URL。
      Parameters:
      url - URL
      Returns:
      本构建器
    • method

      public HttpRequest method(String method)
      修改 HTTP 方法(自动转大写)。
      Parameters:
      method - HTTP 方法
      Returns:
      本构建器
    • header

      public HttpRequest header(String name, Object value)
      添加请求头(同名覆盖)。
      Parameters:
      name - 头名
      value - 头值
      Returns:
      本构建器
    • header

      public HttpRequest header(Map<String,?> headers)
      批量添加请求头。
      Parameters:
      headers - 请求头
      Returns:
      本构建器
    • query

      public HttpRequest query(String name, Object value)
      添加 query 参数(GET 拼接 URL,值会 URL 编码)。
      Parameters:
      name - 参数名
      value - 参数值
      Returns:
      本构建器
    • query

      public HttpRequest query(Map<String,Object> params)
      批量添加 query 参数。
      Parameters:
      params - 参数
      Returns:
      本构建器
    • form

      public HttpRequest form(String name, Object value)
      添加表单参数(POST 发送 application/x-www-form-urlencoded,值会 URL 编码)。 值为 File 时自动转入文件字段,请求升级为 multipart/form-data 编码。
      Parameters:
      name - 参数名
      value - 参数值或文件
      Returns:
      本构建器
    • form

      public HttpRequest form(String name, File... files)
      添加文件字段(multipart/form-data),支持同一字段多个文件。 注意:字面量 null 会被 Java 重载决议选中本方法(较具体), 此时视为空值文本字段(输出 name=),与 form(String, Object) 契约一致。
      Parameters:
      name - 字段名
      files - 文件(可多个,可空数组)
      Returns:
      本构建器
      Since:
      1.7.0
    • formFiles

      public HttpRequest formFiles(Map<String,File> files)
      批量添加文件字段(每字段一个文件)。
      Parameters:
      files - 字段名 → 文件映射
      Returns:
      本构建器
      Since:
      1.7.0
    • form

      public HttpRequest form(Map<String,Object> params)
      批量添加表单参数。
      Parameters:
      params - 参数
      Returns:
      本构建器
    • body

      public HttpRequest body(String body)
      设置请求体(文本,默认 Content-Type 为 application/json;与 form 同时设置时 body 优先)。
      Parameters:
      body - 请求体
      Returns:
      本构建器
    • body

      public HttpRequest body(String body, String contentType)
      设置请求体(文本 + 显式 Content-Type)。
      Parameters:
      body - 请求体
      contentType - Content-Type
      Returns:
      本构建器
    • body

      public HttpRequest body(byte[] body)
      设置请求体(字节,默认 Content-Type 为 application/octet-stream)。
      Parameters:
      body - 请求体
      Returns:
      本构建器
    • body

      public HttpRequest body(byte[] body, String contentType)
      设置请求体(字节 + 显式 Content-Type)。
      Parameters:
      body - 请求体(内部防御性拷贝)
      contentType - Content-Type
      Returns:
      本构建器
    • contentType

      public HttpRequest contentType(String contentType)
      显式设置 Content-Type(覆盖 body/form 推断的默认值)。
      Parameters:
      contentType - Content-Type
      Returns:
      本构建器
    • timeout

      public HttpRequest timeout(int timeoutMillis)
      同时设置连接与读取超时(毫秒)。
      Parameters:
      timeoutMillis - 超时(毫秒)
      Returns:
      本构建器
    • connectTimeout

      public HttpRequest connectTimeout(int timeoutMillis)
      设置连接超时(毫秒)。
      Parameters:
      timeoutMillis - 超时(毫秒)
      Returns:
      本构建器
    • readTimeout

      public HttpRequest readTimeout(int timeoutMillis)
      设置读取超时(毫秒)。
      Parameters:
      timeoutMillis - 超时(毫秒)
      Returns:
      本构建器
    • followRedirects

      public HttpRequest followRedirects(boolean followRedirects)
      是否自动跟随重定向(默认 true)。
      Parameters:
      followRedirects - 是否跟随
      Returns:
      本构建器
    • userAgent

      public HttpRequest userAgent(String userAgent)
      设置 User-Agent(默认 suretool/0.1)。
      Parameters:
      userAgent - User-Agent
      Returns:
      本构建器
    • proxy

      public HttpRequest proxy(String host, int port)
      设置代理(主机 + 端口,HTTP 代理)。
      Parameters:
      host - 代理主机
      port - 代理端口
      Returns:
      本构建器
    • proxy

      public HttpRequest proxy(Proxy proxy)
      设置代理(任意 Proxy,支持 HTTP/SOCKS)。
      Parameters:
      proxy - 代理
      Returns:
      本构建器
    • cookie

      public HttpRequest cookie(String name, Object value)
      设置 Cookie(单对键值)。
      Parameters:
      name - Cookie 名
      value - Cookie 值
      Returns:
      本构建器
    • cookie

      public HttpRequest cookie(String cookie)
      设置 Cookie 头(原始值,如 "name=value; Path=/")。
      Parameters:
      cookie - Cookie 头原文
      Returns:
      本构建器
    • cookieStore

      public HttpRequest cookieStore(CookieStore store)
      绑定会话级 Cookie 管理器:请求自动携带 store 内 Cookie,响应中的 Set-Cookie 自动收集。
      Parameters:
      store - Cookie 管理器(可为空,表示不启用会话保持)
      Returns:
      本构建器
    • client

      public HttpRequest client(HttpClient httpClient)
      注入 JDK HttpClient(自带连接池/keep-alive 复用,虚拟线程友好)。 注入后 execute() 走 HttpClient 引擎;未注入时走 HttpURLConnection。
      Parameters:
      httpClient - JDK HttpClient
      Returns:
      本构建器
    • pool

      public HttpRequest pool(HttpClientBuilder builder)
      便捷注入:通过 HttpClientBuilder 构建带连接池的 JDK HttpClient。
      Parameters:
      builder - 连接池构建器
      Returns:
      本构建器
    • execute

      public HttpResponse execute()
      执行请求。网络错误抛 HttpException;非 2xx 状态码不抛异常,由 HttpResponse.isOk() 判断。
      Returns:
      响应