WatchService不支持递归监控，需手动遍历子目录逐个register；WatchKey需显式reset且检查返回值；无ENTRY_RENAME事件，重命名被拆为DELETE+CREATE；高频小文件场景易丢事件，不适合日志采集等高吞吐场景。
WatchService注册路径必须是父目录，不能监控子目录递归
Java的WatchService本身不支持递归监听，register()方法只对**直接子节点**有效。比如你用path.register(watcher, ENTRY_CREATE, ENTRY_DELETE, ENTRY_MODIFY)注册了/home/user/docs，那只有这个目录下一级的文件或文件夹变动会触发事件，/home/user/docs/report/2024.txt的修改根本不会上报。
常见错误现象：StandardWatchEventKinds.ENTRY_MODIFY在嵌套子目录里完全静默；或者误以为调用一次register()就能“一劳永逸”。
- 必须手动遍历所有子目录，对每个
Path单独调用register() - 注意
Files.walkFileTree()配合SimpleFileVisitor是常用遍历手段，但要避开符号链接（否则可能死循环） - 注册后路径不能被删除或移动，否则对应
WatchKey失效且不会自动重连
WatchKey需要主动reset，否则后续事件会被丢弃
WatchKey是一次性消费的——每次watcher.take()拿到一个WatchKey后，它的内部状态就变成invalid，除非你显式调用key.reset()。漏掉这步，后续任何变化都不会再进入队列。
典型翻车场景：在while (true)循环里取到key、处理完事件，却忘记key.reset()，结果程序“卡住”不再响应新事件，日志里也无报错。
立即学习“Java免费学习笔记（深入）”；
当用户要求为 Java 代码添加注释、修改注释、审查注释、整理注释格式，或要求按照代码注释规范处理 Java 文件时，使用本技能。本技能用于统一生成和维护 Java 类注释模板、按 Git 对比 release 判断版本号、补充每行代码上方中文块注释、调整注释空行规则，并保持 Java 文件 UTF-8 无 BOM 编码。典型触发场景包括：补充类注释、更新 @version、检查 @author 来源、整理行尾注释、把注释放到代码上一行、检查注释是否符合规范、构建前检查 Java 注释风格。
- 必须在
try块内调用key.reset()，且要检查返回值：if (!key.reset()) break;（返回false说明路径已不可访问） - 不要在
catch里吞掉异常后还强行reset()，尤其ClosedWatchServiceException发生时再调用会抛IllegalStateException - 多线程环境下，一个
WatchKey不应被多个线程并发reset
文件重命名和移动触发的是ENTRY_CREATE + ENTRY_DELETE，不是单独的RENAME事件
Java 7+ 的WatchService没有ENTRY_RENAME这种标准事件类型。系统底层（如Linux inotify）的rename操作，在JVM层被拆解为两个独立事件：ENTRY_DELETE（原路径）和ENTRY_CREATE（新路径），中间没有原子性保证，也没有携带“关联ID”。
这意味着：你无法仅靠事件类型判断“这是重命名”，更没法安全还原原始文件名。很多业务逻辑（比如监听上传完成、防止重复处理）因此出错。
- 如果必须识别重命名，得结合事件时间戳（
System.nanoTime()）、文件大小、内容hash做近似匹配，但有竞态风险 - Windows上
ENTRY_MODIFY可能在重命名后额外触发一次（因文件属性更新），Linux则通常不会 - 避免依赖“先删后建”的顺序——实际调度中两个事件可能乱序到达，尤其高负载时
WatchService不适合高频小文件场景，容易丢事件或阻塞
当每秒产生几十个以上小文件（比如日志轮转、临时缓存写入），WatchService的事件队列（默认无界但受系统限制）可能溢出，或take()处理速度跟不上，导致WatchKey失效、事件丢失，甚至整个服务卡死。
这不是代码写得不对，而是设计定位问题：WatchService面向低频、用户级操作通知（如IDE监听源码变更），不是高吞吐文件采集管道。
- 监控日志目录时，优先考虑logrotate配合
inotifywait命令行工具，或直接读tail -F输出 - 若必须用Java，建议加一层缓冲（如
BlockingQueue暂存WatchEvent），并设置合理超时避免take()永久阻塞 - Linux下注意
/proc/sys/fs/inotify/max_user_watches值，默认常为8192，大量子目录注册时容易触顶，报java.io.IOException: No space left on device
真正难的不是怎么注册监听，是怎么在路径变动、服务重启、权限突变、事件风暴这些边界条件下，让通知既不漏也不重——而WatchService本身几乎不帮你扛这些。
