java nio watchservice 是基于操作系统原生事件的轻量级目录监听机制，支持递归监控与事件回调封装，需注意 overflow 处理、目录失效检测及异常隔离。

Java NIO 的 WatchService 是监听目录变化、构建轻量级文件监控服务的核心机制。它不轮询，而是基于操作系统原生事件（如 Linux inotify、Windows ReadDirectoryChangesW），响应快、资源省，适合配置热加载、日志归档、上传触发等生产场景。

注册目录并启动监听循环

WatchService 只能监听目录（不能直接监听单个文件），需先获取服务实例，再注册目标路径及关注的事件类型：

• 调用 FileSystems.getDefault().newWatchService() 获取线程安全的服务实例；
• 用 Paths.get("/path/to/watch") 转为 Path 对象；
• 调用 path.register(watcher, ENTRY_CREATE, ENTRY_MODIFY, ENTRY_DELETE) 完成注册，返回 WatchKey；
• 在独立线程中循环调用 watcher.take() 阻塞等待事件（推荐，避免空转）；
• 每次拿到 WatchKey 后，必须调用 key.pollEvents() 获取事件，并在处理完后立即调用 key.reset()，否则该 key 将不再接收新事件。

处理常见事件与边界情况

实际使用中，以下细节直接影响稳定性：

Java Maven Common

Java Maven 项目审查工作流的通用输入处理。当 Java Maven 项目以 ZIP压缩包或 GitLab 仓库 URL 形式提供且需要...时使用。

下载

• OVERFLOW 事件必须跳过：内核事件队列满时会触发，表示可能丢失事件，此时应记录日志并考虑全量扫描恢复状态；
• 文件修改行为不可靠：ENTRY_MODIFY 在不同编辑器下表现不一（如先写临时文件再重命名，可能只收到 CREATE + DELETE）；
• 目录失效需检测：若被监听目录被删除或权限变更，key.reset() 会返回 false，此时应退出循环或尝试重建；
• 异常需捕获隔离：take() 可能抛 InterruptedException，reset() 可能因服务关闭抛 ClosedWatchServiceException，建议分别处理并优雅重建。

支持子目录递归监听

WatchService 默认只监听注册目录的一级内容，子目录变动不会上报。要实现“全目录树”监控，需手动递归：

• 首次注册时，遍历目标目录下所有子目录，逐个调用 register()；
• 监听到 ENTRY_CREATE 且 event.context() 是目录时，立即对该新目录执行注册；
• 监听到 ENTRY_DELETE 且是目录时，可选择从已注册列表中移除对应 WatchKey（避免无效引用）。

封装为可复用的监控组件

建议将监听逻辑与业务解耦，例如定义回调接口：

public interface FileChangeHandler {
    void onFileChanged(Path fullPath, WatchEvent.Kind> kind);
}

再封装一个 DirectoryWatcher 类，内部维护 WatchService 和注册关系，对外暴露 start() / stop() 方法。启动时开启守护线程执行监听循环，停止时调用 watchService.close() 并中断线程。这样既便于单元测试，也方便集成 Spring 等框架生命周期管理。

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南