Java 实例 – 遍历目录（一文讲透）

Java 实例 – 遍历目录：从入门到实战

在日常开发中，我们经常需要对文件系统进行操作，比如读取某个文件夹下的所有文件、统计特定类型文件的数量、备份数据，或者清理临时文件。这些场景背后的核心技术，就是遍历目录。今天我们就来深入探讨 Java 实例 – 遍历目录的完整实现方式，无论你是初学者还是有一定经验的开发者，都能从中获得实用价值。

想象一下，你有一个项目根目录，里面包含了 src、resources、docs、test 等多个子文件夹，每个文件夹下又有成百上千个文件。手动一个个打开查看？显然不现实。这时候，程序自动帮你“翻箱倒柜”就显得格外重要。Java 提供了强大的文件系统 API，让我们可以轻松实现这种自动化操作。

什么是目录遍历？它为什么重要？

目录遍历，顾名思义，就是逐个访问一个目录及其所有子目录中的文件和子目录。这在很多场景中都有应用，比如：

扫描项目中的所有 Java 文件，用于代码分析；
清理日志目录中超过 30 天的旧日志；
构建静态网站时，遍历所有 Markdown 文件生成 HTML；
搜索特定后缀名的文件（如 .jpg、.pdf）。

在 Java 中，java.io.File 类是操作文件和目录的基础。虽然它功能强大，但它的设计存在一些历史遗留问题，比如无法直接获取文件的元信息（如大小、创建时间）或支持符号链接。因此，从 Java 7 开始，引入了 NIO.2（New I/O 2） 框架，提供了更现代、更高效的文件系统操作方式。

使用 File 类实现简单遍历

我们先从最基础的 File 类开始，它是 Java 早期就提供的 API，适合快速上手。

import java.io.File;

public class DirectoryTraversalExample {

    public static void main(String[] args) {
        // 指定要遍历的目录路径
        String directoryPath = "/path/to/your/folder";

        // 创建 File 对象
        File directory = new File(directoryPath);

        // 检查路径是否存在且是目录
        if (!directory.exists() || !directory.isDirectory()) {
            System.out.println("指定路径不存在或不是目录");
            return;
        }

        // 调用递归方法开始遍历
        traverseDirectory(directory);
    }

    /**
     * 递归遍历目录及其子目录
     * @param dir 要遍历的目录
     */
    public static void traverseDirectory(File dir) {
        // 获取目录下的所有文件和子目录
        File[] files = dir.listFiles();

        // 如果文件数组为空，说明目录为空
        if (files == null) {
            System.out.println("无法读取目录内容：" + dir.getAbsolutePath());
            return;
        }

        // 遍历每个文件或子目录
        for (File file : files) {
            // 如果是文件，打印文件名
            if (file.isFile()) {
                System.out.println("文件: " + file.getAbsolutePath());
            }
            // 如果是目录，递归进入
            else if (file.isDirectory()) {
                System.out.println("目录: " + file.getAbsolutePath());
                // 递归调用自身，继续遍历子目录
                traverseDirectory(file);
            }
        }
    }
}

代码详解：

new File(directoryPath)：创建一个指向指定路径的文件对象。
exists() 和 isDirectory()：确保路径存在且是一个目录，避免程序崩溃。
listFiles()：返回该目录下所有文件和子目录的数组，若无法读取则返回 null。
递归调用 traverseDirectory(file)：当遇到子目录时，程序会自动进入该目录继续遍历，形成“层层深入”的效果。

💡 小贴士：递归就像爬楼梯，每到一个新楼层（子目录），就再找下一层楼梯。只要楼梯不断，你就能走到最底层。

使用 NIO.2 的 Files.walk() 实现更优雅遍历

Java 7 引入的 NIO.2 提供了 java.nio.file.Files 和 java.nio.file.Path，让文件操作更简洁、更高效。特别是 Files.walk() 方法，它能以流的方式遍历整个目录树。

import java.io.IOException;
import java.nio.file.*;

public class NIO2TraversalExample {

    public static void main(String[] args) {
        String directoryPath = "/path/to/your/folder";
        Path startPath = Paths.get(directoryPath);

        // 检查路径是否存在
        if (!Files.exists(startPath)) {
            System.out.println("路径不存在：" + directoryPath);
            return;
        }

        try {
            // 使用 Files.walk() 遍历目录树，返回 Stream<Path>
            Files.walk(startPath)
                 .forEach(path -> {
                     // 判断是文件还是目录
                     if (Files.isRegularFile(path)) {
                         System.out.println("文件: " + path);
                     } else if (Files.isDirectory(path)) {
                         System.out.println("目录: " + path);
                     }
                 });
        } catch (IOException e) {
            System.err.println("遍历过程中发生错误：" + e.getMessage());
        }
    }
}

代码说明：

Paths.get(path)：将字符串路径转换为 Path 对象，是 NIO.2 的标准方式。
Files.walk(startPath)：返回一个 Stream<Path>，包含从起始路径开始的所有文件和目录（包括子目录）。
.forEach()：对每个路径执行操作，类似 for-each 循环。
Files.isRegularFile(path)：判断是否为普通文件（非目录、符号链接等）。
Files.isDirectory(path)：判断是否为目录。

✅ 优势对比：相比 File 类的递归方式，Files.walk() 更简洁，且支持流式处理，便于后续链式操作（如过滤、映射）。

按条件筛选文件：只遍历特定类型的文件

很多时候我们不需要遍历所有文件，而是只关心某些类型。比如只找 .java 文件或 .log 文件。

示例：只查找 Java 文件

import java.io.IOException;
import java.nio.file.*;

public class FilteredTraversalExample {

    public static void main(String[] args) {
        String directoryPath = "/path/to/your/project";
        Path startPath = Paths.get(directoryPath);

        if (!Files.exists(startPath)) {
            System.out.println("路径不存在：" + directoryPath);
            return;
        }

        try {
            // 使用 Files.walk() 并结合 filter 进行筛选
            Files.walk(startPath)
                 .filter(Files::isRegularFile)         // 只保留文件（排除目录）
                 .filter(path -> path.toString().endsWith(".java"))  // 只保留 .java 文件
                 .forEach(path -> System.out.println("找到 Java 文件: " + path));
        } catch (IOException e) {
            System.err.println("遍历失败：" + e.getMessage());
        }
    }
}

逻辑解析：

filter(Files::isRegularFile)：先过滤掉所有目录，只保留文件。
filter(path -> path.toString().endsWith(".java"))：进一步筛选出后缀为 .java 的文件。

🎯 实用场景：你可以将这个逻辑用于代码统计、静态分析工具，或者生成文件列表用于构建系统。

遍历深度控制：限制遍历层级

有时我们只想遍历前两层子目录，不想深入太深。Files.walk() 支持指定最大深度。

import java.io.IOException;
import java.nio.file.*;

public class DepthLimitedTraversal {

    public static void main(String[] args) {
        String directoryPath = "/path/to/your/folder";
        Path startPath = Paths.get(directoryPath);

        if (!Files.exists(startPath)) {
            System.out.println("路径不存在：" + directoryPath);
            return;
        }

        try {
            // 限制遍历深度为 2（包含起始目录为第 0 层）
            Files.walk(startPath, 2)  // 第二个参数是最大深度，2 表示最多进入两层子目录
                 .forEach(path -> {
                     if (Files.isRegularFile(path)) {
                         System.out.println("文件: " + path);
                     } else if (Files.isDirectory(path)) {
                         System.out.println("目录: " + path);
                     }
                 });
        } catch (IOException e) {
            System.err.println("遍历失败：" + e.getMessage());
        }
    }
}

深度说明：

walk(startPath, 0)：只遍历起始目录本身；
walk(startPath, 1)：遍历起始目录 + 第一层子目录；
walk(startPath, 2)：最多进入两层子目录。

📌 适用场景：在大型项目中，避免因递归过深导致性能下降或栈溢出。

实战案例：统计目录中文件数量与总大小

让我们来一个完整的 Java 实例 – 遍历目录的实战项目：统计某个目录下所有文件的总数和总大小（单位：KB）。

import java.io.IOException;
import java.nio.file.*;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicLong;

public class FileStatsCollector {

    public static void main(String[] args) {
        String directoryPath = "/path/to/your/folder";
        Path startPath = Paths.get(directoryPath);

        if (!Files.exists(startPath)) {
            System.out.println("路径不存在：" + directoryPath);
            return;
        }

        AtomicInteger fileCount = new AtomicInteger(0);
        AtomicLong totalSize = new AtomicLong(0);

        try {
            // 遍历所有文件，统计数量和大小
            Files.walk(startPath)
                 .filter(Files::isRegularFile)
                 .forEach(path -> {
                     try {
                         long size = Files.size(path);
                         fileCount.incrementAndGet();
                         totalSize.addAndGet(size);
                     } catch (IOException e) {
                         System.err.println("读取文件大小失败：" + path + " - " + e.getMessage());
                     }
                 });

            // 输出结果
            System.out.println("文件总数: " + fileCount.get());
            System.out.println("总大小: " + (totalSize.get() / 1024) + " KB");

        } catch (IOException e) {
            System.err.println("遍历失败：" + e.getMessage());
        }
    }
}

运行结果示例：

文件总数: 124
总大小: 3456 KB

✅ 这个例子展示了如何将 Java 实例 – 遍历目录应用于真实业务场景，比如磁盘使用分析、资源管理工具开发。

总结与建议

通过本文的深入讲解，我们掌握了多种 Java 实例 – 遍历目录的实现方式：

使用 File 类递归遍历，适合简单场景，逻辑清晰；
使用 NIO.2 的 Files.walk()，代码更简洁，支持流式处理，推荐在新项目中使用；
结合 filter() 和 maxDepth 参数，实现精准控制；
融合 AtomicInteger 和 AtomicLong，实现线程安全的统计。

✅ 最佳实践建议：

尽量使用 NIO.2 的 API，避免 File 类的潜在问题；

遍历前务必检查路径是否存在；

对于大目录，考虑设置最大深度，防止性能问题；

使用 try-with-resources 或异常处理机制，提升健壮性。

无论你是写脚本、做工具，还是开发系统，掌握 Java 实例 – 遍历目录都是一项基础但极其重要的技能。希望这篇文章能帮你打通从“知道”到“会用”的最后一公里。