简介：一个基于 Java 的文件系统监控工具资源包，适合想掌握目录监听、文件变更检测与事件驱动编程的开发者学习参考。程序采用 java.io.File 获取文件属性，并结合 java.nio.file.WatchService 或 commons-io 的 FileAlterationObserver 实现目录监听；默认每 5 秒自动扫描一次，实时更新目录内文件大小与数量变化，多线程设计使扫描任务与界面刷新分离，避免阻塞并提升响应性。rar 压缩包体积仅 7KB，资源页未列出具体文件清单，实际应以核心 Java 源码或轻量工程为主，便于直接导入 IDE 阅读与改造成自定义监控脚本，适合快速通读核心监听逻辑，并在此基础上扩展符合自身需求的功能。该工具还可延伸用于项目构建进度跟踪、游戏存档目录监测、日志增量预警等场景。已有 154 人学习，对理解 WatchEvent、WatchKey、文件监听回调等概念尤其有参考价值。
1. 项目概述与方案选型
1.1 这个项目解决什么问题
做后端开发的同学应该都遇到过这类场景：Linux服务器上某个共享目录突然多了一批不明文件，配置文件在无人操作的情况下被改动，上传目录被塞满之后接口直接报错。每次都是出了问题再翻日志排查，时间成本高不说，很多文件操作的现场早就没了。
我做的这个Java监控目录文件夹程序，本质上就是一个跑在JVM上的文件系统监听器。它盯住你指定的目录，一旦目录里发生文件新建、修改、删除、重命名这些动作，程序能第一时间捕获事件并按你的规则去处理，比如记录日志、调用某个业务方法、把变更信息推送出去。这个项目适合刚学完Java基础想找点实战练习的初学者，也适合在正式项目里需要做文件自动同步、配置热加载、上传目录巡检的开发者参考。
1.2 为什么选择WatchService而不是传统轮询
在Java里做目录监控，最原始的方案是写一个定时任务，每隔几秒扫描一次目录，把当前文件列表和上一次的列表做对比，通过差异推断发生了什么变化。这个方案思路简单，但问题很明显：扫描间隔太小浪费CPU和IO，间隔太大又错过实时性；目录里文件数量一多，每次全量比对的开销直线上升，而且“先创建后写入”这种半成品文件很容易被误判成一次完整的新增事件。
JDK 7开始提供的java.nio.file.WatchService才是正路。它底层依赖操作系统的文件事件通知机制（Linux下的inotify、Windows下的ReadDirectoryChangesW），事件由内核直接推送，不需要业务代码反复去拉取目录快照。我选择它作为核心实现，就是看中了它够轻、够快、够实时，而且不需要引入任何第三方依赖，一个java.nio包全部搞定，打出来的程序包只有几十KB，部署到哪都不费劲。
2. WatchService的核心机制解读
2.1 四个关键角色
理解WatchService，先记住四个类：WatchService负责注册监听并接收事件，你可以把它理解成一个收发室；WatchKey是每个被监听目录和收发室之间的凭证，它代表一个已注册的监听关系；WatchEvent是具体的事件对象，描述发生了什么、发生在哪个文件上；StandardWatchEventKinds则是事件类型的定义清单。它们之间的关系很简单：你拿着目录去收发室注册，拿到一个WatchKey作为回执，收发室收到文件变化后，会把WatchEvent塞进对应的WatchKey里，业务代码再从key里把事件取出来逐个处理。
这个设计的好处是解耦得很彻底。业务代码不关心操作系统底层的差异，不管是Linux还是Windows，面对的都是同一套接口。我最初是在本地Windows上写完的，后来放到Linux服务器上跑，代码一行没改，直接就能用。
2.2 四类标准事件的取舍
WatchService的事件类型一共有四种，我在程序里用到了其中三种，剩下一种属于不得不处理的异常事件：
| 事件类型 | 含义 | 实际处理建议 |
|---|---|---|
ENTRY_CREATE | 文件或目录被创建 | 核心事件，必须处理 |
ENTRY_MODIFY | 文件内容被修改 | 核心事件，必须处理，但要注意触发次数 |
ENTRY_DELETE | 文件或目录被删除 | 核心事件，必须处理 |
OVERFLOW | 事件被丢弃或丢失 | 不能忽略，至少要做个计数和告警 |
有一个细节很容易踩坑：ENTRY_MODIFY不等于“文件改完了”。大部分编辑器保存文件时，会触发多次修改事件，比如清空文件再写入新内容，这个过程中你会收到至少两次MODIFY。如果业务逻辑是“收到一次修改就立刻处理文件”，大概率会读到半个文件或者空文件。这个问题我在下文实操部分给出了一个可靠的规避方案。
2.3 为什么事件还要手动reset
初学WatchService的人常犯一个错：从take()方法拿到key之后，处理完事件不调用reset()方法，结果发现这个目录之后再也不触发监听了，还以为是系统bug。实际上WatchKey是一次性消耗品，它内部维护了一个signaled状态，事件到达后它从ready变成signaled，等待业务代码消费；不调reset()，它就永远停在signaled状态，新的文件变化不会再被收集。
另一种极端是频繁调用reset()但处理太慢，导致事件在key内部不断累积。WatchService内部的事件队列是有容量上限的，超出上限就会抛出OVERFLOW，告诉你有些事件丢了。所以严谨的做法是take()拿到key之后，在reset()之前先把pollEvents()的结果处理完，再立刻reset()回去继续维护监听，整个循环必须保持简洁高效。我在初版代码里就是因为在事件处理里做了文件复制这种耗时操作，导致大文件批量进来时频繁出现OVERFLOW，后来把耗时操作全部扔到线程池里，主循环才稳定下来。
3. 核心代码实现与部署要点
3.1 基础版：单目录监听
先给一个最小可用版本，监听单个目录的创建、删除、修改事件，直接把事件信息打印出来，方便验证机制。
import java.io.IOException; import java.nio.file.*; import java.nio.file.attribute.BasicFileAttributes; public class SimpleDirWatcher { public static void main(String[] args) throws IOException, InterruptedException { Path dir = Paths.get(args.length > 0 ? args[0] : "."); WatchService watchService = FileSystems.getDefault().newWatchService(); dir.register(watchService, StandardWatchEventKinds.ENTRY_CREATE, StandardWatchEventKinds.ENTRY_DELETE, StandardWatchEventKinds.ENTRY_MODIFY); System.out.println("监控目录：" + dir.toAbsolutePath()); while (true) { WatchKey key = watchService.take(); for (WatchEvent<?> event : key.pollEvents()) { WatchEvent.Kind<?> kind = event.kind(); Path fileName = (Path) event.context(); System.out.println(kind.name() + " -> " + fileName); } boolean valid = key.reset(); if (!valid) { System.out.println("监控失效，目录可能已被删除"); break; } } } }这段代码的核心是register方法和while (true)主循环。register指定监听的目录和事件类型；主循环里take()会阻塞等待事件，拿到key之后遍历事件、处理完调用reset()，这套流程是WatchService的标准套路，务必背下来。运行前需要先确认本机已正确安装JDK，命令行执行java -version能看到版本号即可；如果提示找不到java命令，通常需要配置环境变量，Windows下设置JAVA_HOME指向JDK安装目录，并把%JAVA_HOME%\bin加到Path变量里，Linux下则写进/etc/profile或~/.bashrc再用source生效。
3.2 升级版：支持递归监控子目录
基础版只监听顶层目录，子目录里的变化它一概不知。实际业务里监控的目录往往是一个多级结构的文件仓库，子目录随时可能被创建，里面又会有新的文件。要覆盖整个目录树，需要手动做递归注册：启动时遍历所有现有子目录并逐个注册，后续如果监听到创建的是一个目录，立刻把新目录也注册进去。
private static void registerAll(Path start, WatchService watchService) throws IOException { Files.walkFileTree(start, new SimpleFileVisitor<Path>() { @Override public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) throws IOException { dir.register(watchService, StandardWatchEventKinds.ENTRY_CREATE, StandardWatchEventKinds.ENTRY_DELETE, StandardWatchEventKinds.ENTRY_MODIFY); return FileVisitResult.CONTINUE; } }); } // 主循环中处理创建事件时，若新对象是目录，则补充注册 Path created = (Path) event.context(); Path fullPath = watchedDir.resolve(created); if (Files.isDirectory(fullPath, LinkOption.NOFOLLOW_LINKS)) { registerAll(fullPath, watchService); }注意Files.walkFileTree遍历时如果目录权限不够，preVisitDirectory里直接注册会抛出AccessDeniedException，所以启动时可以加一个try-catch，把无权限的目录跳过并记一条警告日志，不要因为个别目录权限问题把整个监控进程搞崩。注册子目录的时机也有讲究，必须在创建事件发生的当下立刻注册，否则这个子目录内部后续的事件全部收不到。
3.3 文件写入完成判断：一个必须解决的坑
前面提到，MODIFY事件可能是多次触发。假如业务场景是“收到Excel文件创建后自动解析入库”，你直接解析大概率读到不完整文件。我的方案是延迟+稳定检测：每次收到ENTRY_CREATE或ENTRY_MODIFY时，不立刻处理，而是丢进一个延时任务里，比如延迟5秒再执行；执行前检查文件是否存在、文件大小是否在最近2秒内保持不变、以及文件是否能以独占方式打开。
private static boolean isFileReady(Path file) { try { if (!Files.exists(file)) { return false; } long lastSize = -1; long checkStart = System.currentTimeMillis(); // 连续两次检查文件大小一致，视为写入完成 while (System.currentTimeMillis() - checkStart < 3000) { long size = Files.size(file); if (size == lastSize) { return true; } lastSize = size; Thread.sleep(1000); } return false; } catch (IOException | InterruptedException e) { return false; } }这种“延迟确认+大小稳定”的组合很实用。它能覆盖大多数通过复制、编辑器保存、程序写文件产生的半成品状态，虽然会增加几秒的处理延迟，但换来的数据完整性值得。真正有强一致要求的场景，还是建议用户先把文件上传到临时目录，完成后用Files.move原子移动到正式目录，这种业务设计能从源头避免半成品文件的出现。
3.4 事件日志与按扩展名过滤
监听只是手段，记录和处理才是目的。我的程序里事件处理部分做了三个功能：把事件写日志、按扩展名过滤、调用外部回调接口。日志格式采用时间 | 事件类型 | 文件路径，直接写到监控目录下的watch.log里，方便事后审计；按扩展名过滤，比如只关心.xml和.json文件，可以用一个Set<String>保存白名单，非白名单文件直接跳过，这样能避开很多临时文件（如Excel的~$xxx.xlsx、文本编辑器的.swp）。最后是回调接口，定义一个简单的函数式接口，业务方自行决定事件来了之后干什么。
@FunctionalInterface public interface FileEventListener { void onEvent(WatchEvent.Kind<?> kind, Path file); }用Lambda回调的方式接入业务逻辑，是我在热词里看到不少人关注Lambda函数式编程之后特意调整的设计。这样主程序和业务完全解耦，比如我做了一个演示Demo，直接传Lambda进去输出一行日志；真实项目里传另一个Lambda去刷新Redis缓存或发消息通知，程序本体完全不用改。
4. 常见问题与排查技巧实录
4.1 事件丢失和OVERFLOW
现象描述：目录同时复制大量文件时，部分文件的创建事件没有触发，或界面上出现OVERFLOW事件。
原因拆解：WatchService底层事件队列是有限长度的。批量操作时事件产生速度远高于业务代码消费速度，超出队列容量就会溢出，溢出的部分以OVERFLOW事件代替，而OVERFLOW本身不带具体的文件名，等于那一段事件全丢了。
解决方案分三层：一是调小单次事件处理的耗时，把耗时的IO操作丢给线程池异步执行，确保主循环快速消费；二是如果丢事件不可容忍，需要考虑用程序在收到OVERFLOW后主动做一次全目录扫描，与现有文件清单比对来补录差异；三是把监控粒度缩小，比如只监控一个“临时落地目录”，而不是直接监控整个超大共享盘，从源头降低事件流量。我实际项目中试下来，第三招见效最快。
4.2 java.lang.NoClassDefFoundError: java/applet/applet 这类启动报错
现象描述：项目能编译通过，但运行时抛NoClassDefFoundError，提示找不到java.applet.Applet，或者类似的javax.*类不存在。
原因拆解：JDK 9开始模块化之后，java.applet、java.xml.bind这些模块默认不在Java SE标准模块里。老代码如果依赖了这些类，编译时会借着你安装的完整JDK糊弄过去，但运行时如果跑在精简过的JRE或部分模块未启用的环境里，就会直接找不到类。
解决办法：先检查运行时用的哪个JDK，执行java -version看版本；如果代码确实用到了模块化剔除的包，要么改用替代API，要么在启动脚本里加--add-modules java.se.ee（注意JDK 11以后这个模块也移除了，这种办法只能解决部分版本）。更推荐的做法是换用Maven或Gradle管理依赖，通过依赖坐标引入所需内容的实现包，避免依赖JDK自带的模块。
4.3 注册失败：UnsupportedOperationException或AccessDeniedException
现象描述：register方法抛异常，或程序启动后目录发生变更但毫无反应。
原因拆解：WatchService依赖文件系统的底层事件机制，某些网络文件系统（如部分旧版NFS挂载）根本不支持文件事件通知，就会抛UnsupportedOperationException。另外，没有权限读取的目录也无法注册成功。
排查流程：第一步，确认目录类型，执行mount或df -h查看是否为本地磁盘；第二步，确认运行程序的系统用户对目录有读写权限，ls -ld /your/path看看权限位；第三步，写一个最小示例只注册一个目录跑一下，快速验证当前环境是否支持WatchService。如果是网络文件系统且无法更换协议，那就老老实实退回轮询方案，这个我强烈建议不要硬刚。
4.4 中文文件名乱码与TrueType字体无关的中文路径问题
现象描述：监听包含中文名或中文字符串的路径时，日志打印出来是乱码，部分情况下Path对象为null。
原因拆解：这个往往不是WatchService的问题，而是控制台输出编码和操作系统默认编码不一致导致的表面现象。Windows控制台默认GBK，Java读取到的是UTF-8路径，直接System.out.println就乱码了。
解决办法：在代码开头显式指定文件编码，System.setProperty("file.encoding", "UTF-8")，并且IDE或启动参数里加-Dfile.encoding=UTF-8；控制台用支持UTF-8的终端，比如Windows Terminal或IDE自带控制台。还有一个小技巧，日志里不要输出Path的toString()，改用path.toAbsolutePath().normalize().toString()，先规范化再输出，能规避很多奇怪的路径问题。
4.5 编译环境里常见的几个“小毛病”
有段时间我频繁收到Lombok的警告，类似“you aren't using a compiler supported by lombok, so lombok will not work”。这个主要原因是项目中Lombok版本和当前JDK版本不匹配，新的JDK编译器的内部API变了，旧版Lombok不认。处理方式很直接：升级Lombok到最新版本，或者明确在maven-compiler-plugin里指定和Lombok兼容的JDK版本。另外新手常遇到的数组越界异常ArrayIndexOutOfBoundsException，我这边就出现在解析文件名后缀时只写了一个分割逻辑没判长度：
// 错误示范：file.txt.txt会越界吗？不一定，但file这种无后缀名文件会越界 String[] arr = fileName.split("\\."); String ext = arr[arr.length - 1]; // 正确姿势：先判断长度再做访问 String ext = ""; if (fileName.contains(".")) { ext = fileName.substring(fileName.lastIndexOf(".") + 1); }这类细节看着简单，但在目录监控这种泛化场景里很容易触发，因为程序不挑文件，什么奇怪的文件名都会遇到。
5. 性能优化与生产环境部署建议
5.1 事件处理线程池化
上面提到主循环不能做耗时操作，那耗时操作放哪？我单独维护了一个ExecutorService，固定核心线程数和队列长度，事件进来之后封装成任务提交给线程池。这样就算某个文件的处理逻辑卡住了，也不会影响主循环继续接收后续事件。线程池参数需要结合机器CPU核数调整，一般核心线程数设为2到4就够，队列别设太长，因为队列积压太多反而说明消费能力跟不上，这时候宁可丢事件记录日志，也不要让内存无限制增长下去。
ExecutorService executor = Executors.newFixedThreadPool( Runtime.getRuntime().availableProcessors(), r -> { Thread t = new Thread(r, "dir-watcher-worker"); t.setDaemon(true); return t; });这里我把线程设成守护线程，进程退出时不会因为工作线程卡住而无法结束，对长期运行在服务器上的程序来说，优雅停机很重要。
5.2 与Redis等外部组件的集成
我在热词里看到不少人在问“RedisTemplate的increment()报错不是integer or out of range”，这类问题和目录监控本身关系不大，但如果在我的监控程序里想把文件变化次数直接存入Redis，很容易踩到同一个类型坑。increment()方法要求key对应的value是整数字符串，如果之前往里存过其他类型，Redis返回的数据类型不匹配，Jedis客户端就会报类型错误。
做法是在第一次写入时明确用set("counter", "0")初始化，后续只通过increment()操作；或者给key加统一前缀，避免和其他业务数据混在一起。这算是一个小提醒：目录监控程序一旦接入了外部存储，那些看似不相关的类型异常很容易在你意想不到的地方冒出来，排查时先怀疑数据类型，再怀疑代码逻辑。
5.3 长期运行的守护化
开发完成后，把它作为后台服务跑起来，有几个注意点。一是必须在代码里捕获InterruptedException和IOException，take()被中断时要有退出逻辑，不要直接吞掉异常导致线程假死；二是建议把程序打成可执行jar，配合Systemd或Windows服务工具做成开机自启，而不是用nohup java -jar挂前台跑，后者一旦进程挂了没人知道；三是日志输出一定用成熟的日志框架，不要只靠System.out，否则排查问题的时候翻不到历史记录。我自己用的方式是打jar之后配一个脚本，启动时把PID写入文件，停止时用PID精确杀进程，方便运维。
6. 后续可以怎么扩展
跑通基础版之后，这个程序可以往几个方向快速扩展：把监控的配置外置，比如改成读一个properties或yml文件，指定目录、事件类型、文件后缀白名单都不用改代码；增加Webhook通知，事件发生时调用一个HTTP接口，把变更信息POST出去，配合企业微信或钉钉群机器人就能实现文件变动的实时告警；接入文件同步逻辑，监控到新文件后自动做校验、压缩、转移到另一个目录，这就是一个简化版的数据同步工具了。核心机制都是这套WatchService，剩下的是业务逻辑的堆叠。
最后说点实际体会。目录监控程序的难点不在于API调用，而在于对文件系统行为的不确定性要有足够心里准备。文件产生的方式千奇百怪，用户可能用Word编辑、可能用WinSCP直接拖拽、可能用脚本并发写入，每一个行为在操作系统层面产生的Watch事件都不一样。所以写完之后一定要做一轮“破坏性测试”——同时复制几百个文件、持续写入一个大文件、创建几十层嵌套目录、删掉正在写入的文件，这些极端操作跑不崩，程序才算合格。我自己在初版上线时就是因为没做这种测试，结果被别人用脚本批量导入文件打了一次OVERFLOW，教训深刻。
本文还有配套的精品资源，点击获取
