Java Files.find 怎么按文件属性和最大深度筛选文件

Files.find 适合“从某个目录开始，在限定深度内按文件属性筛选”的任务。它把 Path 和 BasicFileAttributes 一起交给匹配器，返回一个惰性的 Stream。最小写法如下：

try (Stream files = Files.find(root, 2, (path, attrs) ->
        attrs.isRegularFile() && attrs.size() >= 1024)) {
    // 只消费根目录下两层以内、大小至少为 1 KiB 的普通文件。
    files.forEach(System.out::println);
}

Java 官方 API：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/nio/file/Files.html

Files.find 的关键不是“递归找文件”四个字，而是把搜索起点、最大深度、属性条件和流的生命周期同时写清楚。深度决定访问范围，属性谓词决定哪些路径进入结果，try-with-resources 负责释放遍历过程中打开的目录。

触发场景：什么时候用 Files.find

如果需求是“扫描某个目录，最多进入两层，只保留普通文件，再按大小或修改时间筛选”，Files.find 比先用 Files.walk 得到全部路径、再额外读取属性更直接。匹配器已经同时收到路径和基本属性，可以在一个谓词里完成条件判断。

下面的导入和变量表达了最小边界：

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.attribute.BasicFileAttributes;
import java.util.stream.Stream;

Path root = Path.of("/srv/archive");
int maxDepth = 2;

try (Stream files = Files.find(root, maxDepth, (path, attrs) ->
        attrs.isRegularFile() && path.getFileName().toString().endsWith(".log"))) {
    // 属性判断在 matcher 中完成，结果流只保留满足条件的路径。
    files.forEach(System.out::println);
} catch (IOException ex) {
    // 起点不存在、目录无法打开等创建阶段问题在这里处理。
    System.err.println("无法创建文件搜索流: " + ex.getMessage());
}

Files.find 从 Java 8 起提供。它的参数分别是起点、最大目录深度、匹配器和可选的文件访问选项；没有必要为了基本属性筛选改写成 FileVisitor。

条件配置：用 BasicFileAttributes 写筛选谓词

匹配器类型是 BiPredicate。路径适合判断名称、后缀和相对位置，属性对象适合判断对象类型、大小和时间。把两类条件放在同一个谓词里，代码更容易与文章标题中的“文件属性”对应。

static boolean isLargeRecentFile(Path path, BasicFileAttributes attrs) {
    // 只接收普通文件，排除目录和其他文件类型。
    if (!attrs.isRegularFile()) {
        return false;
    }

    // 用属性对象读取大小，避免在谓词中再次读取文件元数据。
    boolean largeEnough = attrs.size() >= 1024 * 1024;
    boolean isLog = path.getFileName().toString().endsWith(".log");
    return largeEnough && isLog;
}

常用属性包括 isRegularFile()、isDirectory()、size()、lastModifiedTime() 和 creationTime()。不要在谓词中调用另一次 Files.readAttributes 来重复读取同一组基本属性；这样会让筛选逻辑变长，也可能增加文件系统访问。

遍历流水线：理解惰性 Stream

Files.find 返回的不是已经装满结果的列表，而是惰性流。目录会随着流的消费被访问，匹配器也在遍历过程中被调用。因此，下面两种写法都不完整：

• 只调用 Files.find 却不消费流，不能得到任何输出，也容易遗漏关闭。
• 把流保存到长生命周期字段，可能让遍历期间打开的目录资源持续存在。

List selected;

try (Stream files = Files.find(root, 2, (path, attrs) ->
        attrs.isRegularFile() && attrs.size() > 0)) {
    // 在资源作用域内收集结果，离开 try 后列表与目录句柄脱钩。
    selected = files.sorted().toList();
}

selected.forEach(path -> {
    // 流关闭后再处理已收集的路径，避免把流带出资源作用域。
    System.out.println(path);
});

如果只需要逐个处理，可以直接在 try 块中调用 forEach；如果要返回结果，先在作用域内收集成列表。不要把 Stream 作为返回值交给调用方，除非调用方同时明确拥有关闭它的责任。

门禁规则：maxDepth、目录和符号链接

maxDepth 是目录层级限制，不是“最多返回多少个文件”。起点本身的深度是 0，直接子目录属于下一层；设为 0 时只访问起点，设为 Integer.MAX_VALUE 才表示不限制层数。负数不是“跳过遍历”，而是非法参数。

默认情况下，文件树遍历不会自动跟随符号链接；如果传入 FileVisitOption.FOLLOW_LINKS，就要同时考虑链接循环。只有确实需要跨链接进入目标目录时才打开该选项，并把深度和循环风险写进调用约束。

失败处理：分别接住创建和遍历阶段异常

Files.find 方法声明会抛出 IOException，例如起点无法访问或初始目录无法打开。但目录访问是惰性的，流创建后继续遍历时发生的 I/O 问题可能以 UncheckedIOException 的形式从终端操作冒出来。

try (Stream files = Files.find(root, 2, (path, attrs) ->
        attrs.isRegularFile())) {
    try {
        // 惰性访问可能在终端操作执行期间才打开后续目录。
        files.forEach(path -> System.out.println("发现: " + path));
    } catch (UncheckedIOException ex) {
        // 记录遍历位置和根因，避免把目录访问失败误认为匹配为空。
        System.err.println("遍历时读取目录失败: " + ex.getCause().getMessage());
    }
} catch (IOException ex) {
    // 这里处理创建搜索流之前就能确定的 I/O 问题。
    System.err.println("无法开始扫描: " + ex.getMessage());
}

“没有匹配结果”和“遍历某个目录失败”不是同一件事。前者可以正常得到空结果，后者应记录异常并由业务决定重试、跳过还是失败退出。若需要继续处理其他目录，可以把每个根目录的扫描放在独立的错误边界中。

结果复盘：一个可直接改造的完整示例

下面的示例把前面的规则收拢起来：从命令行接收根目录，最多进入两层，筛选至少 1 MiB 的普通日志文件，并在同一资源作用域内完成输出。

import java.io.IOException;
import java.io.UncheckedIOException;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.stream.Stream;

public class FindLogs {
    public static void main(String[] args) {
        Path root = args.length == 0 ? Path.of(".") : Path.of(args[0]);

        try (Stream files = Files.find(root, 2, (path, attrs) ->
                attrs.isRegularFile()
                        && attrs.size() >= 1024 * 1024
                        && path.getFileName().toString().endsWith(".log"))) {
            // 在关闭流之前完成消费，避免保留打开的目录。
            files.forEach(path -> System.out.println(path.toAbsolutePath()));
        } catch (UncheckedIOException ex) {
            // 终端操作阶段的目录访问失败要保留根因信息。
            System.err.println("扫描中断: " + ex.getCause().getMessage());
        } catch (IOException ex) {
            // 起点或初始目录打不开时，直接报告启动失败。
            System.err.println("无法启动扫描: " + ex.getMessage());
        }
    }
}

这个程序没有把“最大深度”误当成结果数量，也没有额外读取属性；同时它明确了流的所有权和两类异常边界。生产代码还可以把匹配条件抽成命名方法，让测试分别覆盖目录、符号链接、空文件和权限不足等情况。

相关问题

Files.find 和 Files.walk 有什么区别？

find 在遍历时直接拿到 BasicFileAttributes 并用匹配器筛选；walk 更像先得到路径流，再由后续 filter 组合条件。只按基本属性筛选时，find 的表达更集中。

maxDepth=0 为什么找不到子目录里的文件？

因为 0 代表只访问起点，不进入起点目录的子层。要访问直接子目录，至少要使用 1。

筛选普通文件为什么要调用 attrs.isRegularFile？

目录、符号链接和其他文件类型也可能出现在遍历结果中。先判断普通文件，再读取大小或后缀，可以避免把目录当成文件处理。

Files.find 返回的流可以跨方法返回吗？

技术上可以，但调用方必须承担关闭责任。更稳妥的方式是在创建流的方法内消费或收集结果，只把列表等已关闭资源的数据返回出去。

记住三件事即可：用 maxDepth 控制范围，用 BasicFileAttributes 控制条件，用 try-with-resources 控制生命周期。这样 Java 文件扫描既能保持最小代码量，也不会把目录资源和异常边界留给调用者猜测。