怎么监听文件/目录的变化？NIO.2 的 WatchService 是什么、怎么用？

简化版

WatchService 是 Java 7（NIO.2）提供的「文件系统监听服务」——它能监听某个目录，当目录里的文件发生「创建、修改、删除」时通知你，不用自己写「死循环轮询、比较文件修改时间」的土办法。用法三步：① 创建 WatchService（FileSystems.getDefault().newWatchService()）；② 把要监听的目录注册进去（dir.register(watchService, ENTRY_CREATE, ENTRY_MODIFY, ENTRY_DELETE)，指定关心哪些事件）；③ 循环取事件（watchService.take() 阻塞等待事件，拿到后遍历 pollEvents() 处理每个变化）。为什么比轮询好：WatchService 底层用操作系统的文件系统事件通知机制（Linux 的 inotify、Windows 的 ReadDirectoryChangesW、macOS 的 FSEvents），是「事件驱动」的——有变化 OS 才通知，没变化就阻塞等待，不消耗 CPU；而轮询要不停地扫描比较，浪费 CPU 且有延迟。典型用途：配置文件热加载（配置改了自动重新加载）、监听日志目录、开发工具的文件变化触发（如 DevTools）。注意：默认只监听「直接子项」，不递归子目录（要递归得自己注册每个子目录）。

详细版

WatchService 三种事件类型：

事件	含义
ENTRY_CREATE	目录里新建了文件/子目录
ENTRY_MODIFY	文件被修改
ENTRY_DELETE	文件/子目录被删除
OVERFLOW	事件太多丢失了（要处理这种情况）

// ① 创建 WatchService
WatchService watchService = FileSystems.getDefault().newWatchService();

// ② 注册目录 + 关心的事件
Path dir = Paths.get("/config");
dir.register(watchService,
    StandardWatchEventKinds.ENTRY_CREATE,
    StandardWatchEventKinds.ENTRY_MODIFY,
    StandardWatchEventKinds.ENTRY_DELETE);

// ③ 循环取事件处理
while (true) {
    WatchKey key = watchService.take();   // 阻塞，直到有事件（不消耗 CPU）
    for (WatchEvent<?> event : key.pollEvents()) {
        WatchEvent.Kind<?> kind = event.kind();
        Path fileName = (Path) event.context();   // 变化的文件名（相对路径）
        System.out.println(kind + ": " + fileName);
        // 处理变化：如配置文件改了 → 重新加载
    }
    boolean valid = key.reset();   // ★ 必须 reset，让 key 能继续接收后续事件
    if (!valid) break;             // 目录不可访问了（如被删）
}

⚠️ WatchService 有几个容易踩的坑：① 必须 key.reset()——处理完一批事件后要调 key.reset() 让这个 WatchKey 恢复到「就绪」状态、能继续接收后续事件；忘了 reset，之后的变化就收不到了。② 默认不递归——注册一个目录只监听它的「直接子项」，子目录里的变化收不到；要监听整棵目录树，得遍历所有子目录、每个都 register（新建子目录时还要动态注册）。③ 一次修改可能触发多个事件——比如保存一个文件，有的编辑器/系统会触发多次 ENTRY_MODIFY（或先 DELETE 再 CREATE），要注意「去重/防抖」。④ OVERFLOW——如果短时间变化太多，事件队列溢出会产生 OVERFLOW 事件（表示「有些事件丢了」），健壮的代码要处理它（如全量重新扫描）。

完整版教学

一、问题：怎么知道文件变了

先理解「监听文件变化」的需求和土办法的问题：

需求：某个文件/目录变了，要及时知道并做出反应
  - 配置文件改了 → 重新加载配置（热更新）
  - 日志目录来了新文件 → 处理它
  - 开发时源码改了 → 触发重新编译/重启（DevTools）

土办法（轮询）：
  while (true) {
      检查文件的 lastModified 时间戳
      如果比上次记录的新 → 文件变了，处理
      Thread.sleep(1000);   // 每秒查一次
  }

轮询的问题：
  ① 消耗 CPU——不停地扫描、比较，即使文件没变也在忙
  ② 有延迟——sleep 间隔内的变化要等下次轮询才发现
  ③ 扩展性差——监听很多文件时，每次都要全扫一遍
  ④ 可能漏——两次轮询之间"改了又改回"可能检测不到

想要的：文件变了"主动通知"我，没变就别占资源
  → 事件驱动，而不是轮询 → WatchService

监听文件变化的需求（配置热更新、日志处理、DevTools 触发）用土办法轮询（死循环查 lastModified + sleep）有问题：消耗 CPU（不停扫描）、有延迟（sleep 间隔）、扩展性差（监听多文件全扫）、可能漏（两次轮询间改了又改回）。想要的是「文件变了主动通知、没变别占资源」——事件驱动而非轮询，这就是 WatchService。理解「监听文件变化需求、轮询土办法的问题(消耗 CPU/有延迟/扩展性差/可能漏)、想要事件驱动主动通知」，就理解了 WatchService 要解决的问题。

二、WatchService 的原理：OS 事件通知

WatchService 比轮询好，是因为它用「操作系统的文件系统事件机制」：

WatchService 底层依赖 OS 的文件系统事件通知：
  Linux：inotify（内核提供的文件系统事件机制）
  Windows：ReadDirectoryChangesW
  macOS：FSEvents / kqueue

工作方式（事件驱动）：
  1. 你注册"监听某目录的某些事件"
  2. OS 内核帮你"盯着"这个目录
  3. 目录里有变化时，OS 内核主动产生一个事件、通知 WatchService
  4. 你的线程从 WatchService take() 拿到事件（平时阻塞等待，不占 CPU）

对比轮询：
  轮询：你主动不停地问"变了吗？变了吗？"（累、慢）
  WatchService：OS 变了才告诉你（省、快）
  → 没变化时，你的线程阻塞在 take()，几乎不消耗 CPU
  → 有变化时，OS 立即通知，几乎无延迟

所以 WatchService 是"把监听的活交给 OS"，比自己轮询高效得多

WatchService 比轮询好，是因为它用 OS 的文件系统事件机制（Linux 的 inotify、Windows 的 ReadDirectoryChangesW、macOS 的 FSEvents）——事件驱动：注册后 OS 内核帮你盯着目录，有变化时主动产生事件通知 WatchService，你的线程 take() 时平时阻塞等待不占 CPU、有变化立即被唤醒。对比轮询「你主动不停地问」，WatchService 是「OS 变了才告诉你」，省 CPU 又几乎无延迟。理解「WatchService 底层用 OS 文件系统事件机制(inotify/ReadDirectoryChangesW/FSEvents)、事件驱动 OS 主动通知、平时阻塞不占 CPU 有变化立即唤醒、比轮询高效」，就理解了它高效的原理。

三、三步用法

WatchService 的用法是固定的三步：

① 创建 WatchService：
   WatchService ws = FileSystems.getDefault().newWatchService();

② 注册要监听的目录 + 关心的事件类型：
   Path dir = Paths.get("/config");
   dir.register(ws, ENTRY_CREATE, ENTRY_MODIFY, ENTRY_DELETE);
   → 注意：register 是在 Path 上调，监听这个目录
   → 只能注册"目录"（不能直接注册一个文件；要监听某文件，
     监听它所在的目录，再在事件里判断是不是那个文件）

③ 循环取事件处理：
   while (true) {
       WatchKey key = ws.take();          // 阻塞等待事件（或 poll 非阻塞）
       for (WatchEvent<?> e : key.pollEvents()) {
           Kind<?> kind = e.kind();        // 什么事件（CREATE/MODIFY/DELETE）
           Path name = (Path) e.context(); // 哪个文件（相对目录的名字）
           // 处理...
       }
       key.reset();                        // ★ 重置 key，继续接收
   }

take() vs poll()：
  take()：阻塞，直到有事件（常用）
  poll()：非阻塞，没事件返回 null
  poll(timeout)：等一段时间

WatchService 三步：① 创建（FileSystems.getDefault().newWatchService()）；② 注册目录+事件（dir.register(ws, ENTRY_CREATE, ...)，只能注册目录不能直接注册文件，要监听某文件就监听其所在目录再判断）；③ 循环取事件（take() 阻塞等待，遍历 pollEvents() 处理，event.kind() 是事件类型、event.context() 是文件名，处理完 key.reset()）。take() 阻塞、poll() 非阻塞。理解「三步:创建 newWatchService、注册 dir.register(只能注册目录)、循环 take()取 key 遍历 pollEvents 处理再 reset、take 阻塞 poll 非阻塞」，就掌握了基本用法。

四、WatchKey 与 reset

理解 WatchKey 的生命周期，尤其是 reset 的重要性：

WatchKey 的状态：
  Ready（就绪）：等待事件
  Signalled（已触发）：有事件了，被 take/poll 取出
  Invalid（无效）：目录不可访问了（被删/移动）

关键流程：
  1. 注册后，WatchKey 处于 Ready
  2. 有事件 → 变成 Signalled，能被 take()/poll() 取出
  3. ★ 取出并处理后，必须 key.reset()：
     把 key 从 Signalled 变回 Ready，才能接收后续事件
     → 忘了 reset：key 停在 Signalled，之后的事件都收不到！
  4. reset() 返回 false → key 已 Invalid（目录没了）→ 停止监听

为什么要显式 reset：
  一个 WatchKey 在被取出到 reset 之间，OS 的新事件会"攒着"
  reset 时把这批攒的事件一起给你（避免处理时丢事件）
  → 所以 reset 是"我处理完了，可以给我下一批"的信号

★ 忘 reset 是最常见的 bug：第一次事件收到了，后面就再也收不到

WatchKey 有 Ready（就绪）、Signalled（已触发）、Invalid（无效） 三状态。关键流程：注册后 Ready → 有事件变 Signalled 被取出 → 处理后必须 key.reset() 变回 Ready 才能接收后续事件（忘 reset 则 key 停在 Signalled、之后事件都收不到——最常见的 bug：第一次收到后面再也收不到）→ reset() 返回 false 说明 Invalid（目录没了）停止监听。reset 是「我处理完了、给我下一批」的信号。理解「WatchKey 三状态 Ready/Signalled/Invalid、处理后必须 reset 变回 Ready 才能收后续事件(忘 reset 是最常见 bug)、reset 返 false 说明目录没了」，就掌握了 WatchKey 和 reset 的关键。

五、坑：递归、重复事件、OVERFLOW

WatchService 有几个必须知道的坑：

坑一：默认不递归监听子目录
  register 一个目录，只监听它的"直接子项"
  子目录里的变化收不到！
  要监听整棵树：
    - 遍历所有子目录，每个都 register（Files.walkFileTree）
    - 新建子目录时，还要动态 register 那个新目录
  → 递归监听要自己实现（JDK 没直接提供）

坑二：一次修改可能触发多个事件
  保存一个文件，有的编辑器/系统会：
    - 触发多次 ENTRY_MODIFY
    - 或先 ENTRY_DELETE 再 ENTRY_CREATE（原子替换）
  → 处理时要"去重/防抖"（如收到事件后延迟一点，合并短时间内的多次）

坑三：OVERFLOW 事件
  短时间变化太多，事件队列满了 → 产生 OVERFLOW 事件
  表示"有些事件丢了"
  → 健壮的代码要处理 OVERFLOW（如触发一次全量扫描，重新同步状态）

坑四：跨平台差异
  不同 OS 的实现不同（inotify/FSEvents...），行为可能有细微差别
  （如事件的粒度、时序）→ 别过度依赖精确的事件序列

WatchService 的坑：① 默认不递归（register 只监听目录的直接子项，子目录变化收不到，要递归得遍历所有子目录各自 register、新建子目录还要动态注册）；② 一次修改可能触发多个事件（多次 MODIFY 或 DELETE+CREATE，要去重/防抖）；③ OVERFLOW（变化太多队列溢出、有事件丢了，要处理如全量重扫）；④ 跨平台差异（不同 OS 实现不同、别过度依赖精确事件序列）。理解「坑:默认不递归(要自己遍历子目录注册)、一次修改可能多个事件(去重防抖)、OVERFLOW(事件丢了要全量重扫)、跨平台差异」，就避开了 WatchService 的常见陷阱。

六、应用与替代

WatchService 的应用场景，以及有更好用的替代库：

典型应用：
  ① 配置文件热加载：监听配置目录，配置改了自动重新加载
  ② 日志/数据目录监听：来了新文件就处理
  ③ 开发工具：源码改了触发重编译/重启（DevTools 类似思路）
  ④ 文件同步、增量索引

实践建议：
  - 监听放在单独的线程（take() 会阻塞）
  - 做好去重/防抖（避免一次保存触发多次处理）
  - 处理 OVERFLOW（兜底全量扫描）
  - 需要递归监听就遍历子目录 register

更好用的替代（生产常用）：
  Apache Commons IO 的 FileAlterationMonitor/Observer：
    - 封装了递归监听、去重等，用起来更省心
    - 底层可能仍是轮询或 WatchService，但 API 更友好
  → 简单需求用 WatchService，复杂/递归需求可考虑 Commons IO

结论：
  WatchService 是 JDK 自带的文件监听（事件驱动、比轮询好）
  但功能基础（不递归、要自己处理坑），
  复杂场景可用封装更好的库

WatchService 的应用：配置文件热加载、日志/数据目录监听、开发工具的文件变化触发。实践建议：监听放单独线程（take 阻塞）、做好去重防抖、处理 OVERFLOW、需要递归就遍历子目录 register。更好用的替代：Apache Commons IO 的 FileAlterationMonitor（封装了递归监听、去重，API 更友好）——简单需求用 WatchService、复杂/递归需求用 Commons IO。理解「应用:配置热加载/日志监听/开发工具;实践:单独线程+去重防抖+处理 OVERFLOW+递归遍历注册;替代:Commons IO FileAlterationMonitor 更友好」，就掌握了 WatchService 的应用和替代。

记忆钩子：「WatchService=NIO.2 文件系统监听服务(监听目录的创建/修改/删除,事件驱动比轮询好);底层用 OS 文件系统事件机制(Linux inotify/Windows ReadDirectoryChangesW/macOS FSEvents),OS 主动通知、平时阻塞不占 CPU;三步:①newWatchService 创建②dir.register(ws,ENTRY_CREATE/MODIFY/DELETE)注册目录(只能注册目录不能注册文件)③循环 take()取 WatchKey 遍历 pollEvents 处理(event.kind 类型/context 文件名)再 key.reset();★坑:必须 reset(忘了后面收不到是最常见 bug)、默认不递归(子目录要各自 register)、一次修改可能多个事件(去重防抖)、OVERFLOW(事件丢了要全量重扫);替代 Commons IO FileAlterationMonitor 更友好」。

七、常见误区与追问

误区：监听文件变化只能用死循环轮询查修改时间。 用 WatchService（NIO.2）更好——它底层用 OS 的文件系统事件机制（inotify 等），事件驱动、OS 主动通知，平时阻塞不占 CPU、有变化立即唤醒；轮询消耗 CPU、有延迟、可能漏。
误区：WatchService 处理完事件不用管，会自动继续监听。 必须调 key.reset()——处理完一批事件后要 reset 让 WatchKey 从 Signalled 变回 Ready 才能接收后续事件；忘了 reset 是最常见的 bug（第一次事件收到了，后面就再也收不到）。
误区：注册一个目录能监听它所有子目录的变化。 默认只监听「直接子项」，不递归——子目录里的变化收不到；要监听整棵目录树得遍历所有子目录各自 register，且新建子目录时还要动态注册那个新目录（递归监听要自己实现）。
误区：保存一个文件只会触发一个事件。 可能触发多个——有的编辑器/系统保存时会多次 ENTRY_MODIFY，或先 ENTRY_DELETE 再 ENTRY_CREATE（原子替换）；处理时要做去重/防抖（收到事件后延迟一点、合并短时间内的多次），避免一次保存触发多次处理。
追问：WatchService 为什么比轮询高效？ 它用操作系统的文件系统事件通知机制（Linux inotify、Windows ReadDirectoryChangesW、macOS FSEvents），是事件驱动的——OS 内核帮你盯着目录，有变化才主动产生事件通知，你的线程平时阻塞在 take() 几乎不消耗 CPU，有变化立即被唤醒几乎无延迟；轮询要不停扫描比较，浪费 CPU 且有 sleep 间隔的延迟。
追问：WatchKey 的 reset() 有什么作用？ 处理完一批事件后调 reset() 把 WatchKey 从 Signalled（已触发）状态变回 Ready（就绪）状态，才能继续接收后续事件；它相当于「我处理完了，可以给我下一批事件」的信号；忘了 reset，key 停在 Signalled、后续变化都收不到；reset() 返回 false 表示 key 已失效（监听的目录被删/移动了）。
追问：什么是 OVERFLOW 事件，怎么处理？ 当短时间内文件变化太多、事件队列溢出时，WatchService 会产生 OVERFLOW 事件，表示「有一些事件丢失了、你收到的不完整」；健壮的代码要处理它——通常是触发一次对监听目录的全量扫描、重新同步文件状态，而不是依赖那些可能已经丢失的增量事件。

八、加强记忆

WatchService 是 Java 7（NIO.2）的「文件系统监听服务」——监听目录里文件的创建（ENTRY_CREATE）、修改（ENTRY_MODIFY）、删除（ENTRY_DELETE），不用自己轮询。底层用 OS 的文件系统事件机制（Linux inotify、Windows ReadDirectoryChangesW、macOS FSEvents），是事件驱动的——OS 主动通知，你的线程平时阻塞在 take() 不占 CPU、有变化立即唤醒，比轮询（消耗 CPU、有延迟、可能漏）高效。用法三步：① 创建（FileSystems.getDefault().newWatchService()）；② 注册目录+事件（dir.register(ws, ENTRY_CREATE, ...)，只能注册目录不能注册文件）；③ 循环取事件（take() 阻塞取 WatchKey、遍历 pollEvents() 处理，event.kind() 类型/event.context() 文件名，处理完必须 key.reset()）。几个坑：① 必须 reset()（WatchKey 从 Signalled 变回 Ready，忘了后面收不到——最常见 bug）；② 默认不递归（只监听直接子项，子目录要各自 register）；③ 一次修改可能触发多个事件（多次 MODIFY 或 DELETE+CREATE，要去重/防抖）；④ OVERFLOW（变化太多事件丢失，要全量重扫）。应用：配置热加载、日志监听、开发工具触发。复杂/递归需求可用 Apache Commons IO 的 FileAlterationMonitor（更友好）。一句话「WatchService=NIO.2 文件系统监听(创建/修改/删除),底层用 OS 事件机制(inotify 等)事件驱动比轮询好、平时阻塞不占 CPU;三步 newWatchService→dir.register(只能目录)→循环 take 取 WatchKey 遍历 pollEvents 再 reset;坑:必须 reset(忘了收不到)、默认不递归、一次修改多个事件要防抖、OVERFLOW 要全量重扫」。

简化版

详细版