File.listFiles() 返回文件顺序不可靠，需手动排序；renameTo() 跨文件系统易失败，应检查返回值并用 Files.move() 替代；中文路径、并发操作等均需额外校验与防护。
用 File.listFiles() 遍历目录时文件顺序不可靠
Java 的 File.listFiles() 返回数组，但 JVM 不保证按名称、时间或任何逻辑排序——不同系统、JDK 版本甚至多次运行结果都可能乱序。如果你依赖“先处理 A 再处理 B”来编号（比如 img_001.jpg → img_002.jpg），实际重命名后很可能错位。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 务必在获取文件列表后手动排序，例如用
Arrays.sort(files, Comparator.comparing(File::getName)) - 若需按修改时间排序，用
Comparator.comparingLong(File::lastModified)，注意 Windows 和 Linux 时间精度差异可能导致并列 - 避免直接对
listFiles()结果 for 循环重命名——中间插入/删除会引发ArrayIndexOutOfBoundsException或漏处理
File.renameTo() 在跨文件系统时大概率失败
这是最常被忽略的坑：renameTo() 本质是 OS 的 rename(2) 系统调用，在 Linux/macOS 下要求源和目标必须在同一挂载点；Windows 虽宽松些，但跨盘符（如 C: → D:）同样返回 false，且不抛异常，只静默失败。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 永远检查返回值：
if (!oldFile.renameTo(newFile)) { /* 失败，走 copy + delete 逻辑 */ } - 跨卷重命名必须拆成两步：先用
Files.copy()复制，再用Files.delete()删除原文件（注意权限和只读属性） - Java 7+ 推荐统一用
Files.move()，它内部自动判断是否可原地重命名，失败时 fallback 到 copy-delete，且支持StandardCopyOption.REPLACE_EXISTING
中文路径或特殊字符导致 renameTo() 返回 false
不是编码问题，而是文件系统层面限制。例如 NTFS 对路径长度上限为 260 字符（除非启用长路径支持），而 macOS HFS+ 对 Unicode 组合字符（如带声调的汉字）处理不稳定。更隐蔽的是：某些杀毒软件会锁定正在扫描的文件，导致重命名拒绝访问。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 用
Paths.get(...).toRealPath()检查路径是否真实可达且无符号链接循环 - 提前验证目标文件名合法性：过滤
/ \ : * ? " |（Windows）或控制字符（\u0000-\u001F） - 重命名前加
newFile.getParentFile().mkdirs()确保父目录存在，否则renameTo()直接失败
批量重命名时并发修改引发冲突
单线程安全，但一旦引入 ExecutorService 多线程处理，两个线程可能同时尝试把 a.jpg 和 b.jpg 改成同一个新名字（比如都算出编号 001），后者必然失败。更糟的是，若没做原子性校验，还可能把文件覆盖掉。
实操建议：
立即学习“Java免费学习笔记（深入）”；
- 禁止多线程直接操作同一目录下的文件重命名——顺序依赖强，收益远低于风险
- 真要提速，可先用单线程生成「旧路径 → 新路径」映射表，再用线程池并发执行
Files.move()（确保每个目标路径唯一） - 每次 move 前加
if (!newFile.exists())双检，防止因网络延迟或 NFS 缓存导致的重复写入
重命名工具真正的复杂点不在遍历或改名，而在路径解析的隐式约束、文件系统行为差异、以及失败后如何回滚到一致状态——这些细节不打日志根本发现不了。
