Java NIO WatchService 为什么会漏事件：目录注册、去重与重新扫描策略

把 Java 程序接到目录监听后，最容易误判的是“收到一个事件就等于文件已经稳定可读”。WatchService 实际上只负责把目录变化通知出来，事件可能合并，底层队列也可能出现 OVERFLOW；如果 WatchKey 失效而代码继续等待，后续变化还会像“突然漏掉”一样。更稳的做法是把事件当作触发信号，用路径去重，遇到不确定状态就重新扫描目录。

WatchService 漏事件根本不是什么底层Bug，大多是注册逻辑没覆盖嵌套文件夹、事件溢出时没补全扫描、重复触发的事件没有做路径去重导致的，只要把三层兜底逻辑补全，基本就能覆盖绝大多数生产场景的文件监听需求。

很多人刚接触 Java NIO 的 WatchService 时，都会遇到明明代码写了监听，偏偏文件改了、新建了没收到通知的情况，排查半天甚至怀疑JDK底层监听实现有问题。实际上这些漏通知的场景几乎都有明确的成因，对应成熟的处理方案。

先看清 WatchService 能保证什么

Java NIO 的监听模型是“目录注册—事件入队—取出 WatchKey—读取事件—重置 WatchKey”。ENTRY_CREATE、ENTRY_DELETE 和 ENTRY_MODIFY 描述的是目录项变化，不是文件内容提交完成的协议。比如编辑器保存一个大文件时，可能先写临时文件，再替换原文件，应用就会看到多次创建、修改或删除。

因此，监听线程适合唤醒索引刷新、配置重载或缩略图任务，不适合单独充当可靠消息队列。真正需要一致结果时，仍要以目录扫描或文件校验为准。

目录注册与 WatchKey 状态是第一道边界

try (WatchService watcher = FileSystems.getDefault().newWatchService()) {
    Path root = Path.of("/srv/inbox");
    root.register(watcher,
            StandardWatchEventKinds.ENTRY_CREATE,
            StandardWatchEventKinds.ENTRY_MODIFY,
            StandardWatchEventKinds.ENTRY_DELETE);

    for (;;) {
        WatchKey key = watcher.take();
        Path watchedDir = (Path) key.watchable();
        for (WatchEvent> event : key.pollEvents()) {
            WatchEvent.Kind> kind = event.kind();
            if (kind == StandardWatchEventKinds.OVERFLOW) {
                rescan(watchedDir);
                continue;
            }
            Path changed = watchedDir.resolve((Path) event.context());
            enqueueOnce(changed, kind);
        }
        if (!key.reset()) {
            removeDirectory(watchedDir);
            rescan(watchedDir.getParent());
        }
    }
}

这段最小代码有三个检查点：event.context() 是相对当前目录的路径；OVERFLOW 不需要显式注册也可能出现；reset() 返回 false 时，监听已经失效，不能继续把它当成正常等待。

为什么看见一个事件，却没有看到最终文件

事件通知和文件稳定之间存在时间差。写入方可能先创建文件，再分块写入；多个修改事件也可能被合并。如果消费者收到 ENTRY_CREATE 就立即读取，常见结果是读到空文件、半截文件，或者刚读完就被替换。

处理方式不要依赖固定等待。可以把路径放入一个去重队列，工作线程打开文件时检查大小是否稳定、是否能完成读取，并保留最后一次失败原因。对配置文件这类低频场景，收到事件后重新读取整个文件通常比猜测事件顺序更简单。

去重不是丢数据：把事件变成一次刷新提示

同一个路径在短时间内出现多次变化很正常。队列的键可以是规范化后的绝对路径，值保存最后事件类型和最近一次观察时间；处理时重新读取当前文件状态，而不是按队列中的每个事件回放。这样既能避免重复刷新，也不会把“文件后来又被删除”的状态误当成旧的修改结果。

如果监听多层目录，新增目录要先注册，再开始等待其中的文件变化。目录删除、移动和权限变化都要进入失效处理路径。这里别急着把监听线程重启无数次：先记录失效的目录、触发一次全量扫描，再决定是否重新注册。

生产环境的落地清单

• 启动时先扫描一次目录，建立基线，再开启事件监听。
• 每次取完事件都调用 reset()，并记录返回值。
• 将 OVERFLOW、目录删除、权限异常作为补偿扫描信号。
• 业务处理按路径幂等，不能假设事件只到达一次。
• 关闭时先停止消费者，再关闭 WatchService，避免新事件进入无人处理的队列。

相关问题

WatchService 能监听子目录吗？

可以，但需要为每个子目录分别注册；注册根目录不会自动覆盖后来创建的子目录。新增目录事件到达后，先注册它，再继续处理其内容。

OVERFLOW 一定代表文件丢失了吗？

它表示事件可能被丢弃，不能知道具体丢了哪些。最安全的处理是重新扫描受影响目录，用当前目录状态覆盖增量缓存。

为什么调用 reset 后仍然没有新事件？

先检查返回值和目录是否仍存在。返回 false 说明 key 已失效；返回 true 但没有新事件，则要确认监听线程仍在等待、目录注册对象没有被替换。

小结

WatchService 的正确用法不是把事件当成完整日志，而是把它当作刷新提示：目录负责注册，WatchKey 负责排队，业务层负责去重、稳定性检查和补偿扫描。只要把 OVERFLOW 与 reset() 失败纳入正常分支，文件监听就不会因为一次异常通知而悄悄失去后续变化。