使用 Spring Integration 的 RemoteFileTemplate 教程

概述

RemoteFileTemplate 是 Spring Integration 3.0+ 提供的强大抽象层，用于简化 FTP/FTPS 文件操作。它封装了底层 FtpSession，提供线程安全的文件传输操作，并自动管理会话资源。

核心优势

✅ 简化 FTP 操作（上传、下载、删除、重命名）
✅ 自动管理会话生命周期
✅ 支持高级操作（批量执行、存在性检查）
✅ 提供对底层 FTPClient 的访问

基本操作指南

1. 初始化 RemoteFileTemplate

@Configuration
@EnableIntegration
class FtpConfig {

    @Bean
    fun ftpSessionFactory(): DefaultFtpSessionFactory {
        return DefaultFtpSessionFactory().apply {
            host = "ftp.example.com"
            port = 21
            username = "user"
            password = "pass"
        }
    }

    @Bean
    fun remoteFileTemplate(): FtpRemoteFileTemplate {
        return FtpRemoteFileTemplate(ftpSessionFactory()).apply {
            // 设置文件存在检查模式
            existsMode = FtpRemoteFileTemplate.ExistsMode.NLST_AND_DIRS
        }
    }
}

2. 文件上传操作

@Service
class FileUploadService(
    private val remoteFileTemplate: RemoteFileTemplate<FTPFile>
) {
    fun uploadFile(file: File, remotePath: String) {
        remoteFileTemplate.execute { session ->
            session.write(FileInputStream(file), remotePath)
        }
    }
}

3. 文件下载操作

fun downloadFile(remotePath: String, localPath: String) {
    remoteFileTemplate.execute { session ->
        session.read(remotePath).use { inputStream ->
            File(localPath).outputStream().use { output ->
                inputStream.copyTo(output)
            }
        }
    }
}

4. 文件存在性检查

fun checkFileExists(path: String): Boolean {
    return remoteFileTemplate.exists(path)
}

高级功能解析

文件存在检查模式 (ExistsMode)

不同 FTP 服务器对 STAT 命令支持不同，Spring 提供三种检查模式：

模式	适用场景	特点
STAT	标准服务器	默认模式，需要服务器完全支持 STAT 命令
NLST	文件检查	仅适用于文件检查，不支持空目录
NLST_AND_DIRS	兼容模式	先尝试 NLST，失败后使用目录切换检查

// 设置存在性检查模式
remoteFileTemplate.existsMode = FtpRemoteFileTemplate.ExistsMode.NLST

IMPORTANT

对于文件上传操作，Spring 会自动使用 NLST 模式，因为目标路径始终是文件

批量操作 (invoke 方法)

版本 5.0+ 支持在同一个会话中执行多个操作：

fun batchOperations() {
    remoteFileTemplate.invoke { operations ->
        operations.write("file1.txt", inputStream1)
        operations.rename("file1.txt", "archive/file1.txt")
        operations.remove("temp/file2.txt")
        true // 返回操作结果
    }
}

动态文件存在模式 (版本 6.5+)

使用 SpEL 表达式动态决定文件存在时的行为：

@Bean
fun ftpOutboundGateway(): FtpOutboundGateway {
    return FtpOutboundGateway(remoteFileTemplate, "mput", "payload").apply {
        // 根据消息头动态决定文件存在模式
        fileExistsModeExpression = "headers['overwrite'] ? 'REPLACE' : 'FAIL'"
    }
}

动态模式支持的值

• REPLACE: 覆盖现有文件
• APPEND: 追加到现有文件
• IGNORE: 忽略操作
• FAIL: 抛出异常（默认）

实用场景示例

场景 1：安全追加文件内容

fun appendToFile(content: String, remotePath: String) {
    remoteFileTemplate.execute { session ->
        // 追加模式会自动禁用临时文件名
        session.append(ByteArrayInputStream(content.toByteArray()), remotePath)
    }
}

CAUTION

在 APPEND 模式下，临时文件名功能会被自动禁用，否则无法实现真正的追加效果

场景 2：处理特殊 FTP 服务器

fun handleProblematicServer() {
    remoteFileTemplate.execute { session ->
        // 获取底层 FTPClient 实例
        val ftpClient = (session as FtpSession).clientInstance
        
        // 执行自定义 FTP 命令
        ftpClient.sendCommand("SITE SPECIAL-COMMAND")
        
        // 检查服务器响应
        if (ftpClient.replyCode == 200) {
            // 特殊处理逻辑
        }
    }
}

场景 3：递归上传目录

fun uploadDirectory(localDir: File, remotePath: String) {
    remoteFileTemplate.invoke { operations ->
        localDir.walk().forEach { localFile ->
            if (localFile.isFile) {
                val relativePath = localFile.relativeTo(localDir).path
                operations.write("$remotePath/$relativePath", FileInputStream(localFile))
            }
        }
        true
    }
}

最佳实践与注意事项

文件操作模式选择

推荐方式

// 使用 execute/invoke 确保资源正确释放
remoteFileTemplate.execute { session ->
    session.write(inputStream, "remote/file.txt")
}

不推荐方式

// 手动管理会话容易导致资源泄漏
val session = remoteFileTemplate.sessionFactory.session
try {
    session.write(inputStream, "remote/file.txt")
} finally {
    session.close()
}

性能优化建议

1. 复用会话：使用 invoke 方法执行多个操作
2. 批量处理：合并小文件传输请求
3. 连接池：配置合适的会话池大小
4. 超时设置：根据网络状况调整超时参数

@Bean
fun ftpSessionFactory(): DefaultFtpSessionFactory {
    return DefaultFtpSessionFactory().apply {
        // 设置连接超时为 5 秒
        connectTimeout = 5000
        // 设置数据超时为 10 秒
        dataTimeout = 10000
        // 启用会话池 (默认10个)
        isSessionCache = true
    }
}

常见问题解决

问题：上传文件时遇到 550 错误
✅ 检查目录是否存在
✅ 验证用户写入权限
✅ 使用 NLST_AND_DIRS 模式检查目录

remoteFileTemplate.existsMode = FtpRemoteFileTemplate.ExistsMode.NLST_AND_DIRS

问题：文件上传不完整
✅ 增加数据超时时间
✅ 检查网络稳定性
✅ 使用 FTPClient#completePendingCommand() 确认传输完成

remoteFileTemplate.execute { session ->
    val ftpClient = (session as FtpSession).clientInstance
    session.write(inputStream, "file.txt")
    // [!code highlight] // 确保文件传输完全完成
    if (!ftpClient.completePendingCommand()) {
        throw IOException("File transfer failed")
    }
}

总结流程

通过本教程，您应该能够掌握：

1. RemoteFileTemplate 的基本配置和使用
2. 不同文件存在检查模式的应用场景
3. 高级功能如批量操作和动态模式
4. 常见问题的解决方案

Spring Integration 的 FTP 模块持续演进，建议定期查看官方文档获取最新特性。