简介这份压缩包是一套面向Java初学者与中级开发者的目录文件监控示例源码围绕实时掌握指定文件夹内文件数量、大小及变化情况展开可用于项目进度跟踪、日志生成观察也可延伸到游戏存档目录与运行日志监控等场景。程序体现每5秒轮询扫描、java.io.File属性读取、java.nio.file.WatchService事件监听以及借助FileAlterationObserver等工具简化回调的思路同时通过多线程将目录扫描与界面刷新分离兼顾响应性与资源消耗。压缩包约7KB文件总数字段显示为0、主要文件类型明细暂未提供包体轻量适合作为文件I/O与事件驱动编程的参考样例。目前已有156人浏览学习读者可从中梳理监控任务拆分、变化检测和节拍控制等实现要点。1. 从一堆塞进同一个文件夹的录屏说起这个 Java 监控目录程序到底解决什么问题做游戏娱乐类内容的人大概都遇到过这种场面录屏、截图、导出的音频先丢进同一个 inbox 目录一天下来几百个文件混在一起改名的、挪位置的、按日期归档的全靠手点一小时就没了。这份 Java 源码做的事情很朴素——盯住一个目录文件一落进来立刻感知然后按你定的规矩分发处理。它适合两类人一是想把「素材整理」这一步彻底自动化的开发者二是刚学完 Java IO 和 NIO、想找个能跑起来又能改得动的小项目练手的同学。代码量不大但没有写成玩具该有的去重、写完判断、线程池分发、日志都留着。2. 项目定位与技术选型JDK 自带 WatchService 打底轮询兜底2.1 解压之后的目录结构四个包各管一段解开压缩包看到的不是一堆平铺的.java文件而是按职责切成了config、watch、core、handler、util五块。这种分法在小工具里算讲究的好处很直接你想换一套文件处理逻辑只动handler包就行监听层一行都不用碰你想换监控方式只动watch包业务层也不知道。目录骨架大致是这样不同版本的包名可能略有出入但分层是一致的DirectoryMonitor/ ├── pom.xml # Maven 构建编译级别 1.8 ├── monitor.properties # 唯一的外部配置入口 ├── run.bat / run.sh # 免打包快捷启动脚本 ├── logs/ # 运行日志与事件流水 └── src/main/java/com/example/monitor/ ├── MonitorApplication.java # main 方法装配所有组件 ├── config/MonitorConfig.java # 读 properties做参数校验 ├── watch/WatchServiceListener.java # 事件监听主循环 ├── watch/PollingScanner.java # 定时扫描兜底 ├── core/FileEvent.java # 事件数据载体 ├── core/FileSettleChecker.java # 判断文件是否写完 ├── core/Dispatcher.java # 去重 线程池分发 ├── handler/FileHandler.java # 处理接口 ├── handler/ArchiveHandler.java # 默认实现按类型归档 ├── util/PathMatcherUtil.java # 通配符白名单/黑名单 └── util/EventLog.java # 落盘日志目录职责改动频率config解析monitor.properties把字符串转成Path、Duration低watch监听目录变化产生原始事件低core去重、写完判断、线程池调度中handler真正处理文件归档、改名、入库、调接口高util路径匹配、日志输出低看清楚这张表后面读源码就有路线了监听层只负责「告诉我发生了什么」core负责「这次事件靠不靠谱、能不能处理」handler负责「处理成什么样」。三层之间的契约只有一个FileEvent对象这是整份代码里最值得学的一处设计。2.2 技术栈只吃 JDK不引第三方监控库pom.xml里的依赖极少除了 JUnit 做测试运行时不需要任何外部 jar。文件监控这部分直接用java.nio.file.WatchService——JDK 7 之后它已经把 Linux 的 inotify、Windows 的 ReadDirectoryChangesW、macOS 的 FSEvents 统一封装起来了调同一套 API 就能跨平台拿到目录变更通知。常见做法有三种源码选的是第一种方案依赖实时性主要限制WatchServiceJDK 自带毫秒级内核推事件不递归、事件会合并、可能丢定时轮询Files.walkJDK 自带取决于间隔CPU 开销随文件数线性上涨第三方文件监控库需要额外 jar毫秒级版本兼容、打包体积变大选WatchService的理由很实在这是个拿 rar 发出来的小工具用户双击run.bat就得能跑多一个 jar 就多一次「class not found」的翻车机会。但它有个绕不开的短板——只监听注册过的那一层目录子目录得自己递归注册事件还会被内核合并短时间内同一个文件改十次你可能只收到两三条ENTRY_MODIFY。所以源码里留了PollingScanner做兜底监听层报了OVERFLOW或者某些网络盘、虚拟机共享目录压根不产生事件的时候轮询能把它捞回来。2.3 运行环境与依赖清单跑起来之前先确认环境这一步别省# JDK 8 及以上都能编源码编译级别写的是 1.8 java -version # Maven 3.6如果只跑不改编装个 JRE 加现成 jar 也行 mvn -v # 顺手看一眼当前用户对目标目录有没有读写权限 ls -ld /data/inbox几个实际会卡住的点JDK 版本低于 8 会直接编译失败Files.getLastModifiedTime那套 API 是 7 才有的Windows 上路径里带空格比如D:\My Files\inbox时配置文件和启动脚本里的引号要写对否则Path解析出来是断的Linux 上如果目标目录挂载在网络文件系统上WatchService大概率注册得上但收不到事件得把轮询开关打开。这些不是玄学都是踩过一次就记住的事。3. 核心链路拆解一个文件落盘之后走的四步3.1 第一步注册监听目录把 WatchKey 和 Path 对上号WatchService最反直觉的地方是它返回的WatchKey只告诉你「哪个注册句柄有动静」不告诉你「哪个目录」。所以必须自己维护一张MapWatchKey, Path反查表。源码里这段是整个项目的地基值得逐行看public class WatchServiceListener implements Runnable { private final WatchService watchService; // WatchKey 只标识注册句柄真实目录要靠这张表反查 private final MapWatchKey, Path keyToDir new ConcurrentHashMap(); private final MonitorConfig config; private final Dispatcher dispatcher; public WatchServiceListener(MonitorConfig config, Dispatcher dispatcher) throws IOException { this.config config; this.dispatcher dispatcher; this.watchService FileSystems.getDefault().newWatchService(); for (Path root : config.getRoots()) { registerRecursive(root); // 入口目录逐个注册 } } private void registerRecursive(Path dir) throws IOException { WatchKey key dir.register(watchService, StandardWatchEventKinds.ENTRY_CREATE, StandardWatchEventKinds.ENTRY_MODIFY, StandardWatchEventKinds.ENTRY_DELETE); keyToDir.put(key, dir); if (!config.isRecursive()) { return; } try (DirectoryStreamPath children Files.newDirectoryStream(dir)) { for (Path child : children) { // 软链接要跳过否则可能绕成死循环 if (Files.isDirectory(child) !Files.isSymbolicLink(child)) { registerRecursive(child); } } } } Override public void run() { while (!Thread.currentThread().isInterrupted()) { WatchKey key; try { key watchService.take(); // 阻塞等待有事件才返回 } catch (InterruptedException e) { Thread.currentThread().interrupt(); return; } catch (ClosedWatchServiceException e) { return; // 服务被关正常退出 } Path dir keyToDir.get(key); if (dir null) { key.reset(); continue; } for (WatchEvent? event : key.pollEvents()) { if (event.kind() StandardWatchEventKinds.OVERFLOW) { dispatcher.onOverflow(dir); // 内核丢事件了交给轮询补 continue; } // context() 只给文件名不是完整路径必须和目录拼 Path child dir.resolve((Path) event.context()); if (event.kind() StandardWatchEventKinds.ENTRY_CREATE Files.isDirectory(child)) { try { registerRecursive(child); // 新建子目录要补注册否则里面瞎了 } catch (IOException ignored) { } } dispatcher.submit(child, event.kind()); } // reset 必须调不调这个 key 之后再也收不到事件 if (!key.reset()) { keyToDir.remove(key); // 目录被删或权限没了注册失效 } } } }几个关键参数得说清楚。watchService.take()是阻塞版本线程会一直挂在这儿不耗 CPU比poll()加sleep干净key.pollEvents()取完事件后必须调key.reset()这是新手最容易漏的一行漏了的表现是「程序启动了第一个事件收到了之后就没动静了」排查起来特别费时间。event.context()返回的是相对路径其实就是文件名所以必须dir.resolve(...)拼回绝对路径直接在多级目录场景下拿它当路径用会得到一堆找不到的文件。还有一个容易误解的点ENTRY_CREATE在「新建子目录」和「文件被移入目录」两种情况下都会触发。前者需要补注册后者需要走处理流程所以代码里先判断Files.isDirectory(child)再决定往哪条路走。3.2 第二步判断文件是不是真的写完了这是目录监控里最容易被低估的一环。文件刚被创建的时候ENTRY_CREATE就来了可此时复制进程可能才写了 3KB你上去就Files.move轻则拿到半个文件重则抛FileSystemException: 另一个程序正在使用此文件。源码里用了一个独立的FileSettleChecker做二次确认public class FileSettleChecker { private final long settleWaitMs; // 两轮采样间隔默认 800ms private final int maxRound; // 最多采样几轮默认 10 轮 public boolean waitUntilSettled(Path file) throws InterruptedException { long lastSize -1L; long lastModified -1L; for (int i 0; i maxRound; i) { if (!Files.exists(file)) { return false; // 等待期间被删了直接放弃 } long size Files.size(file); long modified Files.getLastModifiedTime(file).toMillis(); // 两轮采样完全一致且非空才认为写完了 if (size lastSize modified lastModified size 0) { return true; } lastSize size; lastModified modified; Thread.sleep(settleWaitMs); } return false; // 超时交给上层记日志跳过 } }参数怎么调settleWaitMs决定灵敏度本地小文件 300500ms 够用几十 MB 的录屏文件建议 800ms 到 1s否则大文件还在写的时候两轮采样恰好一样长会误判maxRound是保险丝十轮还没写完基本说明这个文件被别的进程长期占用了再等下去就是死等。size 0这个判断也别删。很多工具包括一些下载器和剪辑软件会先创建一个 0 字节的占位文件写完再补内容这时候两轮采样都是 0光看「两次一样」会直接把空文件判成写完了。在 Windows 上还可以再加一层保险——尝试独占打开文件private boolean tryLockExclusive(Path file) { try (RandomAccessFile raf new RandomAccessFile(file.toFile(), rw); FileChannel channel raf.getChannel()) { FileLock lock channel.tryLock(); // 拿不到锁说明还有别的进程在写 if (lock null) { return false; } lock.release(); return true; } catch (IOException e) { return false; } }这个技巧在 Linux 上意义不大那边更依赖lsof判断但 Windows 场景下能挡掉一大批「文件正在被使用」的异常。3.3 第三步事件去重与线程池分发同一份文件被写一次ENTRY_MODIFY可能连来三四条不去重的话后面handler会被重复调用归档逻辑里就是「文件不存在」的异常刷屏。Dispatcher用了一个时间窗做去重同时把处理任务丢进线程池public class Dispatcher { private final ThreadPoolExecutor pool; private final MapString, Long lastSeen new ConcurrentHashMap(); private final long dedupWindowMs; // 去重窗口默认 500ms public Dispatcher(MonitorConfig config, FileHandler handler) { // 有界队列 CallerRunsPolicy队列满时让监听线程自己执行 // 相当于天然限流宁可慢一点也不把内存撑爆 BlockingQueueRunnable queue new LinkedBlockingQueue(config.getQueueCapacity()); this.pool new ThreadPoolExecutor( config.getWorkerThreads(), config.getWorkerThreads(), 0L, TimeUnit.MILLISECONDS, queue, new ThreadPoolExecutor.CallerRunsPolicy()); this.dedupWindowMs config.getDedupWindowMs(); } public void submit(Path path, WatchEvent.Kind? kind) { String key path.toAbsolutePath() | kind.name(); long now System.currentTimeMillis(); Long prev lastSeen.put(key, now); if (prev ! null now - prev dedupWindowMs) { return; // 窗口内的重复事件直接丢掉 } pool.execute(() - dispatch(path, kind)); } private void dispatch(Path path, WatchEvent.Kind? kind) { try { FileEvent event new FileEvent(path, kind, System.currentTimeMillis()); if (!PathMatcherUtil.matches(path, config)) { return; // 白名单/黑名单过滤在业务之前 } handler.handle(event); } catch (Exception e) { EventLog.error(处理失败 path, e); } } }线程数worker.threads默认给 4够处理绝大多数场景。别一上手就调到 32处理逻辑要是涉及磁盘 IO线程越多上下文切换越凶吞吐反而不涨。队列容量queue.capacity建议给到 2000 以上——目录监控的峰值往往出现在「用户一次性拖进来 500 个文件」这种时刻队列小了会频繁触发CallerRunsPolicy监听线程被业务卡住事件就开始堆积。lastSeen这张表要记得清源码里有个后台线程每 30 秒清一次过期条目不然跑上一周内存就悄悄涨上去了这种慢性问题最容易被忽略。3.4 第四步交给 Handler落日志与失败记录处理层只认一个接口这是整个项目最值得抄的设计public interface FileHandler { void handle(FileEvent event) throws Exception; }默认实现ArchiveHandler干的事很具体按扩展名分到images/、videos/、audio/三个子目录文件名前面拼时间戳防重名public class ArchiveHandler implements FileHandler { private final Path outputRoot; private final MapString, String typeMapping new HashMap(); Override public void handle(FileEvent event) throws Exception { Path src event.getPath(); String ext getExtension(src); // 小写化的扩展名 String category typeMapping.getOrDefault(ext, others); Path targetDir outputRoot.resolve(category) .resolve(LocalDate.now().toString()); // 再按日期分一层 Files.createDirectories(targetDir); String fileName System.currentTimeMillis() _ src.getFileName(); Path target targetDir.resolve(fileName); Files.move(src, target, StandardCopyOption.REPLACE_EXISTING); EventLog.info(归档 src - target); } private String getExtension(Path path) { String name path.getFileName().toString(); int dot name.lastIndexOf(.); return dot 0 ? : name.substring(dot 1).toLowerCase(); } }换成自己的业务只要实现FileHandler要入库就写DbInsertHandler要调接口就写UploadHandler要按内容哈希去重就写DedupHandler。源码里MonitorApplication是按配置里的handler.class反射加载的改配置就能换实现不用重新打包。日志这块源码走的是「双通道」一条logs/monitor.log记人类看的流水一条logs/events.csv记机器分析的明细时间戳、事件类型、完整路径、文件大小。后者在做统计的时候特别省事直接丢进表格工具就能看出一周里哪个时段文件最多。4. 把程序跑起来配置项、启动命令与验证方法4.1 monitor.properties 每一项该填什么配置文件是唯一的入口改这里比改代码安全得多配置项示例值说明monitor.rootsD:/inbox,/data/drop监控根目录多个用英文逗号分隔monitor.recursivetrue是否递归注册子目录monitor.poll.interval3000轮询兜底间隔单位毫秒0 表示关闭monitor.settle.wait800两次采样间隔大文件往上调monitor.settle.round10最多采样轮数monitor.dedup.window500事件去重窗口单位毫秒monitor.worker.threads4处理线程数monitor.queue.capacity2000任务队列长度monitor.include*.jpg,*.png,*.mp4,*.wav白名单留空表示全收monitor.exclude*.tmp,*.part,*.crdownload黑名单优先级高于白名单monitor.handler.classcom.example.monitor.handler.ArchiveHandler处理实现类全限定名monitor.log.dir./logs日志目录两个细节值得单独提exclude里一定要有临时文件后缀浏览器下载中的.crdownload、剪辑软件导出的.part、迅雷的.td这些中途文件被当成成品处理是最高频的翻车点include和exclude同时命中时以exclude为准这个优先级在PathMatcherUtil里写死了改的时候注意别顺手调反。4.2 打包与启动jar 和脚本两种方式# 方式一打成一个可执行 fat jar拷到别的机器上直接 java -jar 就能跑 mvn clean package -DskipTests java -jar target/directory-monitor-1.0.jar -c monitor.properties # 方式二不打包用 classpath 直接跑改代码调试时更顺手 mvn compile java -cp target/classes:lib/* com.example.monitor.MonitorApplication # Windows 下 classpath 分隔符是分号注意别照抄上面的冒号 java -cp target/classes;lib/* com.example.monitor.MonitorApplication-c参数指定配置文件路径不传就默认读工作目录下的monitor.properties。想让它当后台服务跑Linux 上写个 systemd unit 或者nohup java -jar ... /dev/null 21 都行但要注意工作目录——配置文件里的相对路径./logs是相对启动目录算的用 service 启动时工作目录往往是/日志会落到奇怪的地方去建议全部改成绝对路径。启动成功的标志是控制台打出这几行先打印解析后的配置摘要目录数、线程数、是否递归再打印每个注册成功的目录最后是watching ...。如果配置里写的目录不存在源码的处理是打一条 warn 然后跳过不中断启动——这个行为看个人口味我一般会把它改成直接退出省得半夜发现程序在跑但一个目录都没盯住。4.3 造几个文件验证链路是否通不要拿真实素材目录做第一次测试新建一个空目录专门验证# 造一个临时验证目录 mkdir -p /tmp/monitor-test/inbox /tmp/monitor-test/out # 逐个造文件观察日志的变化每个之间隔一两秒模拟真实落盘节奏 echo hello /tmp/monitor-test/inbox/sample-1.txt sleep 2 cp /some/large-video.mp4 /tmp/monitor-test/inbox/ # 大文件看写完判断是否生效 sleep 2 mkdir /tmp/monitor-test/inbox/sub echo hi /tmp/monitor-test/inbox/sub/nested.txt # 实时跟日志重点看三件事事件有没有丢、归档路径对不对、有没有重复处理 tail -f logs/monitor.log预期看到的行为是小文件大约 1 秒内被归档大文件要等复制结束才动sub/nested.txt这种二级目录里的文件也能被抓到验证递归注册补注册那段逻辑。如果大文件在复制到一半就被Files.move走了八成是settle.wait设太小或者FileSettleChecker那段被改坏了。想验证去重是否生效用一个循环在 1 秒内连续echo十次同一个文件日志里对应的归档记录应该只有一两条。4.4 轮询兜底什么时候必须打开public class PollingScanner implements Runnable { private final MapPath, Long snapshot new ConcurrentHashMap(); // 路径 - 修改时间 private final long intervalMs; Override public void run() { while (!Thread.currentThread().isInterrupted()) { try (StreamPath walk Files.walk(config.getRoot(), config.isRecursive() ? Integer.MAX_VALUE : 1)) { walk.filter(Files::isRegularFile).forEach(p - { long mtime Files.getLastModifiedTime(p).toMillis(); Long old snapshot.put(p, mtime); if (old null) { dispatcher.submit(p, StandardWatchEventKinds.ENTRY_CREATE); } else if (old ! mtime) { dispatcher.submit(p, StandardWatchEventKinds.ENTRY_MODIFY); } }); Thread.sleep(intervalMs); } catch (Exception e) { EventLog.error(轮询异常, e); } } } }这段代码的价值不在功能在于「监听层失聪时的后悔药」。三种情况必须打开目录挂在网络共享盘或虚拟机的共享目录上内核事件经常传不过来、Linux 上 inotify 的 watch 数量被打满表现为注册时抛IOException: Too many open files、目录会被整个删除重建原来的WatchKey已经失效。代价是文件多的时候 CPU 会涨所以poll.interval别设成 200ms3000ms 起步比较合适。5. 避坑与常见问题排查五个真实翻车点5.1 事件相关的三个坑现象一程序启动了日志里一条事件都没有。原因WatchKey用完没调reset()第一次pollEvents()之后这个 key 就进入失效状态后续事件全被丢弃。 解决检查run()循环末尾有没有if (!key.reset()) { keyToDir.remove(key); }这行漏了是新手翻车率最高的地方。顺手也检查一下take()是不是被换成了poll()且没加等待那样会变成一个空转的死循环。现象二目录多的时候只有第一层有反应子目录里的文件完全没动静。原因WatchService天生不递归源码里的registerRecursive只会在启动时和「新建子目录」时被调用如果你在注册完之后才往监控目录里复制一整棵树中间那些层级可能没被注册到。 解决确认monitor.recursivetrue如果目录树是外部一次性同步进来的把轮询兜底开上别指望事件层能补全。现象三日志里偶尔出现一条OVERFLOW之后一段时间的事件都对不上。原因内核的事件队列满了短时间内文件变更太密集JDK 只能给你一个OVERFLOW告诉你「丢了一些具体丢了什么不知道」。 解决源码收到OVERFLOW会调dispatcher.onOverflow(dir)实现就是触发一次全量轮询扫描对齐差异。如果你的版本里这段被注释掉了务必自己补上不然丢事件是无声的用户只会说「昨天有几个文件没归档」。5.2 文件处理相关的坑现象四归档出来的图片打不开大小只有原文件的一半。原因写完判断形同虚设——settle.wait设成了 100mssettle.round只有 2大文件在两轮采样之间大小恰好没变缓冲区刷盘节奏导致的被误判成已完成。 解决把采样间隔调到 800ms 以上、轮数调到 10并且确保size lastSize modified lastModified是「连续两轮」都成立而不是只比一次Windows 上再叠一层独占打开判断。现象五处理中文文件名时日志里出现乱码归档后的路径也找不到文件。原因文件名编码和 JVM 默认字符集不一致常见于在 Windows 上打 jar 然后丢到 Linux 上跑file.encoding和sun.jnu.encoding没对齐。 解决启动参数里显式指定-Dfile.encodingUTF-8 -Dsun.jnu.encodingUTF-8配置文件也统一存成 UTF-8 无 BOM别用new String(bytes)这种依赖平台默认编码的写法读配置一律显式传StandardCharsets.UTF_8。5.3 运行环境相关的坑Linux 上如果监控目录特别多几千个子目录注册阶段会抛Too many open files那是 inotify 的 watch 数量上限到了cat /proc/sys/fs/inotify/max_user_watches看一眼当前值按需调大或者改成分层监控Windows 上如果配置里写的是相对路径、启动脚本又不小心在别的盘符下执行Path会解析到意想不到的地方日志里看到路径不对先怀疑这个还有个小坑是监控目录本身被删掉重建后旧WatchKey已经失效reset()返回 false 之后程序不会自动重新注册得靠轮询或者重启才恢复。6. 二次开发把监控器改成你自己的业务管道这份源码最容易上手的地方就是它把「监听」和「处理」切开得足够干净改造几乎只发生在handler包。我按从轻到重的顺序给三条路子。第一条只换处理逻辑。写一个类实现FileHandler把handler.class配置指向它就行不动其他任何代码。public class UploadHandler implements FileHandler { private final HttpClient client HttpClient.newHttpClient(); Override public void handle(FileEvent event) throws Exception { // 只有白名单命中的文件才会走到这里不用重复判断后缀 HttpRequest req HttpRequest.newBuilder() .uri(URI.create(config.getUploadUrl())) .header(Content-Type, application/octet-stream) .POST(HttpRequest.BodyPublishers.ofFile(event.getPath())) .build(); HttpResponseString resp client.send(req, HttpResponse.BodyHandlers.ofString()); if (resp.statusCode() ! 200) { throw new IOException(上传失败: resp.statusCode()); // 抛出后由 Dispatcher 记日志 } } }第二条加一条处理链。FileHandler是接口天然可以组合写一个CompositeHandler持有一个ListFileHandler按顺序执行前一个成功才走下一个。想加个「先算哈希查重、再上传、最后删源文件」的流程就是把三个实现串起来业务代码不用改一行。第三条改事件来源。如果监控的目录规模大到WatchService扛不住比如几十万个文件把watch包换成一个基于Files.walkFileTree的增量扫描器只要它最终调用的还是dispatcher.submit(path, kind)core和handler完全无感。改造完怎么验证我的做法是准备三组固定样本一个正常小文件、一个 500MB 以上的大文件、一个带中文和空格的路径跑一遍看日志里三条是否都归档成功且路径正确然后开两个线程同时往目录里灌 200 个文件看队列有没有被CallerRunsPolicy卡住、lastSeen那张表有没有无限增长。需要的提醒是Dispatcher里的异常是被吞掉记日志的处理失败不会自动重试。真要做可靠管道得在handler里自己加失败落盘 补偿队列别指望框架帮你兜。这个坑我踩过——上线第一周有 30 多个文件因为目标接口限流静默失败日志里躺着几百行处理失败没人看。从那以后我每次接目录监控的活都强制给自己加一条「失败事件单独落一个文件第二天早上扫一眼」的习惯再小的工具也加。希望帮到你。本文还有配套的精品资源点击获取
