Java WatchService 收到 OVERFLOW 怎么处理

Java WatchService 收到 OVERFLOW 时，应把该目录的事件增量视为不完整，重新扫描目录并对齐本地索引。只打印日志然后继续消费，可能让已经漏掉的新增或删除永久留在错误状态；单独调用 reset() 也不能补回丢失的事件。

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

OVERFLOW 改变的是可信度，不是目录内容

正常情况下，通知可以提示某个目录项发生了变化。溢出意味着其中一部分通知可能已经被丢弃，此时无法根据剩余通知还原完整历史。应把事件当作“需要重新观察”的提示，把文件系统当前状态当作重建目录视图的依据。这是处理策略的变化，并不是本文宣称 Java 新增了一个恢复接口。

OVERFLOW 不需要单独注册；它的 context() 由实现决定，可能为 null，count() 也不能当作精确的漏失文件数量。先判断事件种类，再考虑读取普通事件的相对路径。

把忽略溢出改成重新建立目录快照

旧写法经常对溢出直接 continue，然后只处理其余 create、delete、modify。问题是它默认“我收到了所有重要通知”。新的处理约定应把目录标为脏，并安排一次完整重扫；重扫成功后再替换索引或比较差异。

例如原索引保留着已经删除的配置文件，仅补处理收到的修改事件不会删除这个旧记录。重扫时用新目录项集合与旧集合做差，才能得到需要移除的索引项。涉及数据库或外部副作用时，用文件业务标识和版本约束实现幂等；不要把一次文件通知直接等价成一次必须付款、发信或导入的业务事件。

监听循环怎样保留恢复机会

下面给出原创的单目录元数据索引示例，使用 Java 17 及以上语法。普通事件与溢出都合并为一次重扫，重点放在失败后保留恢复机会；它没有实现递归监听、内容哈希、外部业务提交或进程重启后的索引恢复。

import java.io.IOException;
import java.nio.file.*;
import java.nio.file.attribute.BasicFileAttributes;
import java.nio.file.attribute.FileTime;
import java.util.HashMap;
import java.util.Map;
import java.util.concurrent.TimeUnit;
import static java.nio.file.StandardWatchEventKinds.*;

public class DirectoryIndex {
    record Stamp(long size, FileTime modified, boolean directory) {}

    static Map scan(Path root) throws IOException {
        Map fresh = new HashMap();
        // 只扫描一层；遍历或属性读取失败时不返回半份快照
        try (DirectoryStream entries = Files.newDirectoryStream(root)) {
            for (Path path : entries) {
                BasicFileAttributes a = Files.readAttributes(
                    path, BasicFileAttributes.class, LinkOption.NOFOLLOW_LINKS);
                fresh.put(path.getFileName(),
                    new Stamp(a.size(), a.lastModifiedTime(), a.isDirectory()));
            }
        }
        return Map.copyOf(fresh);
    }

    public static void main(String[] args) throws Exception {
        if (args.length != 1) {
            throw new IllegalArgumentException("请提供监听目录");
        }
        Path root = Path.of(args[0]).toAbsolutePath().normalize();
        try (WatchService watcher = root.getFileSystem().newWatchService()) {
            // 先注册再扫描，扫描期间产生的通知仍可触发后续对账
            root.register(watcher, ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY);
            Map snapshot = scan(root);
            boolean dirty = false;
            while (!Thread.currentThread().isInterrupted()) {
                WatchKey key = watcher.poll(2, TimeUnit.SECONDS);
                if (key != null) {
                    boolean valid;
                    try {
                        for (WatchEvent> event : key.pollEvents()) {
                            if (event.kind() == OVERFLOW) {
                                // 不把 OVERFLOW 的 context 强转成 Path
                                dirty = true;
                                continue;
                            }
                            // 此示例对普通通知也做目录级合并，不逐条执行业务
                            dirty = true;
                        }
                    } finally {
                        valid = key.reset();
                    }
                    if (!valid) {
                        throw new IOException("目录监听已失效，需要恢复目录后重新注册");
                    }
                }
                if (dirty) {
                    try {
                        Map fresh = scan(root);
                        // 完整扫描成功后才替换；业务索引可在这里做幂等对账
                        snapshot = fresh;
                        dirty = false;
                    } catch (IOException | DirectoryIteratorException e) {
                        // 保留旧快照和脏标记；超时轮询也能再次尝试
                        System.err.println("目录扫描暂时失败：" + e.getMessage());
                    }
                }
            }
        }
    }
}

snapshot 是名称、大小、修改时间和目录标记组成的内存快照，供应用后续查询接入；示例没有伪造运行输出。大小和修改时间相同不代表内容相同，若目标是检测内容变化，应根据业务再读取内容或计算摘要。

dirty 在扫描成功后才清除，所以失败后即使没有新事件，带超时的 poll 也会给重试留下机会。初始化扫描失败则直接退出，由调用方处理启动失败，避免将空索引误认为真实目录。生产实现还应给重试增加退避和故障告警。

WatchKey 的事件批次处理后需要 reset；这里将工作合并到单一线程，避免同一目录多份快照互相覆盖。大型目录如果需要异步扫描，应为每个目录维护单一对账任务和变化代次：扫描期间又收到通知，就保留后续重扫需求，不要让较旧任务覆盖较新结果。

目录遍历不是文件系统事务，扫描期间文件仍可能变化。先注册再建立初始快照可以缩小通知空窗，但不能承诺重现所有短命文件。对于需要最终一致的目录视图，持续通知加周期性对账更稳妥；对于必须保存每次历史变更的需求，应选择具备持久日志语义的数据来源。

容量调整和常见问题

JDK 25 文档说明实现对每个被监听对象默认缓冲最多 512 个待处理事件，并提供 jdk.nio.file.WatchService.maxEventsPerPoll 系统属性调整为正整数。此处只按 JDK 25 文档说明该选项，不把它视为所有旧 JDK、所有实现通用的配置。

提高容量可以缓解部分突发压力，不能替代重扫。先把压缩、远程请求、解析大文件等耗时业务移出通知消费路径，并合并重复任务；同时记录溢出次数、扫描失败次数和最长未对账时间，区分持续过载与偶发突发。

收到 OVERFLOW 是否必须重建 WatchService？

不必因为溢出就无条件重建。先恢复目录视图，再按监听键是否有效决定是否重新注册；监听对象失效是另一类故障。

监听根目录能覆盖所有子目录吗？

不能把单目录注册当成递归监听。递归场景需要管理各子目录的注册及新增目录，并在相关范围内重扫。本文示例只处理根目录直接包含的条目。

收到修改通知就能立即读取完整文件吗？

不保证写入方已经完成。应与写入方约定提交方式，或设计延迟重试及完整性判断。网络文件系统的通知能力也依赖具体实现。

相关官方说明：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/file/StandardWatchEventKinds.html；监听键约定：https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/nio/file/WatchKey.html；注册与递归管理背景：https://docs.oracle.com/javase/tutorial/essential/io/notification.html（该教程面向 JDK 8）。