HTTP 请求 - HttpRequest

简介

HttpRequest 是 Hutool 提供的一个用于构建和发送 HTTP 请求的工具类。相较于 HttpUtil 中的简单封装，HttpRequest 提供了更灵活的配置和使用方式，支持自定义请求头、表单参数、代理设置、超时控制等。通过链式调用，可以轻松构建和发送复杂的 HTTP 请求，并获取响应结果。

1. 构建普通表单请求 - form

在需要发送带有表单参数的 POST 请求时，可以使用 form 方法将参数添加到请求中。请求参数可以是 Map 或者 Bean，Hutool 会自动进行参数的格式化和编码。

示例：构建普通表单请求

import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.http.Header;
import cn.hutool.core.lang.Console;

import java.util.HashMap;

public class HttpRequestExample {
    public static void main(String[] args) {
        // 构建表单参数
        HashMap<String, Object> paramMap = new HashMap<>();
        paramMap.put("username", "testUser");
        paramMap.put("password", "testPass");

        // 发送 POST 请求并获取响应
        HttpResponse response = HttpRequest.post("https://example.com/login")
            .header(Header.USER_AGENT, "Hutool http") // 设置请求头
            .form(paramMap) // 设置表单内容
            .timeout(20000) // 设置超时时间，单位为毫秒
            .execute(); // 执行请求

        // 获取响应内容
        String result = response.body();
        Console.log("响应内容: {}", result);
    }
}

• form(Map<String, Object> paramMap)：设置表单内容，支持 Map 或 Bean。
  • paramMap：请求参数，以 key-value 形式存储。
  • 返回值：返回 HttpRequest 对象，用于链式调用。

作用： 用于发送带有表单参数的 POST 请求，适用于登录、数据提交等场景。

实际开发场景： 在处理用户登录、注册等需要提交表单数据的接口时，可以使用该方法构建请求。

2. 构建 RESTful 请求 - body

在 RESTful 接口中，通常需要发送 JSON 数据作为请求体。可以使用 body 方法直接传入 JSON 字符串，并通过 POST、PUT 等请求方法发送。

示例：构建 RESTful 请求

import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.core.lang.Console;

public class RestRequestExample {
    public static void main(String[] args) {
        // 构建 JSON 请求体
        String json = "{\"name\":\"testUser\", \"age\":25}";

        // 发送 POST 请求并获取响应
        HttpResponse response = HttpRequest.post("https://example.com/api/user")
            .body(json) // 设置请求体内容
            .execute(); // 执行请求

        // 获取响应内容
        String result = response.body();
        Console.log("响应内容: {}", result);
    }
}

• body(String body)：设置请求体内容，通常为 JSON、XML 等字符串格式。
  • body：请求体内容，可以是任意字符串。
  • 返回值：返回 HttpRequest 对象，用于链式调用。

作用： 用于发送包含 JSON、XML 等格式请求体的请求，适用于 RESTful 接口的交互。

实际开发场景： 在与 RESTful API 交互时，尤其是 POST、PUT 请求，需要传递复杂的数据结构，如 JSON 格式的数据。

3. 设置代理 - setHttpProxy 和 setProxy

在需要通过代理访问外部网络时，可以使用 setHttpProxy 或 setProxy 方法设置代理。Hutool 支持简单代理和自定义代理配置。

示例：配置代理

import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.core.lang.Console;

import java.net.Proxy;
import java.net.InetSocketAddress;

public class ProxyRequestExample {
    public static void main(String[] args) {
        // 使用简单的 HTTP 代理
        HttpResponse response1 = HttpRequest.post("https://example.com/api")
            .setHttpProxy("127.0.0.1", 8080) // 设置代理
            .execute(); // 执行请求

        // 使用自定义代理
        Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 8080));
        HttpResponse response2 = HttpRequest.post("https://example.com/api")
            .setProxy(proxy) // 设置自定义代理
            .execute(); // 执行请求

        // 获取响应内容
        Console.log("响应内容: {}", response1.body());
    }
}

• setHttpProxy(String host, int port)：设置简单的 HTTP 代理。

  • host：代理服务器地址。
  • port：代理服务器端口号。
  • 返回值：返回 HttpRequest 对象，用于链式调用。

• setProxy(Proxy proxy)：设置自定义代理。

  • proxy：java.net.Proxy 对象，支持更多代理类型和配置。
  • 返回值：返回 HttpRequest 对象，用于链式调用。

作用： 用于在需要通过代理服务器访问网络资源时，提供灵活的代理配置。

实际开发场景： 在内网环境或需要跨境访问外部 API 时，通常需要配置代理服务器。

4. 设置请求头信息 - header

在构建 HTTP 请求时，通常需要设置一些常见的请求头，如 User-Agent、Authorization 等。可以使用 header 方法来设置这些请求头信息。

示例：设置请求头信息

import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.http.Header;
import cn.hutool.core.lang.Console;

public class HeaderRequestExample {
    public static void main(String[] args) {
        // 发送 GET 请求并设置请求头
        HttpResponse response = HttpRequest.get("https://example.com/api")
            .header(Header.USER_AGENT, "Hutool http") // 设置 User-Agent
            .header("Authorization", "Bearer your-token-here") // 设置自定义 Authorization 头
            .execute(); // 执行请求

        // 获取响应内容
        String result = response.body();
        Console.log("响应内容: {}", result);
    }
}

• header(String name, String value)：设置请求头信息。
  • name：请求头名称，可以使用 Header 常量或自定义名称。
  • value：请求头对应的值。
  • 返回值：返回 HttpRequest 对象，用于链式调用。

作用： 用于设置请求头信息，控制请求行为或传递认证信息等。

实际开发场景： 在调用需要身份验证的 API 时，通常需要设置 Authorization 请求头；在构建自定义的 HTTP 客户端时，可能需要设置特定的请求头。

5. 超时设置 - timeout

为了避免请求长时间无响应，可以通过 timeout 方法设置请求的超时时间（以毫秒为单位）。如果超过指定时间仍未收到响应，Hutool 会抛出超时异常。

示例：设置超时时间

import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.core.lang.Console;

public class TimeoutRequestExample {
    public static void main(String[] args) {
        // 发送 GET 请求并设置超时时间
        HttpResponse response = HttpRequest.get("https://example.com/api")
            .timeout(5000) // 设置超时时间为 5 秒
            .execute(); // 执行请求

        // 获取响应内容
        String result = response.body();
        Console.log("响应内容: {}", result);
    }
}

• timeout(int milliseconds)：设置请求的超时时间。
  • milliseconds：超时时间（毫秒），如 5000 表示 5 秒。
  • 返回值：返回 HttpRequest 对象，用于链式调用。

作用： 控制请求的最大等待时间，防止因网络问题导致请求无限等待。

实际开发场景： 在需要对请求响应时间进行严格控制的场景下，使用该方法设定超时阈值。