如何使用AWS Java SDK v2实现本地目录上传到S3指定路径的函数

AWS Java SDK v2 提供了独立的 s3-transfer-manager 模块，内置了批量上传本地目录的能力，功能覆盖v1版本的TransferManager全部特性，无需手动遍历文件实现上传逻辑。

第一步：添加依赖 #

首先在项目中引入s3-transfer-manager依赖，以Maven为例：

<dependency>
    <groupId>software.amazon.awssdk</groupId>
    <artifactId>s3-transfer-manager</artifactId>
    <version>2.20.0</version> <!-- 替换为最新稳定版 -->
</dependency>

如果使用Gradle：

implementation 'software.amazon.awssdk:s3-transfer-manager:2.20.0'

第二步：函数实现 #

import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider
import software.amazon.awssdk.regions.Region
import software.amazon.awssdk.transfer.s3.S3TransferManager
import software.amazon.awssdk.transfer.s3.model.UploadDirectoryRequest
import java.nio.file.Path

fun uploadDirectory(bucket: String, prefix: String, directory: Path) {
    // 校验本地目录合法性
    require(directory.toFile().isDirectory) { "传入的路径不是有效目录: $directory" }
    
    // 格式化prefix，确保以/结尾，避免路径拼接错误
    val formattedPrefix = if (prefix.endsWith("/")) prefix else "$prefix/"

    // 初始化TransferManager，生产环境建议复用单例，避免重复初始化
    S3TransferManager.builder()
        .s3ClientConfiguration { cfg ->
            cfg.credentialsProvider(DefaultCredentialsProvider.create())
                .region(Region.of("你的AWS区域")) // 可改为参数传入，或者从环境变量读取
        }
        .use { transferManager ->
            // 构建目录上传请求
            val uploadRequest = UploadDirectoryRequest.builder()
                .bucket(bucket)
                .s3Prefix(formattedPrefix)
                .source(directory)
                // 可选配置：过滤不需要上传的文件，比如跳过隐藏文件
                .fileFilter { path -> !path.fileName.toString().startsWith(".") }
                .build()

            // 启动上传，等待所有文件上传完成
            val uploadDirectoryResponse = transferManager.uploadDirectory(uploadRequest)
            uploadDirectoryResponse.completionFuture().join()

            // 可选：打印上传失败的文件
            uploadDirectoryResponse.failedTransfers().forEach {
                println("上传失败: ${it.exception().message}, 文件: ${it.request().source()}")
            }
        }
}

特性说明 #

• 自动处理大文件分块上传、小文件并行上传，性能优于手动单文件上传实现
• 内置失败重试机制，稳定性更高
• 支持自定义文件过滤规则、上传并发数、分块大小等参数
• 如果需要实现增量同步（仅上传修改过的文件，跳过S3上已存在且和本地一致的文件），可以在UploadDirectoryRequest中添加配置，或者自定义uploadFileTransformer判断文件是否需要上传。

注意事项 #

• 生产环境中建议将S3TransferManager作为单例复用，不要每次调用函数都初始化，减少资源消耗
• 确保运行环境配置了正确的AWS凭据和区域，且拥有S3的PutObject权限，以及本地目录的读取权限
• 空目录默认不会上传到S3（因为S3是对象存储，没有目录实体，仅通过对象key的/模拟目录结构），如果需要保留空目录，可以手动遍历本地空目录，上传一个大小为0、key以/结尾的占位对象。

内容的提问来源于stack exchange，提问作者Adam Millerchip