本文详解如何在 Apache Commons Net 的 FTPClient 中，通过 FTPFileFilter 结合正则表达式，实现对远程 FTP 目录中特定命名规则文件的条件下载，避免全量拉取。
本文详解如何在 apache commons net 的 `ftpclient` 中，通过 `ftpfilefilter` 结合正则表达式，实现对远程 ftp 目录中特定命名规则文件的条件下载，避免全量拉取。
在 Java 中使用 FTPClient 下载文件时，若需按名称模式（如日期前缀、版本号、扩展名或复杂命名规范）筛选目标文件，而非下载整个目录，关键在于避免遍历后手动过滤，而应利用 FTPClient.listFiles(String, FTPFileFilter) 方法，在服务端列表获取阶段即完成高效过滤。
FTPFileFilter 是一个函数式接口，仅含 accept(FTPFile file) 方法，返回 true 表示该文件应被纳入结果集。结合 java.util.regex.Pattern，可轻松实现灵活的正则匹配逻辑。
以下为增强版 downloadFolder 方法，支持传入正则表达式字符串，并自动编译为 Pattern 实例用于文件名匹配：
import org.apache.commons.net.ftp.FTPClient;
import org.apache.commons.net.ftp.FTPFile;
import java.io.*;
import java.util.regex.Pattern;
private static void downloadFolder(
FTPClient ftpClient,
String remotePath,
String localPath,
String fileNameRegex) throws IOException {
System.out.println("Downloading folder '" + remotePath + "' to '" + localPath +
"' with regex: " + fileNameRegex);
// 编译正则，复用 Pattern 提升性能（生产环境建议提取为常量或缓存）
Pattern pattern = Pattern.compile(fileNameRegex);
// 使用 FTPFileFilter 进行服务端侧过滤（仅获取匹配的文件/目录）
FTPFile[] remoteFiles = ftpClient.listFiles(remotePath, file ->
pattern.matcher(file.getName()).matches()
);
if (remoteFiles == null || remoteFiles.length == 0) {
System.out.println("No files matched regex '" + fileNameRegex + "' in " + remotePath);
return;
}
for (FTPFile remoteFile : remoteFiles) {
// 跳过 . 和 ..（尽管 listFiles 通常已过滤，仍建议保留防御性检查）
String name = remoteFile.getName();
if (".".equals(name) || "..".equals(name)) continue;
String remoteFilePath = remotePath + "/" + name;
String localFilePath = localPath + "/" + name;
if (remoteFile.isDirectory()) {
File localDir = new File(localFilePath);
if (!localDir.exists() && !localDir.mkdirs()) {
throw new IOException("Failed to create local directory: " + localFilePath);
}
// 递归下载子目录（注意：子目录名也需满足正则！若需不同规则，请拆分参数）
downloadFolder(ftpClient, remoteFilePath, localFilePath, fileNameRegex);
} else {
System.out.println("Downloading file: " + remoteFilePath);
try (OutputStream outputStream = new BufferedOutputStream(
new FileOutputStream(localFilePath))) {
if (!ftpClient.retrieveFile(remoteFilePath, outputStream)) {
throw new IOException("FTP retrieve failed for: " + remoteFilePath);
}
}
}
}
}✅ 调用示例：
立即学习“Java免费学习笔记（深入）”；
// 仅下载以 "report_" 开头、后接 8 位数字、以 ".csv" 结尾的文件（如 report_20240401.csv）
downloadFolder(ftpClient, "/data/reports", "./downloads", "^report_\d{8}\.csv$");
// 下载所有日志文件（不区分大小写）
downloadFolder(ftpClient, "/logs", "./logs", "(?i)\.log$");⚠️ 重要注意事项：
- 正则作用域仅为文件名（不含路径）：file.getName() 返回的是纯文件/目录名，不包含路径，因此正则无需也不应匹配 / 或路径分隔符。
- 目录也会被匹配：若正则意外匹配了子目录名（如 ^backup.*），该目录将被当作“文件”尝试下载（导致失败）或进入递归逻辑——请确保正则设计符合业务意图，或在 if (remoteFile.isDirectory()) 分支中额外校验是否允许进入该目录。
- 性能提示：listFiles(String, FTPFileFilter) 仍会拉取完整目录列表并在客户端过滤（FTP 协议本身不支持服务端正则过滤），但相比先全量 listFiles() 再 Java 层循环 filter()，它减少了冗余对象创建，代码更简洁、语义更清晰。
- 异常处理建议：生产环境应捕获 IOException 并记录上下文（如当前 remoteFilePath），便于故障定位；同时考虑添加重试机制与连接超时配置。
- 依赖版本：确保使用 Apache Commons Net ≥ 3.6（推荐 ≥ 3.9），以获得最佳稳定性和安全性。
通过上述方式，您即可在保持原有递归结构的同时，赋予 FTP 下载任务精准的文件筛选能力，显著提升数据同步的可控性与效率。
