Java批量重命名命令行工具：正则匹配与安全校验实战

简介针对Java文件批量重命名的源码包面向日常开发中需要整理大量文件的Java程序员提供一套简单直接的解决方案整个资源为一个压缩包体积仅1KB内含1个Java源文件代码结构紧凑适合快速查看和复用。源码围绕IO和NIO两个核心文件操作包展开实例演示了如何使用File类的listFiles()遍历目标目录及子目录借助Files.move()与StandardCopyOption安全地重命名文件同时加入异常处理机制以应对权限不足、目标已存在等常见失败场景命名规则部分留有清晰注释可根据实际需求方便地改造为添加序号、替换字符串或调整扩展名等批量策略。该源码尤其适合整理下载文件夹、日志文件或批量转换扩展名的场景稍作改动即可嵌入日常工具已有574人学习下载无论是刚接触文件操作的初学者还是想寻找现成工具快速完成任务的老手都能从中获得有效参考。1. 文件批量重命名一个Java命令行工具让整理文件不再重复劳动给一批图片素材统一命名规范、给日志文件按日期补序号、把PascalCase文件名批量转成下划线风格——这些看似只需要“改个名字”的小事一旦文件数量上了三位数手工操作就很容易翻车。这个Java项目就是专门解决这个问题的一个基于命令行和配置文件的批量重命名工具支持正则匹配、占位符序号填充、扩展名过滤、干运行预览与冲突检测用最小的代码量把“批量重命名”这个场景做完整了。项目本身不依赖任何重量级框架纯JDK实现JDK 8以上直接编译运行。既适合需要用Java做文件处理工具箱的后端开发同学也适合需要批量整理测试资源、日志样本的自动化测试同学。源码结构清晰规则引擎与文件IO分离拿来即用也方便按自己的需求改造成独立服务或GUI工具。2. 设计思路与技术选型如何用纯JDK把规则引擎做薄做批量重命名工具第一个问题往往不是“怎么写”而是“做成什么样”。是带界面的桌面程序还是控制台命令是用Spring Boot起一个常驻服务还是main方法跑完就退出这个项目给出的答案是纯JDK、零第三方依赖、命令行入口、配置文件驱动。批量重命名本质上是批处理任务不需要常驻进程不需要Web容器一次运行把活干完、干净退出这才是这类工具该有的样子。2.1 需求边界与功能清单先梳理清楚工具处理的核心对象。输入是一个目标目录、一组文件匹配条件和一条重命名规则输出是改名后的文件以及一份可回溯的操作日志。围绕这个边界功能清单落在五个方面。规则匹配支持四种模式前缀匹配、后缀匹配、包含匹配、正则匹配。前缀后缀适合处理固定格式的文件比如所有IMG_开头的照片正则匹配适合处理无规律但可按模式归类的文件比如把20230601_001.jpg这类时间戳命名的汇总文件按新规则统一改名。命中的文件进入重命名队列未命中的保持原样。重命名规则支持四类占位符原文件名占位符${name}、序号占位符${seq:3}、正则捕获组占位符${group:1}、以及固定字符串直接拼接。比如把test_1.jpg改成photo_test_001.jpg规则模板就是photo_${name}_${seq:3}.jpg。${name}引用的是去除扩展名之后的文件名主干扩展名由工具自动保留。安全校验分三层。第一层是目标文件名合法性校验剔除 Windows 下的非法字符\ / : * ? |换成下划线。第二层是冲突检测防止两个源文件重命名之后指向同一个目标名。第三层是只读检查源文件不满足Files.isWritable时跳过并记录日志避免执行到一半才发现没权限。预览与执行分离是这个工具最重要的交互设计。--dry-run参数下引擎完整跑一遍匹配、解析、冲突检测流程但最后一步Files.move不执行只把所有即将发生的改动打印出来。这样先看清楚规则是否生效再实跑避免改了一批文件之后才发现规则写错连个后悔药都没有。最后是操作日志。每次执行生成一个带时间戳的.log文件逐行记录旧名、新名、执行状态。工具提供了一个--reverse参数读取上一次的操作日志执行反向重命名把文件批量恢复原名。这个功能平时用不上一旦规则写错就非常救命。2.2 技术选型和零依赖策略选型权衡集中在两个问题要不要引正则库、要不要用 JSON 或 YAML 做配置。正则表达式JDK 自带的java.util.regex已经完全够用。Pattern的捕获组可以直接实现“从旧文件名提取一段拼到新文件名里”的典型需求。第三方正则库在这个场景下没有额外收益反而增加依赖传播的风险。工具类项目最怕的就是依赖出问题编译环境一换就构建失败。配置文件选择了.properties而非 JSON 或 YAML原因很直白Properties是 JDK 原生支持加载一行代码属性文件的键值结构天然对应“匹配条件重命名规则”这种清单。如果未来要改成 Web 服务把规则源从 properties 换成 request body 即可核心逻辑完全不受影响。文件操作也坚定使用java.nio.file而不是老的java.io.File。Files.move、Path.resolveSibling、Files.walk这几个 API 组合起来比File.renameTo的返回布尔值可靠得多。File.renameTo在跨目录移动时经常静默返回 false没有任何异常信息出了问题只能干瞪眼Files.move则会在失败时抛出明确异常便于引擎统一记录失败原因。第三方依赖是零这一点值得多说一句。pom.xml里只有编译器和打包配置没有spring-boot-starter、没有commons-io、没有 lombok。带来的直接好处是任何装有 JDK 8 以上的机器把源码拷过去mvn package即可构建没有版本冲突、没有传递依赖的坑。代价是文件遍历、日志写入这些公共操作要手写但这种重复是有价值的它让核心逻辑完全透明也让阅读源码的人更快理解文件 IO 的本质。2.3 项目核心目录结构与类职责源码是标准 Maven 结构。核心目录如下file-renamer/ ├── pom.xml ├── src/main/java/com/filetool/renamer/ │ ├── App.java # 入口解析命令行参数 │ ├── config/ │ │ ├── RenameConfig.java # 配置模型 │ │ └── ConfigLoader.java # 配置加载与校验 │ ├── core/ │ │ ├── FileMatcher.java # 四种匹配模式实现 │ │ ├── RenameEngine.java # 引擎调度 │ │ ├── RuleParser.java # 规则模板解析 │ │ └── SequenceGenerator.java # 序号生成 │ ├── validate/ │ │ ├── NameValidator.java # 非法字符校验 │ │ └── ConflictDetector.java # 冲突检测 │ └── util/ │ ├── FileWalker.java # 递归遍历 │ └── LogWriter.java # 执行日志 ├── src/main/resources/ │ └── rename.properties # 默认规则配置 └── src/test/java/ └── RenameEngineTest.java # 核心引擎测试类之间的依赖方向是单向的App 解析参数 → ConfigLoader 加载配置 → RenameEngine 接收配置并调度 → FileMatcher 选出目标文件 → RuleParser 解析命名规则 → NameValidator 和 ConflictDetector 校验 → 最后 Files.move 执行。每个类职责很窄engine 里看不到文件遍历代码matcher 里看不到命名规则代码后续改规则解析不会波及到遍历逻辑。这种模块划分是这个项目里最值得借鉴的一点刚接触 Java 文件处理的人照着这个结构写自己的工具能少走很多弯路。3. 核心代码拆解一条重命名从进入到落盘的完整链路这一章分三段看核心实现规则模板如何被解析成可执行的 Token 链、引擎如何调度匹配与重命名、冲突检测如何夹在中间防止覆盖。3.1 规则解析把${seq:3}变成可执行的 Token 链重命名规则的核心不是字符串拼接而是模板解析。RuleParser的职责是把photo_${name}_${seq:3}.jpg这种模板解析成一组有序的 Token每个 Token 知道自己输出什么。public class RuleParser { private static final Pattern TOKEN_PATTERN Pattern.compile( \\$\\{(\\w)(?::(\\d))?\\} ); public ListRuleToken parse(String template) { ListRuleToken tokens new ArrayList(); Matcher m TOKEN_PATTERN.matcher(template); int last 0; while (m.find()) { if (m.start() last) { tokens.add(new LiteralToken(template.substring(last, m.start()))); } String name m.group(1); String arg m.group(2); if (name.equals(name)) { tokens.add(new NameToken()); } else if (seq.equals(name)) { int width arg null ? 1 : Integer.parseInt(arg); tokens.add(new SequenceToken(width)); } else if (group.equals(name)) { tokens.add(new GroupToken(Integer.parseInt(arg))); } else { throw new IllegalArgumentException(未知占位符: name); } last m.end(); } if (last template.length()) { tokens.add(new LiteralToken(template.substring(last))); } return tokens; } }正则\$\{(\w)(?::(\d))?\}中外层\$\{...\}匹配占位符语法\w捕获占位符名称(?::(\d))?捕获可选的参数。${seq:3}里的 3 就是在这个分组里拿到的。核心逻辑是每次m.find()命中一个占位符时先记录占位符之前的普通文本作为LiteralToken再根据占位符名称创建对应 Token 对象最后更新last位置。循环结束后把模板剩余部分补一个LiteralToken。每个 Token 是一个接口的实现public interface RuleToken { String render(RenameContext context); }RenameContext里带着当前源文件的主文件名、序号计数器和正则匹配结果。NameToken.render返回context.getName()SequenceToken.render返回String.format(%0 width d, context.getSeq())GroupToken.render返回context.getMatcher().group(groupIndex)。三个实现加起来不到 40 行但已经覆盖了最常见的需求。这里有一个在拆代码时容易忽略的细节数字宽度的语义。String.format(%03d, 1234)输出的是1234而不是999格式串的宽度只是最小宽度不是最大宽度。当文件数量超过 999 时三位零填充不会截断序号会悄悄变成四位数。所以在SequenceToken里要考虑溢出策略否则大规模批次下格式会错乱。这种边角问题正是实际跑批量任务时最容易翻车的地方。3.2 引擎调度遍历、匹配、解析、校验、执行的五步流程RenameEngine是整个工具的中枢execute方法按五步走。public class RenameEngine { private final FileWalker fileWalker; private final FileMatcher fileMatcher; private final RuleParser ruleParser; private final ConflictDetector conflictDetector; private final NameValidator nameValidator; public RenameResult execute(RenameConfig config, boolean dryRun) { ListPath files fileWalker.walk(config.getTargetDir(), config.isRecursive()); ListRenameItem pending new ArrayList(); ListRuleToken tokens ruleParser.parse(config.getRenameTemplate()); int seq 1; for (Path file : files) { String fileName file.getFileName().toString(); OptionalFileMatch match fileMatcher.matches(fileName, config); if (!match.isPresent()) { continue; } RenameContext ctx new RenameContext( stripExt(fileName), seq, match.get().matcher()); String newBase tokens.stream() .map(t - t.render(ctx)) .collect(Collectors.joining()); String newName newBase extOf(fileName); if (nameValidator.isValid(newName) !conflictDetector.hasConflict(file, file.resolveSibling(newName))) { pending.add(new RenameItem(file, file.resolveSibling(newName))); seq; } } if (dryRun) { pending.forEach(item - log.info(RENAME {} - {}, item.source(), item.target())); return new RenameResult(pending, Collections.emptyList()); } ListPath done new ArrayList(); for (RenameItem item : pending) { try { Files.move(item.source(), item.target()); done.add(item.target()); } catch (IOException e) { log.severe(MOVE FAILED: item.source() , e.getMessage()); } } return new RenameResult(pending, done); } }五步分别是遍历收集所有候选文件 → 用FileMatcher过滤出命中的文件 → 用解析好的 Token 列表逐 Token 渲染出新文件名 → 用NameValidator和ConflictDetector双重校验 → 执行Files.move落盘。seq计数器只在文件被加入 pending 队列时递增保证了序号连续不会因为某个文件被冲突检测跳过而出现空洞。resolveSibling(newName)是java.nio.file.Path的常用 API拿到当前文件同目录下的一个新路径相当于手工拼接父目录和新文件名。它比Paths.get(parent, newName)更直观也不容易踩分隔符的坑。注意Files.move这里没有传REPLACE_EXISTING目标文件存在时会抛FileAlreadyExistsExceptionengine 捕获后记一条失败日志继续执行下一个文件不会中断整个批次。这比默认覆盖安全得多。如果用户显式传入--overwrite参数这里才加上StandardCopyOption.REPLACE_EXISTING。覆盖策略被单独交给参数控制而不是写死在引擎里是我比较认可的一个设计决定。3.3 冲突检测与扩展名保护防止覆盖和改名丢失public class ConflictDetector { private final SetString occupied new HashSet(); public boolean hasConflict(Path source, Path target) { if (target.equals(source)) { return true; } String key target.toString().toLowerCase(Locale.ROOT); if (occupied.contains(key) || Files.exists(target)) { return true; } occupied.add(key); return false; } }hasConflict返回 true 表示冲突调用方跳过该文件。判断依据有三个目标路径和源路径相同自己改成自己属于无效操作当前批次内已经有一个文件占用了这个目标名磁盘上已经存在同名文件。三个条件任何一个命中即冲突。这里有个容易被误解的行为target.equals(source)在 Windows 和 macOS 这类大小写不敏感的文件系统上abc.jpg改成ABC.jpg时可能返回 true引擎会把这次操作判为无效而跳过。用户觉得“我只是改了大写”系统却认为“路径没有变化”。解决办法是给引擎加一个--force-case-change容错参数遇到这种名字时直接用Files.move尝试执行让底层文件系统去决定合法性。扩展名保护逻辑是一段独立的小方法private String stripExt(String fileName) { int dot fileName.lastIndexOf(.); if (dot 0) { return fileName; } return fileName.substring(0, dot); }lastIndexOf(.)找最后一个点去掉它后面部分作为主文件名。dot 0的判断很关键如果点是第一个字符比如.gitignore整个文件会被当作主文件名扩展名为空。如果不判边界隐藏文件会被切成空字符串重命名之后直接丢名字。这种小坑在真实项目里非常常见写文件处理工具时一定要记住。4. 运行配置与避坑排查从命令行启动到五条血泪经验4.1 环境准备与三种启动方式先把环境准备好。项目要求 JDK 8 以上Maven 3.6 以上。不需要联网拉依赖因为 pom 里没有任何第三方库唯一的风险是本地 Maven 仓库缺基础插件用阿里云镜像源或默认中央仓库都能解决。构建命令很简单mvn clean package -DskipTests不想用 Maven 也可以用 javac 直接编译javac -encoding UTF-8 -d out $(find src/main/java -name *.java)Windows 下没有 find 命令直接用 Maven 就好别在编译环境上浪费时间。编译产物在target/目录下运行方式有三种。干运行预览模式最推荐先跑这一步java -jar target/file-renamer-1.0.jar \ --config src/main/resources/rename.properties \ --dir /tmp/photo_test \ --dry-run--dry-run让引擎跑完整个流程但不对文件做任何修改输出格式为RENAME /old/path - /new/path。实际执行时去掉--dry-run即可。第三种是反向恢复读取上次操作日志恢复原文件名java -jar target/file-renamer-1.0.jar \ --reverse --log logs/rename-20250101-153022.log这相当于给批量重命名加了后悔药规则写错了也能按日志一键还原。4.2 配置文件字段说明rename.properties是默认配置字段含义如下配置项示例值说明dir.target/data/photos目标目录命令行 --dir 可覆盖dir.recursivetrue是否递归子目录match.moderegex匹配模式prefix/suffix/contains/regexmatch.patternIMG_\d{4}匹配模式对应的表达式match.caseSensitivefalse匹配时是否区分大小写rename.templatephoto_${seq:3}.jpg重命名模板rename.extKeeptrue是否保留源扩展名log.output./logs操作日志输出目录advance.forceCaseChangefalse是否允许仅大小写不同的重命名这里最需要注意的是match.pattern在 properties 文件里的转义。properties 文件加载时\d会被 Java 的Properties当成转义字符消费掉所以正则里的\d在配置里必须写成\\d。如果忘记双写加载后正则表达式就只剩d匹配结果全错。我第一次跑这个工具时就栽在这里日志显示 0 个文件被匹配排查了半天才意识到是配置文件转义的问题。4.3 常见问题排查五条血泪经验第一个问题任务执行完日志显示 0 个文件被命中但目录下明明有符合预期的文件。现象是批量重命名任务跑完日志里一个 RENAME 记录都没有。原因是配置文件里正则表达式的反斜杠被Properties加载时转义掉了\d{4}变成d{4}。解决方法是正则里所有反斜杠写成双反斜杠\\d或者在ConfigLoader里对加载后的字符串做一次反转义。我一般会在加载之后把 pattern 值打印出来确认一遍先确定加载阶段的值没问题再排查匹配逻辑。第二个问题重命名执行后某些文件不见了。现象是执行完重命名发现目录里少了几个文件日志里也没有报错。原因有两个一是目标目录里已存在同名文件冲突检测把源文件跳过但用户以为改名成功二是Files.move带了REPLACE_EXISTING直接把磁盘上的同名旧文件覆盖了。解决方法是默认不启用覆盖选项只有用户显式传入--overwrite才开启。我在改造时把覆盖策略抽成了枚举传进引擎避免在 engine 里写死覆盖参数。第三个问题序号生成结果位数不对。现象是${seq:3}生成的序号超过 999 之后变成 4 位数格式错乱。原因是String.format(%03d, 1000)输出的是1000格式串的宽度参数只是最小宽度不是截断长度。解决方法是给SequenceToken增加溢出策略要么自动扩位要么循环封顶。实际处理几万张图片时这个问题很典型3 位宽度在 1024 个文件时就不够用了靠肉眼检查很难发现。第四个问题中文文件名乱码。现象是日志里中文名显示成?重命名后原名中的中文变成乱码。原因是 Windows 控制台默认编码是 GBKJava 字符串内部是 UTF-16日志输出走了系统默认编码中文就被转坏了。解决方法是启动 JVM 时加-Dfile.encodingUTF-8同时LogWriter里用Files.newBufferedWriter(path, StandardCharsets.UTF_8)写文件不依赖PrintWriter的默认编码。这个问题根源不在重命名引擎是 IO 编码但绝大多数第一次碰到的人都会以为是引擎的 bug。第五个问题递归遍历太慢大目录下执行耗时达到分钟级。现象是在数万文件的目录下工具执行耗时超过两分钟。原因有两个一是FileWalker用了Files.walk但没利用 Stream 的并行能力二是每个文件都调用Files.exists做磁盘检查文件数量大时元数据查询次数成倍增加。解决方法是给Files.walk的 Stream 加.parallel()同时在ConflictDetector里把已占用文件名缓存到内存Set先查内存再查磁盘。我在处理一份 8 万文件的日志目录时这两个改动把耗时从 4 分钟压到了 20 秒左右。5. 二次开发把命令行工具改造成通用重命名服务5.1 暴露 HTTP 接口让发布系统直接调用这个工具的模块划分使扩展成本很低。最值得做的一个改造是把命令行入口换成 HTTP 接口复用RenameConfig模型对外提供POST /rename/preview和POST /rename/execute两个端点。第一个返回将要执行的改名清单第二个执行并返回日志文件名。如果不想引入 SpringJDK 自带com.sun.net.httpserver就够用想进现有服务体系就包一层 Spring Boot Controller内部直接调RenameEngine.execute核心代码一行不用改。5.2 扩展序号策略支持幂等重命名当前SequenceGenerator只有零填充序号一种策略。我一般会加三类策略进去时间戳序号、UUID 短序号、文件名哈希序号。哈希序号最实用它让“同一批文件不管跑几遍生成的名称都一样”这在增量同步和幂等校验场景下特别关键。实现上只需要改SequenceToken.render()新增策略在渲染时读取文件内容哈希即可完全不用动引擎。5.3 增加规则链做多轮变换把RenameEngine.execute里的模板渲染循环抽出来形成applyRule(String currentName, RenameRule rule)让配置支持多轮规则依次作用。注意每轮之间要重新分离扩展名序号只在首轮计算避免多轮引用同一个序号变量导致结果不一致。完整的源码工程和配置文件已经在下载资源里打包好了适合直接下载到本地跑通再动手改。我自己的习惯是无论改哪个模块先跑一遍全部已有单元测试再为新行为补测试最后一定跑一遍--dry-run确认改动没有影响已有批次。从那以后每次改RenameEngine我都会强制走一遍干运行成本为零但能挡住大部分低级错误。希望帮到你。本文还有配套的精品资源点击获取