Hutool Java工具类库-HttpUtil(HTTP 客户端工具类)

原创于 2025-08-13 10:00:00 发布 · 1.6k 阅读

30 ·

CC 4.0 BY-SA版权

文章标签：

#http #网络 #java #开发语言

Hutool 同时被 2 个专栏收录

7 篇文章

订阅专栏

JAVA工具类

2 篇文章

订阅专栏

Hutool是一个Java工具包集，其中的HttpUtil模块封装了JDK的HttpURLConnection，提供了简单易用的HTTP客户端功能。本文将全面介绍HttpUtil和HttpRequest类的所有核心方法，通过丰富的示例展示其使用场景，并深入探讨高级应用技巧，帮助开发者高效处理HTTP请求。

一、HttpUtil基础介绍

1.1 HttpUtil概述

HttpUtil是Hutool工具包中针对HTTP请求场景封装的工具类，主要特点包括：

基于JDK原生HttpURLConnection封装，无需额外依赖
支持HTTP/HTTPS协议
提供文件上传下载等常见功能
支持同步请求，简单易用

1.2 核心优势

相比原生HttpURLConnection，HttpUtil具有以下优势：

API简洁：一行代码完成HTTP请求
自动处理编码：智能识别响应编码
连接池管理：内置连接复用机制
HTTPS支持：自动处理SSL证书问题
文件处理：简化大文件下载和上传

1.3 Maven依赖

使用HttpUtil需要添加Hutool依赖：

<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>5.8.0</version>
</dependency>

二、HttpUtil核心方法详解

2.1 GET请求方法

HttpUtil提供了多个get方法重载，满足不同场景需求：

基本GET请求：

// 最简单GET请求
String result1 = HttpUtil.get("https://www.baidu.com");

// 指定编码的GET请求
String result2 = HttpUtil.get("https://www.baidu.com", CharsetUtil.CHARSET_UTF_8);

// 带参数的GET请求
HashMap<String, Object> paramMap = new HashMap<>();
paramMap.put("city", "北京");
String result3 = HttpUtil.get("https://www.baidu.com", paramMap);

异步GET请求：

HttpUtil.get("https://www.baidu.com", new AsyncHttpClient() {
    @Override
    public void onSuccess(HttpResponse response) {
        System.out.println(response.body());
    }
    
    @Override
    public void onError(Exception e) {
        e.printStackTrace();
    }
});

2.2 POST请求方法

POST请求同样提供多种重载形式：

基本POST请求：

HashMap<String, Object> paramMap = new HashMap<>();
paramMap.put("username", "admin");
paramMap.put("password", "123456");

// 表单POST
String result1 = HttpUtil.post("https://example.com/login", paramMap);

// JSON POST
String json = JSONUtil.toJsonStr(paramMap);
String result2 = HttpUtil.post("https://example.com/api", json);

文件上传：

HashMap<String, Object> paramMap = new HashMap<>();
// 文件参数只需指定File对象
paramMap.put("file", FileUtil.file("D:/test.jpg")); 
paramMap.put("name", "avatar");

String result = HttpUtil.post("https://example.com/upload", paramMap);

2.3 文件下载方法

HttpUtil针对大文件下载做了特殊优化，采用流式处理避免内存溢出：

基本文件下载：

String fileUrl = "http://example.com/largefile.zip";
// 下载到指定目录，返回下载字节数
long size = HttpUtil.downloadFile(fileUrl, FileUtil.file("/data/downloads"));

带进度回调的下载：

HttpUtil.downloadFile(fileUrl, FileUtil.file("/data/downloads"), new StreamProgress(){
    @Override
    public void start() {
        Console.log("开始下载...");
    }
    
    @Override
    public void progress(long progressSize) {
        Console.log("已下载：{}", FileUtil.readableFileSize(progressSize));
    }
    
    @Override
    public void finish() {
        Console.log("下载完成！");
    }
});

2.4 其他实用方法

URL编码/解码：

// 参数编码
String encoded = HttpUtil.encodeParams("name=张三&age=20");

// URL参数转Map
Map<String, String> params = HttpUtil.decodeParams("name=张三&age=20");

构建完整URL：

Map<String, Object> paramMap = new HashMap<>();
paramMap.put("name", "张三");
paramMap.put("age", 20);

String url = HttpUtil.urlWithForm("https://example.com/api", paramMap);
// 结果：https://example.com/api?name=张三&age=20

获取MIME类型：

String mimeType = HttpUtil.getMimeType("test.pdf");
// 返回：application/pdf

三、HttpRequest高级用法

HttpUtil的便捷方法底层都是通过HttpRequest实现的，对于需要更复杂配置的场景，可以直接使用HttpRequest类。

3.1 链式构建请求

HttpRequest采用流畅的链式API设计：

基本配置示例：

String result = HttpRequest.post("https://example.com/api")
    .header("User-Agent", "Hutool Http") // 设置请求头
    .header("Accept", "application/json")
    .form(paramMap) // 表单参数
    .timeout(20000) // 超时时间(毫秒)
    .execute() // 执行请求
    .body(); // 获取响应体

3.2 各种HTTP方法

HttpRequest支持所有HTTP方法：

PUT请求：

String result = HttpRequest.put("https://example.com/api/1")
    .body(JSONUtil.toJsonStr(data))
    .execute()
    .body();

DELETE请求：

String result = HttpRequest.delete("https://example.com/api/1")
    .execute()
    .body();

自定义方法：

String result = HttpRequest.createRequest(Method.PATCH, "https://example.com/api")
    .execute()
    .body();

3.3 请求配置项

HttpRequest提供了丰富的配置选项：

设置代理：

HttpRequest.get("https://example.com")
    .setProxy("127.0.0.1", 8080)
    .execute();

Basic认证：

HttpRequest.get("https://example.com")
    .basicAuth("username", "password")
    .execute();

禁用重定向：

HttpRequest.get("https://example.com")
    .disableRedirect()
    .execute();

设置Cookie：

HttpRequest.get("https://example.com")
    .cookie("name=value; path=/")
    .execute();

3.4 响应处理

HttpResponse对象提供了多种响应处理方法：

获取完整响应：

HttpResponse response = HttpRequest.get("https://example.com").execute();

// 状态码
int status = response.getStatus();
// 响应头
String contentType = response.header("Content-Type");
// 响应体
String body = response.body();
// 响应体转字节数组
byte[] bytes = response.bodyBytes();

流式处理响应：

HttpRequest.get("https://example.com/largefile")
    .execute()
    .writeBody(new FileOutputStream("/data/largefile"));

四、高级应用场景

4.1 HTTPS证书处理

HttpUtil默认信任所有HTTPS证书，适用于开发环境：

// 无需特殊处理即可请求HTTPS
String result = HttpUtil.get("https://example.com");

如需自定义SSL配置：

HttpRequest.get("https://example.com")
    .setSSLProtocol("TLSv1.2")
    .execute();

4.2 RESTful API调用

JSON请求示例：

JSONObject json = new JSONObject();
json.put("username", "admin");
json.put("password", "123456");

String result = HttpRequest.post("https://example.com/api/login")
    .header("Content-Type", "application/json")
    .body(json.toString())
    .execute()
    .body();

获取JSON响应：

HttpResponse response = HttpRequest.get("https://example.com/api/user/1")
    .execute();
    
JSONObject userJson = JSONUtil.parseObj(response.body());

4.3 文件分块上传

对于大文件上传，可以手动控制分块：

File file = FileUtil.file("D:/largefile.zip");
HttpRequest.post("https://example.com/upload")
    .form("file", file)
    .setChunkedStreamMode(1024 * 1024) // 1MB分块
    .execute();

4.4 连接池配置

HttpUtil内置连接池，可通过全局配置调整：

// 设置全局最大连接数
HttpGlobalConfig.setMaxConnCount(100);
// 设置每个路由最大连接数
HttpGlobalConfig.setMaxConnPerRoute(20);
// 设置超时时间(毫秒)
HttpGlobalConfig.setTimeout(30000);

五、性能优化与最佳实践

5.1 性能优化建议

复用HttpRequest对象：对于频繁请求同一地址，可复用HttpRequest实例
合理设置超时：根据网络状况设置连接和读取超时

启用压缩：对文本内容启用Gzip压缩

HttpRequest.get("https://example.com")
    .header("Accept-Encoding", "gzip")
    .execute();

使用连接池：合理配置连接池参数

5.2 异常处理

常见异常类型：

HttpException：HTTP协议相关异常
IORuntimeException：IO操作异常
TimeoutException：请求超时

异常处理示例：

try {
    String result = HttpUtil.get("https://example.com");
} catch (IORuntimeException e) {
    // 处理IO异常
    System.err.println("网络错误: " + e.getMessage());
} catch (TimeoutException e) {
    // 处理超时
    System.err.println("请求超时");
} catch (HttpException e) {
    // 处理HTTP错误
    System.err.println("HTTP错误: " + e.getStatus());
}

5.3 安全建议

敏感信息：不要在URL中传递敏感参数
HTTPS优先：生产环境务必使用HTTPS
输入验证：严格验证服务器响应
资源释放：确保流正确关闭

try (HttpResponse response = HttpRequest.get(url).execute()) {
    // 使用response
}

六、总结

Hutool的HttpUtil和HttpRequest提供了强大而简便的HTTP客户端功能，涵盖了从简单GET请求到复杂文件上传的各种场景。通过本文的介绍，您应该已经掌握了：

HttpUtil的基本GET/POST请求方法
文件上传下载的高级用法
HttpRequest的链式配置技巧
各种HTTP方法(PUT/DELETE等)的使用
性能优化和安全实践

核心优势总结：

简单易用：大多数请求一行代码即可完成
功能全面：覆盖各种HTTP场景需求
性能优异：内置连接池和流式处理
灵活扩展：可通过HttpRequest满足特殊需求

无论是简单的爬虫开发，还是复杂的API调用，Hutool HTTP工具都能显著提升开发效率。建议根据实际需求选择合适的抽象层级，简单场景用HttpUtil，复杂场景用HttpRequest，以获得最佳的开发体验。