Hutool 核心工具类 FileUtil & IoUtil

在Java项目开发中，文件IO操作是高频需求（如文件复制、读写、删除、流处理等）。传统JDK原生IO代码繁琐，需手动管理流的创建与关闭，易出现空指针异常、资源泄漏等问题，开发效率低且容错率差。Hutool工具包对JDK原生IO进行了深度封装，提炼出FileUtil和IoUtil两个核心工具类，简化代码编写，降低开发风险，因此专门系统学习这两个工具类的使用。

1.2 学习目标

掌握FileUtil与IoUtil的核心定位、职责范围，能清晰区分两者的使用场景。
熟练掌握两个类的常用方法，包括参数列表、返回值、功能解释及使用注意事项。
能结合实际开发场景，灵活选择合适的工具类与方法，避免常见错误。
理解两个工具类的底层封装逻辑，掌握流的安全管理技巧，杜绝资源泄漏。

二、核心概念与原理

2.1 基础概念

Hutool：一款Java工具包，致力于简化开发，封装了大量常用工具类，覆盖IO、日期、字符串、集合等多个场景，其中FileUtil和IoUtil是IO操作的核心工具。
FileUtil：Hutool提供的文件/文件夹高级操作工具类，专注于本地文件和目录的整体操作，内部自动处理流的创建与关闭，无需开发者手动干预。
IoUtil：Hutool提供的流操作底层工具类，专注于InputStream、OutputStream等流对象的操作，负责流之间的数据搬运、安全关闭，需开发者手动传入流对象并管理其生命周期。

2.2 核心原理

FileUtil的底层本质是对JDK原生文件操作（如File类、FileInputStream、FileOutputStream）的封装，将“打开流→操作→关闭流”的完整流程封装在方法内部，开发者只需传入文件路径或File对象即可完成操作。

IoUtil的底层是对JDK原生流操作的优化，解决了原生流关闭繁琐、易抛空指针的问题，提供了流拷贝、流转换、安全关闭等核心功能，适配所有流类型（文件流、网络流、压缩流等），通用性更强。

三、知识图谱与逻辑

3.1 工具类关系图谱

Hutool工具包 → IO模块 → 两大核心工具类：

FileUtil：面向文件/文件夹，上层封装，依赖IoUtil完成底层流操作。
IoUtil：面向流对象，底层工具，为FileUtil提供流处理支持，也可独立用于各类流操作。

3.2 核心操作流程对比

3.2.1 FileUtil操作流程（自动流管理）

传入文件路径/File对象 → 方法内部自动创建流 → 执行文件操作（复制/读写等） → 自动关闭流 → 返回操作结果。

3.2.2 IoUtil操作流程（手动流管理）

手动创建流对象 → 传入IoUtil方法执行流操作 → 手动调用IoUtil.close()关闭流 → 完成操作。

四、核心API详解（重点）

4.1 FileUtil 常用API详解

核心特点：高级封装，无需手动操作流，不易出错，专注于文件/文件夹整体操作。

方法签名	参数列表	返回值	功能解释	注意事项	使用场景
copy(String srcPath, String destPath, boolean isOverride)	srcPath：源文件/文件夹路径；destPath：目标路径；isOverride：目标文件存在时是否覆盖（true=覆盖，false=不覆盖）	void	复制单个文件或整个文件夹，内部自动处理流的创建与关闭，支持递归复制文件夹	1. 路径需符合系统格式（Windows用\，Linux用/）；2. 复制文件夹时会递归复制所有子文件和子目录；3. 目标路径父目录不存在时会自动创建	文件备份、文件迁移、项目资源复制
readUtf8String(String path)	path：需要读取的文件路径	String	以UTF-8编码读取文件的全部文本内容，自动处理流关闭	1. 仅适用于文本文件（如txt、json、xml、配置文件）；2. 文件过大时可能占用较多内存	读取配置文件、读取文本日志、读取JSON/XML文件
writeString(String path, String content, boolean isAppend)	path：目标文件路径；content：需要写入的文本内容；isAppend：是否追加写入（true=追加，false=覆盖）	void	将字符串写入指定文件，自动创建文件（文件不存在时）和流，写入完成后自动关闭流	1. 路径父目录不存在时会自动创建；2. 追加写入时不会覆盖原有内容，按顺序添加在文件末尾	生成日志文件、保存用户输入内容、导出文本数据
exists(String path)	path：文件/文件夹路径	boolean	判断指定路径的文件或文件夹是否存在	路径格式需正确，否则会返回false（如路径拼写错误）	文件操作前的安全判断（如复制前判断源文件是否存在）、下载前判断目标路径是否存在
del(String path)	path：文件/文件夹路径	boolean	删除指定的文件或文件夹，删除文件夹时会递归删除所有子文件和子目录	1. 删除操作不可逆，请谨慎使用；2. 无法删除正在被占用的文件/文件夹	清理临时文件、删除无用目录、项目清理操作
touch(String path)	path：文件路径	File	创建指定路径的文件，若文件已存在则不做任何操作，返回该File对象	路径父目录不存在时会自动创建	创建空日志文件、创建空配置文件

4.2 IoUtil 常用API详解

核心特点：底层流操作，必须手动传入流对象，需手动管理流生命周期，通用性强。

方法签名	参数列表	返回值	功能解释	注意事项	使用场景
copy(InputStream in, OutputStream out)	in：输入流（如FileInputStream）；out：输出流（如FileOutputStream）	long	将输入流中的数据拷贝到输出流中，返回复制的总字节数	1. 必须手动创建流对象，拷贝完成后需手动关闭流；2. 流为null时会抛出空指针异常	文件流拷贝、网络流数据传输、二进制文件（图片、音频）拷贝
copy(InputStream in, OutputStream out, int bufferSize)	in：输入流；out：输出流；bufferSize：缓冲区大小（单位：字节，常用8192）	long	带缓冲区的流拷贝，通过设置缓冲区大小提升读写效率，返回复制的总字节数	1. 缓冲区大小建议设置为2的幂次方（如8192、16384）；2. 大文件拷贝时设置合适的缓冲区可显著提升性能	大文件复制、高并发流传输、需要优化性能的流操作
close(AutoCloseable... closeables)	closeables：一个或多个实现AutoCloseable接口的对象（主要是各类流对象）	void	安全关闭流对象，内部自动判空，捕获关闭时的IOException，不会影响后续代码执行	1. 可一次性传入多个流对象，顺序不影响关闭效果；2. 传入null时不会报错，会自动跳过	finally块中关闭流、多流操作后的资源释放、避免资源泄漏
read(InputStream in, String charset)	in：输入流；charset：编码格式（如UTF-8、GBK）	String	将输入流中的数据转换为指定编码的字符串，读取完成后不会自动关闭流	1. 编码格式需与流中数据的编码一致，否则会出现乱码；2. 读取完成后需手动关闭流	网络响应流转文本、读取二进制流中的文本内容、流数据解析
write(OutputStream out, byte[] bytes)	out：输出流；bytes：需要写入的字节数组	void	将字节数组写入输出流中，写入完成后不会自动关闭流	1. 字节数组为null时会抛出空指针异常；2. 写入完成后需手动关闭流	文件下载、图片写入、二进制数据导出、网络流发送数据

五、典型应用案例

5.1 案例一：本地文件复制（推荐写法：FileUtil）

需求：将D盘下的a.txt文件复制到E盘，若E盘已存在该文件则覆盖。

import cn.hutool.core.io.FileUtil;

public class FileCopyDemo {
    public static void main(String[] args) {
        // 源文件路径
        String srcPath = "D:/a.txt";
        // 目标文件路径
        String destPath = "E:/a.txt";
        // 调用FileUtil.copy方法，自动处理流，无需手动关闭
        FileUtil.copy(srcPath, destPath, true);
        System.out.println("文件复制完成！");
    }
}

说明：该写法极简，无需关心流的创建与关闭，Hutool内部自动处理，不易出错，适合日常文件复制场景。

5.2 案例二：流拷贝（底层写法：IoUtil）

需求：读取D盘a.txt文件（字节流），写入到E盘b.txt，使用缓冲区提升效率，并安全关闭流。

import cn.hutool.core.io.IoUtil;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.InputStream;
import java.io.OutputStream;

public class IoCopyDemo {
    public static void main(String[] args) {
        // 声明流对象（try外声明，finally中可关闭）
        InputStream in = null;
        OutputStream out = null;
        try {
            // 手动创建输入流和输出流
            in = new FileInputStream("D:/a.txt");
            out = new FileOutputStream("E:/b.txt");
            // 带缓冲区的流拷贝，缓冲区大小设为8192字节
            long copySize = IoUtil.copy(in, out, 8192);
            System.out.println("复制完成，复制字节数：" + copySize);
        } catch (Exception e) {
            // 捕获异常，避免程序崩溃
            e.printStackTrace();
        } finally {
            // 安全关闭所有流，一次性传入多个流
            IoUtil.close(in, out);
        }
    }
}

说明：该写法需手动创建流，拷贝完成后必须关闭流，适合需要自定义缓冲区、处理特殊流（如网络流）的场景。

5.3 案例三：文本文件读写（对比写法）

需求：读取D盘config.txt配置文件，修改内容后追加写入到该文件。

import cn.hutool.core.io.FileUtil;

public class FileReadWriteDemo {
    public static void main(String[] args) {
        String path = "D:/config.txt";
        // 1. 读取文件内容（FileUtil，自动处理流）
        String content = FileUtil.readUtf8String(path);
        System.out.println("原文件内容：" + content);
        
        // 2. 修改内容并追加写入
        String newContent = "\n新增配置：test=123";
        FileUtil.writeString(path, newContent, true);
        System.out.println("追加写入完成！");
        
        // 3. 再次读取验证
        String newContentAll = FileUtil.readUtf8String(path);
        System.out.println("修改后文件内容：" + newContentAll);
    }
}

说明：使用FileUtil读写文本文件，无需关注流的细节，代码简洁，适合日常文本操作。

六、常见坑与避坑技巧

6.1 易错点总结

坑1：使用IoUtil时，忘记关闭流，导致资源泄漏。避坑：无论流操作是否成功，都要在finally块中调用IoUtil.close()关闭所有流，建议一次性传入所有流对象。
坑2：使用FileUtil时，路径格式错误（如Windows路径用/，Linux路径用\），导致操作失败。避坑：尽量使用标准路径格式，或使用FileUtil的path方法自动适配系统路径。
坑3：使用IoUtil.copy()时，传入null流，导致空指针异常。避坑：使用前对流传入判空，或确保流对象已正确初始化。
坑4：使用FileUtil.readUtf8String()读取二进制文件（如图片、音频），导致乱码或读取失败。避坑：该方法仅适用于文本文件，二进制文件需使用流操作（IoUtil）。
坑5：删除文件/文件夹时，未判断文件是否被占用，导致删除失败。避坑：删除前可先判断文件是否存在，且确保文件未被其他程序占用。

6.2 异常处理方案

FileUtil和IoUtil的方法内部会抛出IOException，开发中需合理捕获异常，避免程序崩溃，同时便于排查问题。

// 异常处理示例
try {
    FileUtil.copy("D:/a.txt", "E:/a.txt", true);
} catch (Exception e) {
    System.err.println("文件复制失败：" + e.getMessage());
    // 可选：打印异常堆栈，便于排查
    e.printStackTrace();
}