Java walkFileTree 的 postVisitDirectory 收到异常时怎么处理

在 Java 的目录树任务里，postVisitDirectory 经常被当成“目录遍历完成后的清理回调”。这个理解只对了一半：当目录迭代过程中发生 I/O 错误，或者遍历被提前中断时，回调仍然可能被调用，只是第二个参数 exc 不再是 null。

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

判断目录是否完整收尾，先看 exc：null 表示目录及其后代正常完成遍历；非 null 表示迭代提前结束，当前目录的结果不能直接按“完整成功”处理。随后再根据任务是否允许部分完成，选择记录后继续、终止遍历或抛出原异常。

规模背景：为什么目录收尾会成为瓶颈

小目录里，开发者通常只在 visitFile 中做业务处理，最后在 postVisitDirectory 删除空目录、提交目录统计或写一条完成日志。文件数量变大、目录位于网络盘、挂载点发生短暂抖动后，真正危险的不是回调没有执行，而是回调执行了却被当成“正常完成”。

在批量归档任务中，一个目录可能已经处理完一部分文件，随后目录流在继续读取子项时收到 IOException。如果代码仍然提交“目录已完成”事件，下游就会把一个只有部分内容的归档当成完整结果。这个问题与权限跳过策略不同：这里要处理的是遍历框架明确传回的收尾异常。

原架构瓶颈：只处理 visitFile 会丢掉目录级失败

下面这种写法看起来能工作：文件处理失败就抛出，目录结束后直接写“完成”。问题在于它没有检查 exc，因此无法区分“所有子项都遍历到了”和“目录迭代提前结束”。

import java.io.IOException;
import java.nio.file.FileVisitResult;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.SimpleFileVisitor;
import java.nio.file.attribute.BasicFileAttributes;

public final class UnsafeTreeJob {
    public static void run(Path root) throws IOException {
        Files.walkFileTree(root, new SimpleFileVisitor() {
            @Override
            public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
                    throws IOException {
                // 文件级任务只负责处理当前文件，异常继续交给遍历框架。
                System.out.println("处理文件: " + file);
                return FileVisitResult.CONTINUE;
            }

            @Override
            public FileVisitResult postVisitDirectory(Path dir, IOException exc)
                    throws IOException {
                // 错误：不检查 exc 就发布“目录已完成”事件。
                System.out.println("目录已完成: " + dir);
                return FileVisitResult.CONTINUE;
            }
        });
    }
}

这段代码的问题不是返回值一定错误，而是完成事件的前置条件不完整。官方接口说明中，postVisitDirectory 也会在目录迭代提前结束时调用，此时异常对象就是导致提前结束的原因。高压任务最先要修复的是状态模型，而不是盲目增加重试次数。

新架构：把 postVisitDirectory 变成明确的状态分流点

一个可复用的处理顺序是：先判断 exc，再决定当前目录的业务状态，最后返回遍历控制结果。对于删除目录树、生成不可重复归档等任务，我通常把非空异常视为失败边界，保留目录和已处理数量后抛出；对于允许部分结果的索引扫描，则记录为 PARTIAL，但不发送完整成功事件。

import java.io.IOException;
import java.nio.file.FileVisitResult;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.SimpleFileVisitor;
import java.nio.file.attribute.BasicFileAttributes;

public final class SafeTreeJob {
    private final long[] processed = new long[1];

    public void run(Path root) throws IOException {
        Files.walkFileTree(root, new SimpleFileVisitor() {
            @Override
            public FileVisitResult visitFile(Path file, BasicFileAttributes attrs)
                    throws IOException {
                // 先完成文件动作，再累计已确认处理的数量。
                processFile(file);
                processed[0]++;
                return FileVisitResult.CONTINUE;
            }

            @Override
            public FileVisitResult postVisitDirectory(Path dir, IOException exc)
                    throws IOException {
                if (exc != null) {
                    // 非空 exc 说明目录没有完整走完，记录上下文后失败退出。
                    recordPartial(dir, processed[0], exc);
                    throw exc;
                }

                // 只有正常收尾才允许发布“目录完整”事件。
                recordCompleted(dir, processed[0]);
                return FileVisitResult.CONTINUE;
            }
        });
    }

    private void processFile(Path file) {
        // 这里放归档、校验或索引动作；示例不依赖外部系统。
    }

    private void recordPartial(Path dir, long count, IOException exc) {
        // 记录目录、已处理数量和原始异常，供恢复任务定位断点。
        System.err.println("目录未完整遍历: " + dir
                + ", processed=" + count + ", error=" + exc.getMessage());
    }

    private void recordCompleted(Path dir, long count) {
        // 完成事件只代表当前目录的遍历已正常收尾。
        System.out.println("目录完整: " + dir + ", processed=" + count);
    }
}

这里的关键不是“所有异常都抛出”，而是把异常和业务承诺对齐。postVisitDirectory 返回 CONTINUE 只能说明遍历控制器继续处理其他路径，并不等于当前目录已经完整成功；如果选择继续，业务记录中必须保留部分状态。

关键取舍：继续、终止还是抛出原异常

FileVisitResult 提供 CONTINUE、SKIP_SIBLINGS、SKIP_SUBTREE 和 TERMINATE。在 postVisitDirectory 中，最稳妥的选择取决于任务能否接受部分完成，而不是取决于哪一个枚举值看起来更“温和”。

如果一个异常目录之后的兄弟目录仍然有价值，可以记录部分状态后返回 CONTINUE；如果结果必须完整，返回 TERMINATE 或直接抛出异常更容易让调度器感知失败。不要用 SKIP_SUBTREE 掩盖已经发生的收尾异常，它主要描述进入目录前是否跳过子树，不能替代失败状态。

上线结果：用可恢复状态替代盲目重跑

当批量任务把目录结果分成 COMPLETED、PARTIAL 和 FAILED 后，调度层才能做正确动作：完整目录不重复处理，部分目录进入人工或自动重试，失败任务保留原始异常。这样即使一次扫描跨越多个挂载点，也不会因为一个目录异常而丢失所有已确认结果。

enum DirectoryState {
    COMPLETED,
    PARTIAL,
    FAILED
}

record DirectoryOutcome(
        Path directory,
        DirectoryState state,
        long processedFiles,
        String errorMessage) {
    // outcome 是恢复任务的最小上下文，不把异常只留在控制台。
}

static DirectoryOutcome toOutcome(Path dir, long processed, IOException exc) {
    if (exc == null) {
        // null 只表示本次目录迭代正常完成。
        return new DirectoryOutcome(dir, DirectoryState.COMPLETED, processed, "");
    }

    // 是否自动重试由调度层决定，这里先保留为部分结果。
    return new DirectoryOutcome(dir, DirectoryState.PARTIAL, processed,
            exc.getClass().getSimpleName() + ": " + exc.getMessage());
}

恢复时不要从整个根目录无条件重跑。优先按 DirectoryOutcome 找到异常目录，重新计算该目录下的任务边界，并保证文件动作具备幂等性。如果任务本身不可恢复，就让调度器看到 FAILED，交给人工确认，而不是把异常转换成一条误导性的成功日志。

后续改进：让目录级异常进入验收清单

在提交一轮文件树任务前，可以用下面的清单检查收尾逻辑：

• 是否在 postVisitDirectory 中显式判断了 exc？
• 目录正常完成和部分完成是否使用不同状态，完成事件是否只在 exc == null 时发送？
• 异常记录是否包含目录路径、已处理数量、异常类型和恢复线索？
• 返回 CONTINUE 时，业务是否真的允许部分结果？返回终止时，调度器是否能感知失败？
• 文件动作是否幂等，重试是否会重复删除、重复归档或覆盖已有结果？

最终可以把这个问题归纳为一句话：postVisitDirectory 是目录遍历的结果确认点，不是无条件的成功回调。先读取 exc，再选择业务状态和遍历控制结果，才能让大批量文件任务在异常发生后仍然可解释、可恢复。

常见问题

postVisitDirectory 的 exc 为什么不是只在 visitFile 抛错时出现？ 因为目录迭代器本身在继续读取目录项时也可能发生 I/O 错误，接口会把导致提前结束的异常传到目录收尾回调。

exc == null 是否代表目录中的每个业务动作都成功？ 它只说明文件树遍历正常完成。业务动作如果自行捕获并记录失败，还需要额外的业务计数或状态来判断是否可提交完整结果。

为什么不能总是返回 CONTINUE？ 因为遍历控制继续和当前目录业务成功是两件事。允许继续时可以保留其他目录的价值，但必须把当前目录标记为部分结果。