最強工具庫 Hutool，使用教程（含 Hutool-AI 使用講解）
在 Java 世界里，總有那樣一個工具庫，它既輕量又實用，把很多日常重復工作封裝成“開箱即用”的 API，讓你可以把精力放在業(yè)務邏輯本身。
對于中國開發(fā)者來說，Hutool 就是這樣一把“瑞士軍刀”——從字符串、集合、日期、IO、文件、加密，到 JDBC、JSON、HTTP、圖片、并發(fā)、甚至 AI 能力（hutool-ai），它幾乎覆蓋了你日常開發(fā)中會用到的絕大多數(shù)工具函數(shù)。
本文說明：此文所有代碼，都是有我本人在 5.8.40 版本親測可用不報錯，歡迎大家直接使用本文示例代碼。
什么是 Hutool？為何它能成為開發(fā)必備
Hutool = Hu + tool，是原公司項目底層代碼剝離后的開源庫，“Hu”是公司名稱的表示，tool 表示工具。Hutool 諧音“糊涂”，一方面簡潔易懂，一方面寓意“難得糊涂”。
這個始于 2014 年的開源項目，核心定位是 "減少代碼搜索成本，避免復制粘貼代碼導致的潛在問題"。與 Guava 等國外工具庫相比，Hutool 最大的優(yōu)勢在于對中文場景的深度適配和開發(fā)者友好的 API 設(shè)計。
Hutool 的核心優(yōu)勢
- 中文友好：內(nèi)置農(nóng)歷日期計算、中文金額轉(zhuǎn)換等特色功能，完美解決本地化需求
- 零依賴：純 Java 實現(xiàn)，不引入額外第三方庫，避免依賴沖突
- 模塊化設(shè)計：20 + 功能模塊支持按需引入，最小化項目體積
- 活躍社區(qū)：Gitee 托管的國產(chǎn)項目，issue 響應速度遠超許多國外庫
- 持續(xù)進化：2025 年最新的 5.8.40 版本仍在高頻更新，不斷增強功能邊界
版本選擇指南
當前 Hutool 存在兩個重要版本線：
- 5.x 系列：穩(wěn)定版本，截至本文發(fā)布，最新為 5.8.40（2025 年 8 月發(fā)布），保持向下兼容
- 6.x 系列：正在醞釀的重構(gòu)版本，將包名從
cn.hutool改為org.dromara.hutool，并優(yōu)化了大量 API 設(shè)計
?? 注意：生產(chǎn)環(huán)境建議使用 5.8.40 穩(wěn)定版，6.x 版本預計 2026 年正式發(fā)布，本文代碼示例將基于 5.8.40 版本，并標注 6.x 的差異之處。
快速入門：環(huán)境配置
通過 Maven 引入 Hutool 最簡單的方式是使用hutool-all包：
<dependency>
<groupId>cn.hutool </groupId>
<artifactId>hutool-all </artifactId>
<version>5.8.40</version>
</dependency>第一個 Hutool 程序：
import cn.hutool.core.date.DateUtil;
import cn.hutool.core.util.StrUtil;
public class HutoolDemo {
public static void main(String[] args) {
// 獲取當前時間并格式化
String now = DateUtil.now();
// 字符串模板替換
String welcome = StrUtil.format("歡迎使用Hutool！當前時間：{}", now);
System.out.println(welcome);
}
}這段代碼展示了 Hutool 最典型的使用方式：通過靜態(tài)工具類直接調(diào)用方法，無需創(chuàng)建實例，極大簡化了代碼結(jié)構(gòu)。
核心工具類詳解：從字符串到加密的全場景覆蓋
Hutool 的工具類遵循 "所見即所得" 的命名原則，StrUtil處理字符串，DateUtil處理日期，SecureUtil處理加密，讓開發(fā)者能僅憑類名就知道該用哪個工具。下面我們將逐一講解開發(fā)中最常用的核心模塊。
字符串處理：StrUtil 讓字符操作如行云流水
字符串處理是 Java 開發(fā)中最頻繁的操作之一，StrUtil類封裝了 200 + 常用方法，徹底告別String類的蹩腳 API。
空判斷—— 最常用也最容易出錯的操作：
// 原生Java寫法
if (str == null || str.length() == 0 || "null".equals(str)) {
// 處理空字符串
}
// Hutool寫法
if (StrUtil.isEmpty(str)) {
// 處理空字符串
}
// 更嚴格的空判斷（純空白字符也視為空）
if (StrUtil.isBlank(str)) {
// 處理空白字符串
}字符串格式化—— 支持多種占位符風格：
// 標準占位符
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é)果：report5.8.40 版本新特性：增強的脫敏功能，支持護照號碼脫敏：
import cn.hutool.core.util.DesensitizedUtil;
// 手機號脫敏：138****1234
String phone = DesensitizedUtil.mobilePhone("13812341234");
// 護照脫敏：E123****5678
String passport = DesensitizedUtil.passport("E12345678"); // 5.8.40新增日期時間：DateUtil 解決所有時間難題
Java 的日期處理一直為人詬病，Date、Calendar、LocalDateTime并存導致混亂，DateUtil將這些 API 統(tǒng)一封裝，提供直觀易用的日期操作。
日期格式化—— 無需記憶繁瑣的 pattern：
// 獲取當前時間
Date now = new Date();
// 格式化成年月日
String ymd = DateUtil.formatDate(now); // 2025-08-29
// 格式化時分秒
String hms = DateUtil.formatTime(now); // 15:30:45
// 自定義格式
String custom = DateUtil.format(now, "yyyy年MM月dd日 HH:mm:ss");日期計算—— 鏈式調(diào)用輕松實現(xiàn)：
// 昨天
Date yesterday = DateUtil.yesterday();
// 明天
Date tomorrow = DateUtil.tomorrow();
// 三天后
Date after3Days = DateUtil.offsetDay(now, 3);
// 十分鐘前
Date before10Min = DateUtil.offsetMinute(now, -10);
// 計算兩個日期差
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ù)會通過版本更新保持同步，如需自定義節(jié)假日，可通過
HolidayUtil進行擴展。
集合操作：CollUtil 讓集合處理得心應手
Java 集合框架雖然強大，但很多常用操作仍需大量代碼，CollUtil彌補了這一不足，提供了集合創(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個元素
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 操作增強：
Map<String, Object> user = new HashMap<>();
user.put("name", "張三");
user.put("age", 25);
user.put("address", null);
// 獲取值，不存在時返回默認值
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 一行代碼實現(xiàn)加密解密
數(shù)據(jù)安全是開發(fā)必備需求，SecureUtil封裝了對稱加密、非對稱加密、摘要算法等多種加密方式，無需了解復雜的加密原理即可輕松使用。
MD5 加密—— 常用于密碼存儲：
// 簡單MD5加密
String md5 = SecureUtil.md5("123456");
// 帶鹽值的MD5加密（更安全）
String saltMd5 = SecureUtil.md5("123456" + "salt");AES 對稱加密—— 適用于敏感數(shù)據(jù)傳輸：
String content = "需要加密的內(nèi)容";
String key = "1234567890123456"; // AES密鑰長度必須是16/24/32位
// 加密
String encrypt = SecureUtil.aes(key.getBytes()).encryptBase64(content);
// 解密
String decrypt = SecureUtil.aes(key.getBytes()).decryptStr(encrypt);國密算法—— 支持 SM2/SM3/SM4 等國家標準算法：
// SM3摘要算法
String sm3 = SmUtil.sm3("國密測試");
// SM4對稱加密
String sm4Encrypt = SmUtil.sm4(key.getBytes()).encryptBase64(content);注意：加密算法的密鑰管理至關(guān)重要，生產(chǎn)環(huán)境中切勿將密鑰硬編碼在代碼中，建議通過配置中心管理。
文件操作：FileUtil 讓文件處理事半功倍
Java 的 IO 操作代碼冗長且容易出錯，FileUtil和IoUtil將這些操作簡化到極致，無論是文件讀寫還是目錄操作都能輕松完成。
文件讀寫—— 幾行代碼搞定：
// 讀取文件內(nèi)容
String content = FileUtil.readString("test.txt", CharsetUtil.UTF_8);
// 寫入文件
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)建多級目錄
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
// 最后修改時間
Date lastModified = FileUtil.lastModifiedTime(file);HTTP 客戶端：HttpUtil 輕松發(fā)送網(wǎng)絡(luò)請求
相比HttpClient的復雜配置，HttpUtil讓 HTTP 請求變得極其簡單，無論是 GET、POST 還是文件上傳下載都能輕松應對。
GET 請求：
// 簡單GET請求
String result = HttpUtil.get("https://api.example.com/data");
// 帶參數(shù)的GET請求
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 請求：
// 表單提交
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"));
// 帶進度條的下載
HttpUtil.downloadFile("https://example.com/large.zip", FileUtil.file("downloads"),
new StreamProgress() {
@Override
public void start() {
System.out.println("開始下載");
}
@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模塊，為開發(fā)者提供了簡單易用的 AI 能力集成方案。該模塊封裝了主流 AI 平臺的 API，支持文本生成、圖像生成等常見場景，并提供了統(tǒng)一的調(diào)用接口。
模塊引入與初始化
使用hutool-ai需要單獨引入依賴：
<dependency>
<groupId>cn.hutool</groupId>
<artifactId>hutool-ai</artifactId>
<version>5.8.40</version>
</dependency>初始化 AI 客戶端（以豆包平臺為例）：
// 配置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 模塊中專門對接 DeepSeek 大模型服務的接口，在基礎(chǔ) AIService 功能基礎(chǔ)上擴展了 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);
// 普通對話
String content = baseAIService.chat("寫一個瘋狂星期四廣告詞");
// 流式對話
baseAIService.chat("寫一個瘋狂星期四廣告詞", s -> {
System.out.println(s);
});
// 查詢模型列表
String models = baseAIService.models();
// 查詢賬戶余額
String balance = baseAIService.balance();圖片理解
DoubaoService 是 Hutool AI 模塊中對接豆包大模型服務的擴展接口，在基礎(chǔ) AIService 功能基礎(chǔ)上提供了豆包特有的多模態(tài)和高級功能支持。
// 配置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("生成一段動畫視頻，主角是大耳朵圖圖，一個活潑可愛的小男孩。視頻中圖圖在公園里玩耍，" +
"畫面采用明亮溫暖的卡通風格，色彩鮮艷，動作流暢。背景音樂輕快活潑，帶有冒險感，音效包括鳥叫聲、歡笑聲和山洞回聲。", "https://img2.baidu.com/it/u=862000265,4064861820&fm=253&fmt=auto&app=138&f=JPEG?w=800&h=1544");
//查詢視頻生成任務信息
String videoTasksInfo = baseAIService.getVideoTasksInfo("任務id");總結(jié)：為什么 Hutool 值得你全面擁抱
經(jīng)過本文的詳細介紹，相信你已經(jīng)對 Hutool 有了全面的認識。這款國產(chǎn)工具庫之所以能獲得廣泛認可，核心在于它真正理解 Java 開發(fā)者的痛點，用最簡單直接的方式解決問題。
