# 适用于 Java 2.x 的 AWS 开发工具包 - Amazon S3 ## 概述 Amazon S3（简单存储服务）是一种对象存储，旨在从任何地方存储和检索任意数量的数据。此技能涵盖使用 AWS SDK for Java 2.x 使用 S3 的模式，包括存储桶操作、对象上传/下载、预签名 URL、分段传输和 Spring Boot 集成。 ## 何时使用在以下情况下使用此技能： * 使用正确的配置创建、列出或删除 S3 存储桶 * 通过元数据和加密从 S3 上传或下载对象 * 使用错误处理功能处理大文件 (>100MB) 的分段上传 * 生成预签名 URL 以临时访问 S3 对象 * 在 S3 存储桶之间复制或移动对象并保留元数据 * 设置对象元数据、存储类别和访问控制 * 实施 S3 Transfer Manager 以优化文件传输 * 将S3与Spring Boot应用程序集成以实现云存储 * 设置 S3 事件通知以进行对象生命周期管理 * 管理存储桶策略、CORS 配置和访问控制 * 实现S3操作的重试机制和错误处理 * 测试 S3 与 LocalStack 的开发环境集成 ## 说明请按照以下步骤使用 Amazon S3： 1. **添加依赖项** \- 包括 S3 和可选的传输管理器依赖项 2. **创建客户端** \- 使用区域和凭据实例化 S3Client 3. **创建Bucket** \- 使用具有唯一名称和配置的createBucket() 4. **上传对象** \- 对于小文件使用 putObject() 或对于大文件使用 Transfer Manager 5. **下载对象** \- 将 getObject() 与 ResponseInputStream 结合使用 6. **生成预签名 URL** \- 使用 S3Presigner 进行临时访问 7. **配置权限** \- 设置存储桶策略和访问控制 8. **设置生命周期规则** \- 配置对象过期和转换 ## 依赖关系 <依赖关系> software.amazon.awssdk s3 2.20.0 // 使用最新的稳定版本 <依赖关系> software.amazon.awssdk s3-transfer-manager 2.20.0 // 使用最新的稳定版本 <依赖关系> software.amazon.awssdk netty-nio-client 2.20.0 // 使用最新的稳定版本 ## 客户端设置 ### 基本同步客户端导入软件.amazon.awssdk.regions.Region; 导入软件.amazon.awssdk.services.s3.S3Client; S3Client s3Client = S3Client.builder() .region(区域.US_EAST_1) .build(); ### 基本异步客户端导入 software.amazon.awssdk.services.s3.S3AsyncClient; S3AsyncClient s3AsyncClient = S3AsyncClient.builder() .region(区域.US_EAST_1) .build(); ### 使用重试逻辑配置客户端导入 software.amazon.awssdk.http.apache.ApacheHttpClient; 导入 software.amazon.awssdk.core.retry.RetryPolicy; 导入 software.amazon.awssdk.core.retry.backoff.ExponentialRetryBackoff; 导入java.time.Duration； S3Client s3Client = S3Client.builder() .region(区域.US_EAST_1) .httpClientBuilder(ApacheHttpClient.builder() .maxConnections(200) .connectionTimeout(Duration.ofSeconds(5))) .overrideConfiguration(b -> b .apiCallTimeout(Duration.ofSeconds(60)) .apiCallAttemptTimeout(Duration.ofSeconds(30)) .retryPolicy(RetryPolicy.builder() .numRetries(3) .retryBackoffStrategy(ExponentialRetryBackoff.builder() .baseDelay(持续时间.ofSeconds(1)) .maxBackoffTime(持续时间.ofSeconds(30)) .build()) .build())) .build(); ## 基本桶操作 ### 创建存储桶导入软件.amazon.awssdk.services.s3.model.*; 导入 java.util.concurrent.CompletableFuture; 公共无效createBucket（S3Client s3Client，字符串bucketName）{ 尝试{ CreateBucketRequest 请求 = CreateBucketRequest.builder() .bucket(bucketName) .build(); s3Client.createBucket(请求); // 等待桶准备好 HeadBucketRequest waitRequest = HeadBucketRequest.builder() .bucket(bucketName) .build(); s3Client.waiter().waitUntilBucketExists(waitRequest); System.out.println("桶创建成功：" + BucketName); } catch (S3Exception e) { System.err.println("创建存储桶时出错：" + e.awsErrorDetails().errorMessage()); 扔 e； } } ### 列出所有存储桶公共列表<字符串> listAllBuckets(S3Client s3Client) { ListBucketsResponse 响应 = s3Client.listBuckets(); 返回response.buckets().stream() .map(桶::名称) .collect(Collectors.toList()); } ### 检查桶是否存在公共布尔bucketExists（S3Client s3Client，字符串bucketName）{ 尝试{ HeadBucketRequest 请求 = HeadBucketRequest.builder() .bucket(bucketName) .build(); s3Client.headBucket(请求); 返回真； } catch (NoSuchBucketException e) { 返回假； } } ## 基本对象操作 ### 将文件上传到S3 导入 software.amazon.awssdk.core.sync.RequestBody; 导入java.nio.file.Paths；公共无效uploadFile（S3Client s3Client，字符串bucketName，字符串键，字符串文件路径）{ PutObjectRequest 请求 = PutObjectRequest.builder() .bucket(bucketName) .key(键) .build(); s3Client.putObject(请求, RequestBody.fromFile(Paths.get(filePath))); System.out.println("文件上传：" + key); } ### 从 S3 下载文件导入 software.amazon.awssdk.core.ResponseInputStream; 导入 software.amazon.awssdk.services.s3.model.GetObjectResponse; 导入java.nio.file.Paths；公共无效downloadFile（S3Client s3Client，字符串bucketName，字符串键，字符串destPath）{ GetObjectRequest 请求 = GetObjectRequest.builder() .bucket(bucketName) .key(键) .build(); s3Client.getObject(请求, Paths.get(destPath)); System.out.println("下载的文件：" + destPath); } ### 获取对象元数据公共Map <字符串，字符串> getObjectMetadata（S3Client s3Client，字符串bucketName，字符串键）{ HeadObjectRequest 请求 = HeadObjectRequest.builder() .bucket(bucketName) .key(键) .build(); HeadObjectResponse 响应 = s3Client.headObject(请求); 返回response.metadata(); } ## 高级对象操作 ### 使用元数据和加密上传公共无效 uploadWithMetadata(S3Client s3Client, 字符串bucketName, 字符串键, 字符串 filePath, Map 元数据) { PutObjectRequest 请求 = PutObjectRequest.builder() .bucket(bucketName) .key(键) .元数据（元数据） .contentType(“应用程序/pdf”) .serverSideEncryption(ServerSideEncryption.AES256) .storageClass(StorageClass.STANDARD_IA) .build(); PutObjectResponse 响应 = s3Client.putObject(请求, RequestBody.fromFile(Paths.get(filePath))); System.out.println("上传完成。ETag: " + response.eTag()); } ### 在存储桶之间复制对象公共无效copyObject（S3Client s3Client，字符串sourceBucket，字符串sourceKey，字符串 destBucket、字符串 destKey) { CopyObjectRequest 请求 = CopyObjectRequest.builder() .sourceBucket(sourceBucket) .sourceKey(源密钥) .destinationBucket(destBucket) .destinationKey(destKey) .build(); s3Client.copyObject(请求); System.out.println("复制的对象：" + sourceKey + " -> " + destKey); } ### 删除多个对象公共无效deleteMultipleObjects（S3Client s3Client，字符串bucketName，List 键）{ List objectIds =keys.stream() .map(key -> ObjectIdentifier.builder().key(key).build()) .collect(Collectors.toList()); 删除删除=Delete.builder() .objects(objectIds) .build(); DeleteObjectsRequest请求=DeleteObjectsRequest.builder() .bucket(bucketName) .删除（删除） .build(); DeleteObjectsResponse 响应 = s3Client.deleteObjects(请求); response.deleted().forEach(已删除 -> System.out.println("已删除：" +deleted.key())); response.errors().forEach(错误 -> System.err.println("删除失败" + error.key() + ": " + error.message())); } ## 预签名 URL ### 生成下载地址导入 software.amazon.awssdk.services.s3.presigner.S3Presigner; 导入 software.amazon.awssdk.services.s3.presigner.model.*; 导入java.time.Duration；公共字符串generateDownloadUrl（字符串bucketName，字符串键）{ 尝试 (S3Presigner presigner = S3Presigner.builder() .region(区域.US_EAST_1) .build()) { GetObjectRequest getObjectRequest = GetObjectRequest.builder() .bucket(bucketName) .key(键) .build(); GetObjectPresignRequest presignRequest = GetObjectPresignRequest.builder() .signatureDuration(持续时间.ofMinutes(10)) .getObjectRequest(getObjectRequest) .build(); PresignedGetObjectRequest presignedRequest = presigner.presignGetObject(presignRequest); 返回 presignedRequest.url().toString(); } } ### 生成上传网址公共字符串generateUploadUrl（字符串bucketName，字符串键）{ 尝试 (S3Presigner presigner = S3Presigner.create()) { PutObjectRequest putObjectRequest = PutObjectRequest.builder() .bucket(bucketName) .key(键) .build(); PutObjectPresignRequest presignRequest = PutObjectPresignRequest.builder() .signatureDuration(Duration.ofMinutes(5)) .putObjectRequest(putObjectRequest) .build(); PresignedPutObjectRequest presignedRequest = presigner.presignPutObject(presignRequest); 返回 presignedRequest.url().toString(); } } ## S3 传输管理器 ### 使用传输管理器上传导入软件.amazon.awssdk.transfer.s3.*; 导入 software.amazon.awssdk.transfer.s3.model.*; 公共无效uploadWithTransferManager（字符串bucketName，字符串键，字符串文件路径）{ 尝试（S3TransferManager TransferManager = S3TransferManager.create（））{ UploadFileRequest uploadRequest = UploadFileRequest.builder() .putObjectRequest(请求->请求 .bucket(bucketName) .key(键)) .source(Paths.get(文件路径)) .build(); FileUpload上传=transferManager.uploadFile(uploadRequest); // 监控进度 upload.progressFuture().thenAccept(进度 -> { System.out.println("上传进度：" + Progress.progressPercent() + "%"); }); CompletedFileUpload 结果 = upload.completionFuture().join(); System.out.println("上传完成。ETag: " + result.response().eTag()); } } ### 使用传输管理器下载公共无效 downloadWithTransferManager（字符串bucketName，字符串键，字符串destPath）{ 尝试（S3TransferManager TransferManager = S3TransferManager.create（））{ DownloadFileRequest downloadRequest = DownloadFileRequest.builder() .getObjectRequest(请求->请求 .bucket(bucketName) .key(键)) .destination(Paths.get(destPath)) .build(); FileDownload 下载 = TransferManager.downloadFile(downloadRequest); CompletedFileDownload 结果 = download.completionFuture().join(); System.out.println("下载完成。大小：" + result.response().contentLength()); } } ## Spring Boot 集成 ### 配置属性导入 org.springframework.boot.context.properties.ConfigurationProperties; @ConfigurationProperties（前缀=“aws.s3”）公共类 S3Properties { 私有字符串访问密钥；私有字符串密钥；私有字符串区域=“us-east-1”；私有字符串端点；私有字符串defaultBucket；私有布尔 asyncEnabled = false; 私有布尔transferManagerEnabled = true; // 获取器和设置器公共字符串 getAccessKey() { 返回 accessKey; } 公共无效 setAccessKey(String accessKey) { this.accessKey = accessKey; } // ...其他 getter 和 setter } ### S3配置类导入 org.springframework.context.annotation.Bean; 导入 org.springframework.context.annotation.Configuration; 导入 software.amazon.awssdk.auth.credentials.AwsBasicCredentials；导入 software.amazon.awssdk.auth.credentials.StaticCredentialsProvider；导入软件.amazon.awssdk.services.s3.S3Client; 导入 software.amazon.awssdk.services.s3.S3AsyncClient; 导入软件.amazon.awssdk.regions.Region; 导入java.net.URI； @配置公共类 S3Configuration { 私有最终 S3Properties 属性；公共 S3Configuration（S3Properties 属性）{ this.properties = 属性； } @豆子公共 S3Client s3Client() { S3Client.Builder 构建器 = S3Client.builder() .region(Region.of(properties.getRegion())); if (properties.getAccessKey() != null &&properties.getSecretKey() != null) { builder.credentialsProvider(StaticCredentialsProvider.create( AwsBasicCredentials.create( 属性.getAccessKey(), 属性.getSecretKey()))); } if (properties.getEndpoint() != null) { builder.endpointOverride(URI.create(properties.getEndpoint())); } 返回 builder.build(); } @豆子公共 S3AsyncClient s3AsyncClient() { S3AsyncClient.Builder 构建器 = S3AsyncClient.builder() .region(Region.of(properties.getRegion())); if (properties.getAccessKey() != null &&properties.getSecretKey() != null) { builder.credentialsProvider(StaticCredentialsProvider.create( AwsBasicCredentials.create( 属性.getAccessKey(), 属性.getSecretKey()))); } if (properties.getEndpoint() != null) { builder.endpointOverride(URI.create(properties.getEndpoint())); } 返回 builder.build(); } @豆子公共 S3TransferManager s3TransferManager() { 返回 S3TransferManager.builder() .s3Client(s3Client()) .build(); } } ### S3 服务导入 org.springframework.stereotype.Service; 导入 software.amazon.awssdk.transfer.s3.S3TransferManager; 导入软件.amazon.awssdk.services.s3.model.*; 导入 java.nio.file.*; 导入 java.util.*; 导入 java.util.concurrent.CompletableFuture; @服务 @RequiredArgsConstructor 公共类S3Service { 私有最终S3Client s3Client；私有最终 S3AsyncClient s3AsyncClient；私有最终S3TransferManager传输管理器；私有最终 S3Properties 属性；公共 CompletableFuture uploadFileAsync(String key, 路径文件) { PutObjectRequest 请求 = PutObjectRequest.builder() .bucket(属性.getDefaultBucket()) .key(键) .build(); 返回 CompletableFuture.runAsync(() -> { s3Client.putObject(请求, RequestBody.fromFile(文件)); }); } 公共 CompletableFuture downloadFileAsync(String key) { GetObjectRequest 请求 = GetObjectRequest.builder() .bucket(属性.getDefaultBucket()) .key(键) .build(); 返回 CompletableFuture.supplyAsync(() -> { 尝试 (ResponseInputStream 响应 = s3Client.getObject(请求)) { 返回response.readAllBytes(); } catch (IOException e) { throw new RuntimeException("无法读取 S3 对象", e); } }); } 公共 CompletableFuturegeneratePresignedUrl(String key, Duration 持续时间) { 返回 CompletableFuture.supplyAsync(() -> { 尝试 (S3Presigner presigner = S3Presigner.builder() .region(Region.of(properties.getRegion())) .build()) { GetObjectRequest getRequest = GetObjectRequest.builder() .bucket(属性.getDefaultBucket()) .key(键) .build(); GetObjectPresignRequest presignRequest = GetObjectPresignRequest.builder() .signatureDuration(持续时间) .getObjectRequest(getRequest) .build(); 返回 presigner.presignGetObject(presignRequest).url().toString(); } }); } 公共 Flux listObjects(字符串前缀) { ListObjectsV2Request 请求 = ListObjectsV2Request.builder() .bucket(属性.getDefaultBucket()) .前缀（前缀） .build(); 返回 Flux.create(sink -> { s3Client.listObjectsV2Paginator（请求） .contents() .forEach(sink::next); 接收器.complete(); }); } } ## 示例 ### 基本文件上传示例公共类S3UploadExample { 公共静态无效主（字符串[] args）{ // 初始化客户端 S3Client s3Client = S3Client.builder() .region(区域.US_EAST_1) .build(); 字符串bucketName =“我的示例bucket”; String filePath = "文档.pdf"; String key = "uploads/document.pdf"; // 如果桶不存在则创建 if (!bucketExists(s3Client,bucketName)) { createBucket(s3Client, 存储桶名称); } // 上传文件 Map 元数据 = Map.of( “作者”、“约翰·多伊”、 “内容类型”，“应用程序/pdf”， “上传日期”，java.time.LocalDate.now().toString() ）； uploadWithMetadata(s3Client, BucketName, key, filePath, 元数据); // 生成预签名 URL String downloadUrl =generateDownloadUrl(bucketName, key); System.out.println("下载地址：" + downloadUrl); // 关闭客户端 s3Client.close(); } } ### 批处理文件处理示例导入 java.nio.file.*; 导入 java.util.stream.*; 公共类S3BatchProcessing { 公共无效processDirectoryUpload（S3Client s3Client，字符串bucketName，字符串directoryPath）{ 尝试 (Stream paths = Files.walk(Paths.get(directoryPath))) { List> futures = paths .filter(文件::isRegularFile) .map(路径 -> { String key = BucketName + "/" + path.getFileName().toString(); 返回 CompletableFuture.runAsync(() -> { uploadFile(s3Client,bucketName,key,path.toString()); }); }) .collect(Collectors.toList()); // 等待所有上传完成 CompletableFuture.allOf( futures.toArray(new CompletableFuture[0]) ).join(); System.out.println("所有文件上传成功"); } catch (IOException e) { throw new RuntimeException("处理目录失败", e); } } } ## 最佳实践 ### 性能优化 1. **使用 S3 Transfer Manager** ：自动处理大于 100MB 的文件的分段上传、并行传输和进度跟踪 2. **重用S3客户端**：客户端是线程安全的，应该在整个应用程序生命周期中重用 3. **启用异步操作** ：使用 S3AsyncClient 进行 I/O 密集型操作以提高吞吐量 4. **配置适当的超时**：为大文件操作设置适当的超时 5. **使用连接池** ：配置 HTTP 客户端以实现最佳连接管理 ### 安全考虑 1. **使用临时凭证**：始终使用 IAM 角色或 AWS STS 来获取短期访问令牌 2. **启用服务器端加密**：对敏感数据使用 AES-256 或 AWS KMS 3. **实施访问控制**：在生产中使用存储桶策略和 IAM 角色而不是访问密钥 4. **验证对象元数据**：清理用户提供的元数据以防止标头注入 5. **使用预签名 URL** ：通过使用临时访问 URL 避免暴露凭据 ### 错误处理 1. **实现重试逻辑**：网络操作应该具有指数退避重试策略 2. **处理限制**：正确处理 429 Too Many Requests 响应 3. **验证对象存在** ：在需要对象的操作之前检查对象是否存在 4. **清理失败的操作** ：中止失败的分段上传 5. **适当记录**：记录成功的操作和错误以进行监控 ### 成本优化 1. **使用适当的存储类别**：根据访问模式选择STANDARD、STANDARD_IA、INTELLIGENT_TIERING 2. **实施生命周期策略**：自动过渡或过期对象 3. **启用对象版本控制**：对于需要保留的重要数据 4. **监控使用情况**：跟踪数据传输和存储成本 5. **最小化 API 调用**：尽可能使用批处理操作 ## 约束和限制 * **文件大小限制** ：单次 PUT 操作限制为 5GB；对于较大的文件使用分段上传 * **批量操作** ：每个删除对象操作最多 1000 个对象 * **元数据大小** ：用户定义的元数据限制为 2KB * **并发传输** ：传输管理器默认处理最多 100 个并发传输 * **区域一致性** ：跨区域操作可能会产生额外的成本和延迟 * **S3 最终一致性**：新对象上传后可能不会立即可见 ## 参考文献欲了解更多详细信息，请参阅： * [AWS S3 对象操作参考]() * [S3 传输管理器模式]() * [Spring Boot 集成指南]() * [AWS S3 开发人员指南]() * [AWS SDK for Java 2.x S3 API]() ## 相关技能 * `aws-sdk-java-v2-core` \- 核心 AWS SDK 模式和配置 * `spring-boot-dependency-injection` \- Spring 依赖注入模式 * `unit-test-service-layer` \- 测试服务层模式 * `unit-test-wiremock-rest-api` \- 测试外部 API 集成 ## 限制和警告 * **对象大小**：单次 PUT 限制为 5GB；对于较大的文件使用分段上传 * **存储桶名称**：在所有 AWS 账户中必须是全局唯一的 * **对象不变性** ：对象不能被修改；必须完全更换 * **最终一致性** ：上传后列表操作可能会有轻微延迟 * **请求率** ：S3 支持高请求率，但有限制 * **存储类别**：某些存储类别有最短持续时间要求 * **预签名 URL** ：最长过期时间为 7 天 * **分段上传**：除最后一部分外，各部分必须至少为 5MB * **删除标记** ：版本控制创建删除标记而不是实际删除 * **跨区域** ：跨区域复制会产生数据传输成本

AWS SDK Java V2 S3

包含技能