Java DirectoryStream 迭代器抛异常后怎样确保资源关闭

我在把旧的目录扫描工具迁到更稳的资源管理写法时，最容易忽略的不是 Files.newDirectoryStream 怎么调用，而是迭代器抛异常以后谁负责关闭目录流。结论很明确：DirectoryStream 创建时就持有目录访问资源，应直接放进 try-with-resources；遍历阶段的 I/O 错误按 DirectoryIteratorException 处理，再从它的原因中取出 IOException。

官方地址：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/file/DirectoryStream.html

不要把目录流交给循环结束或垃圾回收“顺便处理”。把 DirectoryStream 声明为资源，try-with-resources 会在正常结束、遍历异常和显式抛错时执行关闭；如果关闭阶段另有异常，Java 会把它放进主异常的 suppressed 列表。

从手写关闭迁到 try-with-resources

旧代码常把目录流放在变量里，再用 finally 判断是否为空并调用 close()。这种写法并非一定错误，但异常分支多时，打开失败、遍历失败和关闭失败很容易被写成不同的处理逻辑。迁移时只需要把资源创建表达式放进括号，遍历代码保持在同一个作用域内。

import java.io.IOException;
import java.nio.file.DirectoryStream;
import java.nio.file.Files;
import java.nio.file.Path;

static void printEntries(Path dir) throws IOException {
    // 目录流在创建时就获得资源，声明后由 try-with-resources 负责关闭。
    try (DirectoryStream stream = Files.newDirectoryStream(dir)) {
        // DirectoryStream 只保证一个迭代器，直接使用增强 for 即可。
        for (Path entry : stream) {
            System.out.println(entry.getFileName());
        }
    }
}

这里的关键不是把代码写短，而是让关闭动作和资源建立处相邻。Oracle 的 API 明确说明，目录流关闭会释放关联资源，未关闭可能造成资源泄漏；所以不要把 DirectoryStream 作为长期缓存对象，也不要期待迭代器自行释放它。

遍历异常与 close 异常要分层记录

目录访问中的 I/O 错误可能在迭代器的 hasNext() 或 next() 处表现为 DirectoryIteratorException，真正的 IOException 位于它的原因链中。API 还说明 hasNext() 会至少预读一个元素，因此当它返回 true 后紧跟的 next() 不会因为该次预读的 I/O 错误再次失败；这不代表后续迭代永远不会失败。

import java.io.IOException;
import java.nio.file.DirectoryIteratorException;
import java.nio.file.DirectoryStream;
import java.nio.file.Files;
import java.nio.file.Path;

static void readJavaFiles(Path dir) throws IOException {
    try (DirectoryStream stream = Files.newDirectoryStream(dir, "*.java")) {
        for (Path entry : stream) {
            // 过滤只影响业务处理，不改变 DirectoryStream 的关闭责任。
            System.out.println(entry);
        }
    } catch (DirectoryIteratorException ex) {
        // 迭代器把 I/O 错误包装成运行时异常，优先还原原始 IOException。
        IOException cause = ex.getCause();
        if (cause != null) {
            // 关闭阶段的附加错误仍挂在包装异常上，转交到原因对象的诊断链。
            for (Throwable suppressed : ex.getSuppressed()) {
                cause.addSuppressed(suppressed);
            }
            throw cause;
        }
        throw ex;
    }
}

这个 catch 只负责迭代异常；目录流打开失败或正常退出时的 close() 失败仍按方法声明的 IOException 传播。不要用 ex.getMessage() 代替 getCause()，因为消息适合人读，原因对象才是可继续分类和记录的 I/O 错误。

关闭阶段的附加错误怎样保留

try-with-resources 的规则是：如果主体已经抛出一个主异常，关闭资源时又抛出另一个异常，主异常继续作为主线，关闭异常通过 Throwable.getSuppressed() 保存。这样既不会让清理失败覆盖目录遍历失败，也不会静默丢掉清理阶段的线索。

static void logDirectoryFailure(Path dir) throws IOException {
    try (DirectoryStream stream = Files.newDirectoryStream(dir)) {
        for (Path entry : stream) {
            // 业务处理异常和关闭异常应分开观察，避免只记录最后一条消息。
            inspect(entry);
        }
    } catch (DirectoryIteratorException ex) {
        // 先记录包装异常的类型，方便区分迭代阶段与打开阶段。
        log("iterator", ex);
        for (Throwable suppressed : ex.getSuppressed()) {
            // suppressed 通常来自 close，是主异常之外的附加诊断线索。
            log("close-suppressed", suppressed);
        }
        throw ex;
    }
}

static void inspect(Path entry) throws IOException {
    // 示例只表示业务检查位置，不假设目录中存在固定文件内容。
    if (entry.getFileName() == null) {
        throw new IOException("目录项缺少文件名");
    }
}

static void log(String phase, Throwable error) {
    // 日志只保留阶段和异常链，不把完整路径或用户输入无条件写入公共日志。
    System.err.println(phase + ": " + error.getClass().getName());
}

如果团队只关心最终的 IOException，可以在统一日志层展开 getCause() 和 getSuppressed()；如果需要保留 Java 原始异常形态，则直接记录 DirectoryIteratorException 更稳。两种选择都比只打印一行字符串可靠。

迁移清单：把目录流生命周期固定下来

我在迁移这类代码时会按下面的顺序检查：资源创建是否处于 try-with-resources；方法是否只创建一个迭代器；是否把 DirectoryIteratorException 的 IOException 原因记录下来；是否保留 close 阶段的 suppressed 信息；是否把过滤、业务处理和资源清理分开。目录流的迭代顺序不应被当作稳定排序，本文也不把这个问题和递归遍历混在一起。

相关问题

DirectoryStream 能不能反复调用 iterator？ 不能把它当普通 Iterable；API 只支持单个迭代器，重复获取可能抛出 IllegalStateException。

为什么只 catch IOException 还接不到遍历错误？ 因为迭代阶段的 I/O 错误先包装成 DirectoryIteratorException，需要从 getCause() 取出原始 IOException。

close 抛出的异常会覆盖遍历异常吗？ 主体已有异常时，关闭异常通常进入 getSuppressed()；应把它作为附加诊断信息记录。