最強(qiáng)工具庫(kù) Hutool，使用教程（含 Hutool-AI 使用講解）

作者：wayn 2025-09-01 02:11:00

經(jīng)過(guò)本文的詳細(xì)介紹，相信你已經(jīng)對(duì) Hutool 有了全面的認(rèn)識(shí)。這款國(guó)產(chǎn)工具庫(kù)之所以能獲得廣泛認(rèn)可，核心在于它真正理解 Java 開(kāi)發(fā)者的痛點(diǎn)，用最簡(jiǎn)單直接的方式解決問(wèn)題。

在 Java 世界里，總有那樣一個(gè)工具庫(kù)，它既輕量又實(shí)用，把很多日常重復(fù)工作封裝成“開(kāi)箱即用”的 API，讓你可以把精力放在業(yè)務(wù)邏輯本身。

對(duì)于中國(guó)開(kāi)發(fā)者來(lái)說(shuō)，Hutool 就是這樣一把“瑞士軍刀”——從字符串、集合、日期、IO、文件、加密，到 JDBC、JSON、HTTP、圖片、并發(fā)、甚至 AI 能力（hutool-ai），它幾乎覆蓋了你日常開(kāi)發(fā)中會(huì)用到的絕大多數(shù)工具函數(shù)。

本文說(shuō)明：此文所有代碼，都是有我本人在 5.8.40 版本親測(cè)可用不報(bào)錯(cuò)，歡迎大家直接使用本文示例代碼。

什么是 Hutool？為何它能成為開(kāi)發(fā)必備

Hutool = Hu + tool，是原公司項(xiàng)目底層代碼剝離后的開(kāi)源庫(kù)，“Hu”是公司名稱的表示，tool 表示工具。Hutool 諧音“糊涂”，一方面簡(jiǎn)潔易懂，一方面寓意“難得糊涂”。

這個(gè)始于 2014 年的開(kāi)源項(xiàng)目，核心定位是 "減少代碼搜索成本，避免復(fù)制粘貼代碼導(dǎo)致的潛在問(wèn)題"。與 Guava 等國(guó)外工具庫(kù)相比，Hutool 最大的優(yōu)勢(shì)在于對(duì)中文場(chǎng)景的深度適配和開(kāi)發(fā)者友好的 API 設(shè)計(jì)。

Hutool 的核心優(yōu)勢(shì)

中文友好：內(nèi)置農(nóng)歷日期計(jì)算、中文金額轉(zhuǎn)換等特色功能，完美解決本地化需求
零依賴：純 Java 實(shí)現(xiàn)，不引入額外第三方庫(kù)，避免依賴沖突
模塊化設(shè)計(jì)：20 + 功能模塊支持按需引入，最小化項(xiàng)目體積
活躍社區(qū)：Gitee 托管的國(guó)產(chǎn)項(xiàng)目，issue 響應(yīng)速度遠(yuǎn)超許多國(guó)外庫(kù)
持續(xù)進(jìn)化：2025 年最新的 5.8.40 版本仍在高頻更新，不斷增強(qiáng)功能邊界

版本選擇指南

當(dāng)前 Hutool 存在兩個(gè)重要版本線：

5.x 系列：穩(wěn)定版本，截至本文發(fā)布，最新為 5.8.40（2025 年 8 月發(fā)布），保持向下兼容
6.x 系列：正在醞釀的重構(gòu)版本，將包名從cn.hutool改為org.dromara.hutool，并優(yōu)化了大量 API 設(shè)計(jì)

?? 注意：生產(chǎn)環(huán)境建議使用 5.8.40 穩(wěn)定版，6.x 版本預(yù)計(jì) 2026 年正式發(fā)布，本文代碼示例將基于 5.8.40 版本，并標(biāo)注 6.x 的差異之處。

快速入門：環(huán)境配置

通過(guò) Maven 引入 Hutool 最簡(jiǎn)單的方式是使用hutool-all包：

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

第一個(gè) Hutool 程序：

import cn.hutool.core.date.DateUtil;
import cn.hutool.core.util.StrUtil;

public class HutoolDemo {

   public static void main(String[] args) {
       // 獲取當(dāng)前時(shí)間并格式化
       String now = DateUtil.now();
       // 字符串模板替換
       String welcome = StrUtil.format("歡迎使用Hutool！當(dāng)前時(shí)間：{}", now);
       System.out.println(welcome);
   }

}

這段代碼展示了 Hutool 最典型的使用方式：通過(guò)靜態(tài)工具類直接調(diào)用方法，無(wú)需創(chuàng)建實(shí)例，極大簡(jiǎn)化了代碼結(jié)構(gòu)。

核心工具類詳解：從字符串到加密的全場(chǎng)景覆蓋

Hutool 的工具類遵循 "所見(jiàn)即所得" 的命名原則，StrUtil處理字符串，DateUtil處理日期，SecureUtil處理加密，讓開(kāi)發(fā)者能僅憑類名就知道該用哪個(gè)工具。下面我們將逐一講解開(kāi)發(fā)中最常用的核心模塊。

字符串處理：StrUtil 讓字符操作如行云流水

字符串處理是 Java 開(kāi)發(fā)中最頻繁的操作之一，StrUtil類封裝了 200 + 常用方法，徹底告別String類的蹩腳 API。

空判斷—— 最常用也最容易出錯(cuò)的操作：

// 原生Java寫(xiě)法

if (str == null || str.length() == 0 || "null".equals(str)) {
   // 處理空字符串
}

// Hutool寫(xiě)法
if (StrUtil.isEmpty(str)) {
   // 處理空字符串
}

// 更嚴(yán)格的空判斷（純空白字符也視為空）
if (StrUtil.isBlank(str)) {
   // 處理空白字符串
}

字符串格式化—— 支持多種占位符風(fēng)格：

// 標(biāo)準(zhǔn)占位符
String result1 = StrUtil.format("姓名：{}，年齡：{}", "張三", 25);

// 命名占位符
Map<String, Object> map = new HashMap <>();
map.put("name", "李四");
map.put("age", 30);
String result2 = StrUtil.format("姓名：{name}，年齡：{age}", map);

字符串切割與拼接—— 靈活處理各種分隔符：

String str = "a,b,c,d";

// 切割字符串
List<String> list = StrUtil.split(str, ',');

// 拼接字符串
String join = StrUtil.join("|", list); // 結(jié)果：a|b|c|d

// 去除前后綴
String fileName = "report.pdf";
String name = StrUtil.removeSuffix(fileName, ".pdf"); // 結(jié)果：report

5.8.40 版本新特性：增強(qiáng)的脫敏功能，支持護(hù)照號(hào)碼脫敏：

import cn.hutool.core.util.DesensitizedUtil;

// 手機(jī)號(hào)脫敏：138****1234
String phone = DesensitizedUtil.mobilePhone("13812341234");

// 護(hù)照脫敏：E123****5678
String passport = DesensitizedUtil.passport("E12345678"); // 5.8.40新增

日期時(shí)間：DateUtil 解決所有時(shí)間難題

Java 的日期處理一直為人詬病，Date、Calendar、LocalDateTime并存導(dǎo)致混亂，DateUtil將這些 API 統(tǒng)一封裝，提供直觀易用的日期操作。

日期格式化—— 無(wú)需記憶繁瑣的 pattern：

// 獲取當(dāng)前時(shí)間
Date now = new Date();

// 格式化成年月日
String ymd = DateUtil.formatDate(now); // 2025-08-29

// 格式化時(shí)分秒
String hms = DateUtil.formatTime(now); // 15:30:45

// 自定義格式
String custom = DateUtil.format(now, "yyyy年MM月dd日 HH:mm:ss");

日期計(jì)算—— 鏈?zhǔn)秸{(diào)用輕松實(shí)現(xiàn)：

// 昨天
Date yesterday = DateUtil.yesterday();

// 明天
Date tomorrow = DateUtil.tomorrow();

// 三天后
Date after3Days = DateUtil.offsetDay(now, 3);

// 十分鐘前
Date before10Min = DateUtil.offsetMinute(now, -10);

// 計(jì)算兩個(gè)日期差
Date start = DateUtil.parse("2025-01-01");
Date end = DateUtil.parse("2025-08-29");
long days = DateUtil.between(start, end, DateUnit.DAY); // 240天

中文特色功能—— 農(nóng)歷與節(jié)假日：

// 農(nóng)歷轉(zhuǎn)換
String lunar = DateUtil.lunar(now); // 農(nóng)歷七月十六

// 節(jié)假日判斷
boolean isWorkday = DateUtil.isWorkday(now); // 是否工作日
boolean isHoliday = DateUtil.isHoliday(now); // 是否節(jié)假日

小貼士：Hutool 的節(jié)假日數(shù)據(jù)會(huì)通過(guò)版本更新保持同步，如需自定義節(jié)假日，可通過(guò) HolidayUtil 進(jìn)行擴(kuò)展。

集合操作：CollUtil 讓集合處理得心應(yīng)手

Java 集合框架雖然強(qiáng)大，但很多常用操作仍需大量代碼，CollUtil彌補(bǔ)了這一不足，提供了集合創(chuàng)建、轉(zhuǎn)換、操作的一站式解決方案。

集合創(chuàng)建—— 一行代碼創(chuàng)建各種集合：

// 創(chuàng)建列表
List<String> list = CollUtil.newArrayList("a", "b", "c");

// 創(chuàng)建有序映射
Map<String, Integer> map = MapUtil.newHashMap(true);

// 創(chuàng)建固定大小的集合
Set<Integer> set = CollUtil.newHashSet(1, 2, 3, 4);

集合判斷與操作：

List<Integer> numbers = CollUtil.newArrayList(1, 2, 3, 4, 5);

// 判斷非空
boolean notEmpty = CollUtil.isNotEmpty(numbers);

// 取前3個(gè)元素
List<Integer> top3 = ListUtil.sub(numbers, 0, 3); // [1,2,3]

// 集合拆分
List<List<Integer>> partition = ListUtil.partition(numbers, 2); // [[1,2],[3,4],[5]]

// 集合轉(zhuǎn)字符串
String str = CollUtil.join(numbers, ","); // "1,2,3,4,5"

Map 操作增強(qiáng)：

Map<String, Object> user = new HashMap<>();
user.put("name", "張三");
user.put("age", 25);
user.put("address", null);

// 獲取值，不存在時(shí)返回默認(rèn)值
String name = MapUtil.getStr(user, "name", "未知");
int age = MapUtil.getInt(user, "age", 0);

// 忽略null值轉(zhuǎn)換為字符串
String userStr = MapUtil.joinIgnoreNull(user, ",", "=");
// 結(jié)果：name=張三, age=25

加密工具：SecureUtil 一行代碼實(shí)現(xiàn)加密解密

數(shù)據(jù)安全是開(kāi)發(fā)必備需求，SecureUtil封裝了對(duì)稱加密、非對(duì)稱加密、摘要算法等多種加密方式，無(wú)需了解復(fù)雜的加密原理即可輕松使用。

MD5 加密—— 常用于密碼存儲(chǔ)：

// 簡(jiǎn)單MD5加密
String md5 = SecureUtil.md5("123456");

// 帶鹽值的MD5加密（更安全）
String saltMd5 = SecureUtil.md5("123456" + "salt");

AES 對(duì)稱加密—— 適用于敏感數(shù)據(jù)傳輸：

String content = "需要加密的內(nèi)容";
String key = "1234567890123456"; // AES密鑰長(zhǎng)度必須是16/24/32位

// 加密
String encrypt = SecureUtil.aes(key.getBytes()).encryptBase64(content);

// 解密
String decrypt = SecureUtil.aes(key.getBytes()).decryptStr(encrypt);

國(guó)密算法—— 支持 SM2/SM3/SM4 等國(guó)家標(biāo)準(zhǔn)算法：

// SM3摘要算法
String sm3 = SmUtil.sm3("國(guó)密測(cè)試");

// SM4對(duì)稱加密
String sm4Encrypt = SmUtil.sm4(key.getBytes()).encryptBase64(content);

注意：加密算法的密鑰管理至關(guān)重要，生產(chǎn)環(huán)境中切勿將密鑰硬編碼在代碼中，建議通過(guò)配置中心管理。

文件操作：FileUtil 讓文件處理事半功倍

Java 的 IO 操作代碼冗長(zhǎng)且容易出錯(cuò)，FileUtil和IoUtil將這些操作簡(jiǎn)化到極致，無(wú)論是文件讀寫(xiě)還是目錄操作都能輕松完成。

文件讀寫(xiě)—— 幾行代碼搞定：

// 讀取文件內(nèi)容
String content = FileUtil.readString("test.txt", CharsetUtil.UTF_8);

// 寫(xiě)入文件
FileUtil.writeString("Hello Hutool", "output.txt", CharsetUtil.UTF_8);

// 追加內(nèi)容
FileUtil.appendString("\n追加一行", "output.txt", CharsetUtil.UTF_8);

// 大文件拷貝
FileUtil.copy("largeFile.zip", new File("targetDir"), true); // true表示覆蓋

目錄操作：

// 創(chuàng)建目錄
FileUtil.mkdir("newDir");

// 創(chuàng)建多級(jí)目錄
FileUtil.mkdir("parent/child/grandchild");

// 列出目錄下所有文件
List<File> files = List.of(FileUtil.ls("parent"));

// 遞歸列出所有Java文件
List<File> javaFiles = FileUtil.loopFiles("com", file -> file.getName().endsWith(".class"));

文件信息獲取：

File file = new File("test.txt");

// 文件大小
long size = FileUtil.size(file);

// 人性化顯示大小
String humanSize = FileUtil.readableFileSize(size); // 如：1.5MB

// 文件類型
String type = FileUtil.getType(file); // txt

// 最后修改時(shí)間
Date lastModified = FileUtil.lastModifiedTime(file);

HTTP 客戶端：HttpUtil 輕松發(fā)送網(wǎng)絡(luò)請(qǐng)求

相比HttpClient的復(fù)雜配置，HttpUtil讓 HTTP 請(qǐng)求變得極其簡(jiǎn)單，無(wú)論是 GET、POST 還是文件上傳下載都能輕松應(yīng)對(duì)。

GET 請(qǐng)求：

// 簡(jiǎn)單GET請(qǐng)求
String result = HttpUtil.get("https://api.example.com/data");

// 帶參數(shù)的GET請(qǐng)求
Map<String, Object> paramMap = new HashMap <>();
paramMap.put("page", 1);
paramMap.put("size", 10);
String pageResult = HttpUtil.get("https://api.example.com/list", paramMap);

POST 請(qǐng)求：

// 表單提交
Map<String, Object> formData = new HashMap <>();
formData.put("username", "test");
formData.put("password", "123456");
String loginResult = HttpUtil.post("https://api.example.com/login", formData);

// JSON提交
String json = "{\"name\":\"hutool\",\"version\":\"5.8.40\"}";
HttpResponse response = HttpUtil.createPost("https://api.example.com/submit")
   .body(json)
   .header("Content-Type", "application/json")
   .execute();

String jsonResult = response.body();

文件下載：

// 下載文件到指定路徑
HttpUtil.downloadFile("https://example.com/file.zip", FileUtil.file("downloads"));

// 帶進(jìn)度條的下載
HttpUtil.downloadFile("https://example.com/large.zip", FileUtil.file("downloads"),
   new StreamProgress() {

       @Override
       public void start() {
           System.out.println("開(kāi)始下載");
       }

      @Override
      public void progress(long total, long progressSize) {
          System.out.println("已下載：" + FileUtil.readableFileSize(progressSize));

      }

       @Override
       public void finish() {
           System.out.println("下載完成");
       }
   });

hutool-ai 模塊：AI 能力集成新范式

隨著大模型技術(shù)的普及，Hutool 在 5.8.x 版本中新增了hutool-ai模塊，為開(kāi)發(fā)者提供了簡(jiǎn)單易用的 AI 能力集成方案。該模塊封裝了主流 AI 平臺(tái)的 API，支持文本生成、圖像生成等常見(jiàn)場(chǎng)景，并提供了統(tǒng)一的調(diào)用接口。

模塊引入與初始化

使用hutool-ai需要單獨(dú)引入依賴：

<dependency>
   <groupId>cn.hutool</groupId>
   <artifactId>hutool-ai</artifactId>
   <version>5.8.40</version>
</dependency>

初始化 AI 客戶端（以豆包平臺(tái)為例）：

// 配置API密鑰
AIConfig config = new BaseConfig();
config.setApiKey("sk-");
config.setApiUrl("https://api.deepseek.com/v1");
config.setModel("deepseek-reasoner");

// 創(chuàng)建deepseekAI客戶端
DeepSeekServiceImpl baseAIService = new DeepSeekServiceImpl(config);

文本生成功能

DeepSeekService 是 Hutool AI 模塊中專門對(duì)接 DeepSeek 大模型服務(wù)的接口，在基礎(chǔ) AIService 功能基礎(chǔ)上擴(kuò)展了 DeepSeek 特有的功能。

// 配置API密鑰
AIConfig config = new BaseConfig();
config.setApiKey("sk-");
config.setApiUrl("https://api.deepseek.com/v1");
config.setModel("deepseek-reasoner");

// 創(chuàng)建deepseekAI客戶端
DeepSeekServiceImpl baseAIService = new DeepSeekServiceImpl(config);

// 普通對(duì)話
String content = baseAIService.chat("寫(xiě)一個(gè)瘋狂星期四廣告詞");

// 流式對(duì)話
baseAIService.chat("寫(xiě)一個(gè)瘋狂星期四廣告詞", s -> {
    System.out.println(s);
});

// 查詢模型列表
String models = baseAIService.models();
// 查詢賬戶余額
String balance = baseAIService.balance();

圖片理解

DoubaoService 是 Hutool AI 模塊中對(duì)接豆包大模型服務(wù)的擴(kuò)展接口，在基礎(chǔ) AIService 功能基礎(chǔ)上提供了豆包特有的多模態(tài)和高級(jí)功能支持。

// 配置API密鑰
AIConfig config = new BaseConfig();
config.setApiKey("sk-");
config.setApiUrl("https://api.deepseek.com/v1");
config.setModel("deepseek-reasoner");

// 創(chuàng)建deepseekAI客戶端
DoubaoServiceImpl baseAIService = new DoubaoServiceImpl(config);
String base64 = "xxx"; // 圖片base64內(nèi)容
String chatVision = baseAIService.chatVision("圖片上有些什么？", Arrays.asList(base64));

視頻生成

// 配置API密鑰
AIConfig config = new BaseConfig();
config.setApiKey("sk-");
config.setApiUrl("https://api.deepseek.com/v1");
config.setModel("deepseek-reasoner");

// 創(chuàng)建deepseekAI客戶端
DoubaoServiceImpl baseAIService = new DoubaoServiceImpl(config);

String videoTasks = baseAIService.videoTasks("生成一段動(dòng)畫(huà)視頻，主角是大耳朵圖圖，一個(gè)活潑可愛(ài)的小男孩。視頻中圖圖在公園里玩耍，" +
"畫(huà)面采用明亮溫暖的卡通風(fēng)格，色彩鮮艷，動(dòng)作流暢。背景音樂(lè)輕快活潑，帶有冒險(xiǎn)感，音效包括鳥(niǎo)叫聲、歡笑聲和山洞回聲。", "https://img2.baidu.com/it/u=862000265,4064861820&fm=253&fmt=auto&app=138&f=JPEG?w=800&h=1544");

//查詢視頻生成任務(wù)信息
String videoTasksInfo = baseAIService.getVideoTasksInfo("任務(wù)id");

總結(jié)：為什么 Hutool 值得你全面擁抱

責(zé)任編輯：武曉燕來(lái)源：程序員wayn

Hutool 工具庫(kù)AI