SimpleFileVisitor 是 Java NIO.2 提供的抽象类，用于精细控制文件树遍历，适用于需跳过目录、捕获异常、统计或提前终止等场景；重写 visitFile 和 preVisitDirectory 方法配合 FileVisitResult 返回值即可满足多数需求。
SimpleFileVisitor 是什么，为什么不用递归调用 Files.walk
SimpleFileVisitor 是 Java NIO.2 提供的一个抽象类，用来定制文件树遍历行为。它不是“必须用”的工具，而是当你需要在遍历中做精细控制（比如跳过某些子目录、捕获异常、提前终止、统计类型）时的合理选择。直接手写递归或用 Files.walk() 更简单，但它们要么难处理异常（Files.walk() 遇到权限错误会直接中断），要么逻辑分散不易维护。
关键判断：如果你只要“列出所有 .java 文件”，用 Files.walk() + filter() 就够了；但凡涉及“遇到 PermissionDeniedException 继续走”“只进 src/main/java 不进 target”“统计每个目录下 class 文件数量”，就得靠 SimpleFileVisitor。
重写 visitFile 和 preVisitDirectory 的典型组合
绝大多数实际需求靠重写这两个方法就能覆盖。注意它们的返回值是 FileVisitResult，不是 void —— 返回值决定遍历是否继续、是否跳过子目录。
-
visitFile()：每碰到一个文件就触发，适合过滤、读取、计数。别在这里做耗时操作（如解析大文件），否则拖慢整个遍历 -
preVisitDirectory()：进入目录前触发，适合检查权限、跳过特定目录（比如返回FileVisitResult.SKIP_SUBTREE）、初始化该目录下的临时状态 - 不要重写
visitFileFailed()就默认忽略所有访问失败（如无权限、路径不存在），但这样你会收不到任何提示 —— 生产环境建议至少 log 一下IOException
示例：只处理 src/main/java 下的 .java 文件，跳过 target 和 build
你接手一个需求时，是不是经常这样："改一个小字段 → 结果把不相关的代码也改了"、"需求说得很模糊 → 做着做着发现跑偏了"、"数据库加个字段 → 上线才发现漏了数据兼容"、"做了个新功能 → 一个月后自己都忘了当时怎么设计的"、"写到一半被中断 → 再回来不知道从哪继续"；这个 Skill 就是专门解决这些问题的。 它会自动探测你的项目环境（JDK、Spring Boot、ORM、数据库、前端框架），记在
立即学习“Java免费学习笔记（深入）”；
Files.walkFileTree(Paths.get("project-root"), new SimpleFileVisitor<Path>() {
@Override
public FileVisitResult preVisitDirectory(Path dir, BasicFileAttributes attrs) {
String name = dir.getFileName().toString();
if ("target".equals(name) || "build".equals(name)) {
return FileVisitResult.SKIP_SUBTREE;
}
return FileVisitResult.CONTINUE;
}
@Override
public FileVisitResult visitFile(Path file, BasicFileAttributes attrs) {
if (file.toString().endsWith(".java")) {
System.out.println(file);
}
return FileVisitResult.CONTINUE;
}
@Override
public FileVisitResult visitFileFailed(Path file, IOException exc) {
System.err.println("skip " + file + ": " + exc.getMessage());
return FileVisitResult.CONTINUE;
}
});
常见坑：异常吞没、符号链接、Windows 路径长度限制
这三个问题在线上环境最容易导致“明明有文件却没扫到”或“程序静默退出”。
- 不重写
visitFileFailed()→ 权限不足或断开的符号链接会让遍历直接停止（JDK 8 默认行为），而不是跳过该节点 - 默认不跟随符号链接 → 如果目标目录里有软链指向其他分区或网络路径，
SimpleFileVisitor不会自动进去。要支持，得传入EnumSet.of(FileVisitOption.FOLLOW_LINKS)给walkFileTree() - Windows 下长路径（>260 字符）触发
InvalidPathException，且不会进visitFileFailed()—— 它在构建Path对象阶段就抛了。解决办法是启用系统级长路径支持，或改用 UNC 路径（\\?\C:\...）
性能和替代方案对比：什么情况下该换掉 SimpleFileVisitor
它本身没有性能问题，但容易被误用出性能陷阱。
- 每次
visitFile()都调用Files.isReadable()或Files.size()→ 多一次系统调用，遍历百万小文件时延迟明显。应复用BasicFileAttributes参数里的信息（比如attrs.size()、attrs.isRegularFile()） - 需要并行遍历？
SimpleFileVisitor是单线程同步模型，别试图在 visitor 里扔线程池 —— 改用Files.walk()+parallelStream()，但要注意它不处理 IO 异常的传播 - 只查一层子目录？别用它。直接
Files.list(dir).filter(Files::isDirectory).forEach(...)更轻量
真正复杂的场景（比如带深度限制、按修改时间分批、跨文件系统挂载点识别），往往需要自己封装一层状态机，SimpleFileVisitor 只是起点，不是终点。
