# 适用于 Java 2.x 的 AWS 开发工具包 - 核心模式 ## 概述配置 AWS 服务客户端、身份验证、超时、HTTP 客户端，并实施适用于 Java 2.x 应用程序的 AWS 开发工具包的最佳实践。此技能提供了构建健壮、高性能且安全的与 AWS 服务集成的基本模式。 ## 说明请按照以下步骤配置适用于 Java 2.x 的 AWS 开发工具包： 1. **添加依赖项** \- 包括 SDK 核心和适当的 HTTP 客户端依赖项 2. **配置凭证** \- 设置凭证提供程序链（环境变量、配置文件、IAM 角色） 3. **创建客户端** \- 构建具有适当区域和配置的服务客户端 4. **配置超时** \- 适当设置 API 调用和尝试超时 5. **设置 HTTP 客户端** \- 选择带有连接池的 Apache（同步）或 Netty（异步） 6. **处理错误** \- 实现正确的异常处理和重试逻辑 7. **关闭资源** \- 始终关闭客户端和流响应 8. **本地测试** \- 使用 LocalStack 或 Testcontainers 进行集成测试 ## 何时使用在以下情况下使用此技能： * 使用正确的配置设置适用于 Java 2.x 服务客户端的 AWS 开发工具包 * 配置身份验证和凭证管理策略 * 实施客户端生命周期管理和资源清理 * 通过 HTTP 客户端配置和连接池优化性能 * 为API调用设置适当的超时配置 * 实施错误处理和重试策略 * 启用监控和指标收集 * 将AWS SDK与Spring Boot应用程序集成 * 测试 AWS 与 LocalStack 和 Testcontainers 的集成 ## 快速入门 ### 基本服务客户端设置导入软件.amazon.awssdk.regions.Region; 导入软件.amazon.awssdk.services.s3.S3Client; // 带区域的基本客户端 S3Client s3Client = S3Client.builder() .region(区域.US_EAST_1) .build(); // 完成后始终关闭客户端尝试 (S3Client s3 = S3Client.builder().region(Region.US_EAST_1).build()) { // 使用客户端 } // 自动关闭 ### 基本身份验证 // 使用默认的凭证提供者链 S3Client s3Client = S3Client.builder() .region(区域.US_EAST_1) .build(); // 自动检测凭证 ## 客户端配置 ### 服务客户端构建器模式导入 software.amazon.awssdk.core.client.config.ClientOverrideConfiguration; 导入 software.amazon.awssdk.http.apache.ApacheHttpClient; 导入 software.amazon.awssdk.http.apache.ProxyConfiguration; 导入 software.amazon.awssdk.metrics.publishers.cloudwatch.CloudWatchMetricPublisher；导入 software.amazon.awssdk.auth.credentials.EnvironmentVariableCredentialsProvider；导入java.time.Duration；导入java.net.URI； // 高级客户端配置 S3Client s3Client = S3Client.builder() .region(区域.EU_SOUTH_2) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .overrideConfiguration(b -> b .apiCallTimeout(持续时间.ofSeconds(30)) .apiCallAttemptTimeout(Duration.ofSeconds(10)) .addMetricPublisher(CloudWatchMetricPublisher.create())) .httpClientBuilder(ApacheHttpClient.builder() .maxConnections(100) .connectionTimeout(Duration.ofSeconds(5)) .proxyConfiguration(ProxyConfiguration.builder() .endpoint(URI.create("http://proxy:8080")) .build())) .build(); ### 单独的配置对象 ClientOverrideConfiguration clientConfig = ClientOverrideConfiguration.builder() .apiCallTimeout(持续时间.ofSeconds(30)) .apiCallAttemptTimeout(Duration.ofSeconds(10)) .addMetricPublisher(CloudWatchMetricPublisher.create()) .build(); ApacheHttpClient httpClient = ApacheHttpClient.builder() .maxConnections(100) .connectionTimeout(Duration.ofSeconds(5)) .build(); S3Client s3Client = S3Client.builder() .region(区域.EU_SOUTH_2) .credentialsProvider(EnvironmentVariableCredentialsProvider.create()) .overrideConfiguration(clientConfig) .httpClient(httpClient) .build(); ## 身份验证和凭证 ### 默认凭证提供商链 // SDK 自动使用默认凭证提供程序链： // 1. Java 系统属性（aws.accessKeyId 和 aws.secretAccessKey） // 2.环境变量（AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY） // 3. 来自 AWS_WEB_IDENTITY_TOKEN_FILE 的 Web 身份令牌 // 4. 共享凭证和配置文件（~/.aws/credentials 和 ~/.aws/config） // 5. Amazon ECS 容器凭证 // 6. Amazon EC2 实例配置文件凭证 S3Client s3Client = S3Client.builder() .region(区域.US_EAST_1) .build(); // 使用默认的凭证提供者链 ### 显式凭证提供者导入 software.amazon.awssdk.auth.credentials.*; // 环境变量 CredentialsProvider envCredentials = EnvironmentVariableCredentialsProvider.create(); // 来自 ~/.aws/credentials 的配置文件 CredentialsProvider profileCredentials = ProfileCredentialsProvider.create("myprofile"); // 静态凭证（不建议用于生产） CredentialsProvider staticCredentials = StaticCredentialsProvider.create( AwsBasicCredentials.create("accessKeyId", "secretAccessKey") ）； // 实例配置文件（适用于 EC2） CredentialsProvider instanceProfileCredentials = InstanceProfileCredentialsProvider.create(); // 与客户端一起使用 S3Client s3Client = S3Client.builder() .region(区域.US_EAST_1) .credentialsProvider(profileCredentials) .build(); ### SSO 身份验证设置 # ~/.aws/config [默认] sso_session = 我的 sso sso_account_id = 111122223333 sso_role_name = 示例角色区域 = us-east-1 输出=json [sso-会话我的-sso] sso_region = us-east-1 sso_start_url = https://provided-domain.awsapps.com/start sso_registration_scopes = sso:帐户:访问权限 # 运行应用程序之前登录 aws 单点登录 # 验证活动会话 aws sts 获取调用者身份 ## HTTP 客户端配置 ### Apache HTTP 客户端（推荐用于同步）导入 software.amazon.awssdk.http.apache.ApacheHttpClient; ApacheHttpClient httpClient = ApacheHttpClient.builder() .maxConnections(100) .connectionTimeout(Duration.ofSeconds(5)) .socketTimeout(持续时间.ofSeconds(30)) .connectionTimeToLive(持续时间.ofMinutes(5)) .expectContinueEnabled(true) .build(); S3Client s3Client = S3Client.builder() .httpClient(httpClient) .build(); ### Netty HTTP 客户端（用于异步操作）导入 software.amazon.awssdk.http.nio.netty.NettyNioAsyncHttpClient; 导入 software.amazon.awssdk.http.nio.netty.SslProvider； NettyNioAsyncHttpClient httpClient = NettyNioAsyncHttpClient.builder() .最大并发数(100) .connectionTimeout(Duration.ofSeconds(5)) .readTimeout(持续时间.ofSeconds(30)) .writeTimeout(持续时间.ofSeconds(30)) .sslProvider(SslProvider.OPENSSL) // 比 JDK 更好的性能 .build(); S3AsyncClient s3AsyncClient = S3AsyncClient.builder() .httpClient(httpClient) .build(); ### URL 连接 HTTP 客户端（轻量级）导入 software.amazon.awssdk.http.urlconnection.UrlConnectionHttpClient; UrlConnectionHttpClient httpClient = UrlConnectionHttpClient.builder() .socketTimeout(持续时间.ofSeconds(30)) .build(); ## 最佳实践 ### 1\.重用服务客户端 **做：** @服务公共类S3Service { 私有最终S3Client s3Client；公共 S3Service() { this.s3Client = S3Client.builder() .region(区域.US_EAST_1) .build(); } // 重用 s3Client 进行所有操作 } **不要：** 公共无效uploadFile（字符串桶，字符串键）{ // 每次创建新客户端 - 浪费资源！ S3Client s3 = S3Client.builder().build(); s3.putObject(...); s3.close(); } ### 2\.配置 API 超时 S3Client s3Client = S3Client.builder() .overrideConfiguration(b -> b .apiCallTimeout(持续时间.ofSeconds(30)) .apiCallAttemptTimeout(Duration.ofMillis(5000))) .build(); ### 3\.关闭未使用的客户端 // 尝试使用资源尝试 (S3Client s3 = S3Client.builder().build()) { s3.listBuckets(); } // 显式关闭 S3Client s3Client = S3Client.builder().build(); 尝试{ s3Client.listBuckets(); }最后{ s3Client.close(); } ### 4\.关闭流媒体响应尝试 (ResponseInputStream s3Object = s3Client.getObject(GetObjectRequest.builder() .bucket（桶） .key(键) .build())) { // 立即读取并处理流 byte[] 数据 = s3Object.readAllBytes(); } // 流自动关闭，连接返回池 ### 5\.为异步客户端优化 SSL **添加依赖：** <依赖关系> io.netty netty-tcnative-boringssl-static <版本>2.0.61.最终版 <范围>运行时 **配置 SSL：** NettyNioAsyncHttpClient httpClient = NettyNioAsyncHttpClient.builder() .sslProvider(SslProvider.OPENSSL) .build(); S3AsyncClient s3AsyncClient = S3AsyncClient.builder() .httpClient(httpClient) .build(); ## Spring Boot 集成 ### 配置属性 @ConfigurationProperties（前缀=“aws”）公共记录 AwsProperties( 字符串区域，字符串 accessKeyId, 字符串秘密访问密钥， S3属性 s3, DynamoDb属性 dynamoDb ）{ 公共记录 S3Properties( 整数最大连接数，整数连接超时秒，整数 apiCallTimeoutSeconds ）{} 公共记录 DynamoDbProperties( 整数最大连接数，整数读取超时秒数）{} } ### 客户端配置 Bean @配置 @EnableConfigurationProperties(AwsProperties.class) 公共类 AwsClientConfiguration { 私有最终 AwsProperties awsProperties; 公共 AwsClientConfiguration(AwsProperties awsProperties) { this.awsProperties = awsProperties; } @豆子公共 S3Client s3Client() { 返回 S3Client.builder() .region(Region.of(awsProperties.region())) .credentialsProvider(credentialsProvider()) .overrideConfiguration(clientOverrideConfiguration( awsProperties.s3().apiCallTimeoutSeconds())) .httpClient(apacheHttpClient( awsProperties.s3().maxConnections(), awsProperties.s3().connectionTimeoutSeconds())) .build(); } 私人凭证提供者凭证提供者（）{ if (awsProperties.accessKeyId() != null && awsProperties.secretAccessKey() != null) { 返回 StaticCredentialsProvider.create( AwsBasicCredentials.create( awsProperties.accessKeyId(), awsProperties.secretAccessKey())); } 返回 DefaultCredentialsProvider.create(); } 私人 ClientOverrideConfiguration clientOverrideConfiguration( 整数 apiCallTimeoutSeconds) { 返回 ClientOverrideConfiguration.builder() .apiCallTimeout(持续时间.ofSeconds( apiCallTimeoutSeconds！= null ？ apiCallTimeoutSeconds : 30)) .apiCallAttemptTimeout(Duration.ofSeconds(10)) .build(); } 私有 ApacheHttpClient apacheHttpClient( 整数最大连接数，整数连接超时秒) { 返回 ApacheHttpClient.builder() .maxConnections(maxConnections!= null ? maxConnections: 50) .connectionTimeout(持续时间.ofSeconds( 连接超时秒！= null ？连接超时秒：5)) .socketTimeout(持续时间.ofSeconds(30)) .build(); } } ### 应用程序属性亚马逊：区域：us-east-1 s3：最大连接数：100 连接超时秒数：5 api 调用超时秒数：30 发电机数据库：最大连接数：50 读取超时秒数：30 ## 错误处理导入 software.amazon.awssdk.services.s3.model.S3Exception; 导入 software.amazon.awssdk.core.exception.SdkClientException; 导入 software.amazon.awssdk.core.exception.SdkServiceException; 尝试{ s3Client.getObject(请求); } catch (S3Exception e) { // 服务特定的异常 System.err.println("S3 错误：" + e.awsErrorDetails().errorMessage()); System.err.println("错误代码：" + e.awsErrorDetails().errorCode()); System.err.println("状态码：" + e.statusCode()); System.err.println("请求ID：" + e.requestId()); } catch (SdkServiceException e) { // 通用服务异常 System.err.println("AWS 服务错误：" + e.getMessage()); } catch (SdkClientException e) { // 客户端错误（网络、超时等） System.err.println("客户端错误：" + e.getMessage()); } ## 测试模式 ### LocalStack 集成 @测试配置公共类 LocalStackAwsConfig { @豆子公共 S3Client s3Client() { 返回 S3Client.builder() .region(区域.US_EAST_1) .endpointOverride(URI.create("http://localhost:4566")) .credentialsProvider(StaticCredentialsProvider.create( AwsBasicCredentials.create("测试", "测试"))) .build(); } } ### 使用 LocalStack 测试容器 @测试容器 @SpringBootTest 类 S3IntegrationTest { @容器静态 LocalStackContainer localstack = 新的 LocalStackContainer( DockerImageName.parse("localstack/localstack:3.0")) .withServices(LocalStackContainer.Service.S3); @DynamicPropertySource 静态无效 overrideProperties（DynamicPropertyRegistry 注册表）{ registry.add("aws.s3.endpoint", () -> localstack.getEndpointOverride(LocalStackContainer.Service.S3)); registry.add("aws.region", () -> localstack.getRegion()); registry.add("aws.access-key-id", localstack::getAccessKey); registry.add("aws.secret-access-key", localstack::getSecretKey); } } ## Maven 依赖项 <依赖管理> <依赖关系> <依赖关系> software.amazon.awssdk bom 2.25.0 // 使用最新的稳定版本 <类型>pom <范围>导入 <依赖关系> <依赖关系> software.amazon.awssdk sdk-core <依赖关系> software.amazon.awssdk apache-client <依赖关系> software.amazon.awssdk netty-nio-client <依赖关系> software.amazon.awssdk url-连接-客户端 <依赖关系> software.amazon.awssdk cloudwatch-metric-publisher <依赖关系> io.netty netty-tcnative-boringssl-static <版本>2.0.61.最终版 <范围>运行时 ## Gradle 依赖关系依赖项{ 实施平台('software.amazon.awssdk:bom:2.25.0') 实施“software.amazon.awssdk:sdk-core” 实施“software.amazon.awssdk：apache-client” 实施“software.amazon.awssdk：netty-nio-client” 实施“software.amazon.awssdk：cloudwatch-metric-publisher” runtimeOnly 'io.netty:netty-tcnative-boringssl-static:2.0.61.Final' } ## 示例 ### 示例 1：带有错误处理的基本 S3 上传导入 software.amazon.awssdk.core.sync.RequestBody; 导入软件.amazon.awssdk.services.s3.model.*; 公共类S3UploadService { 私有最终S3Client s3Client；公共无效uploadFile（字符串桶，字符串键，字节[]内容）{ 尝试{ PutObjectRequest 请求 = PutObjectRequest.builder() .bucket（桶） .key(键) .build(); s3Client.putObject(请求, RequestBody.fromBytes(内容)); } catch (S3Exception e) { if (e.statusCode() == 404) { throw new RuntimeException("未找到存储桶：" + bucket, e); } throw new RuntimeException("上传失败", e); } } } ### 示例 2：带分页的 DynamoDB 查询导入 software.amazon.awssdk.services.dynamodb.model.*; public List queryDynamoDB(DynamoDbClient client, String tableName) { QueryRequest 请求 = QueryRequest.builder() .表名(表名) .keyConditionExpression("pk = :pk") .expressionAttributeValues(Map.of(":pk", AttributeValue.builder().s("user#123").build())) .build(); List allItems = new ArrayList<>(); for (Page 页面: client.queryPaginator(request).stream()) { allItems.addAll(page.items()); } 返回所有项目； } ### 示例 3：Spring Boot 配置 @配置公共类 AwsConfiguration { @豆子公共 S3Client s3Client(AwsProperties 属性) { 返回 S3Client.builder() .region(Region.of(properties.getRegion())) .credentialsProvider（credentialsProvider（属性）） .overrideConfiguration(ClientOverrideConfiguration.builder() .apiCallTimeout(持续时间.ofSeconds(30)) .build()) .build(); } 私有CredentialsProvider凭据提供程序（AwsProperties属性）{ if (properties.getAccessKeyId() != null) { 返回 StaticCredentialsProvider.create( AwsBasicCredentials.create( 属性.getAccessKeyId(), 属性.getSecretAccessKey())); } 返回 DefaultCredentialsProvider.create(); } } ## 基本 S3 上传导入 software.amazon.awssdk.core.sync.RequestBody; 导入 software.amazon.awssdk.services.s3.model.PutObjectRequest; 尝试 (S3Client s3 = S3Client.builder().region(Region.US_EAST_1).build()) { PutObjectRequest 请求 = PutObjectRequest.builder() .bucket("我的桶") .key("上传/文件.txt") .build(); s3.putObject(request, RequestBody.fromString("你好，世界！")); } ### S3 分页列表对象导入 software.amazon.awssdk.services.s3.model.ListObjectsV2Request; 导入 software.amazon.awssdk.services.s3.model.ListObjectsV2Response; 尝试 (S3Client s3 = S3Client.builder().region(Region.US_EAST_1).build()) { ListObjectsV2Request 请求 = ListObjectsV2Request.builder() .bucket("我的桶") .build(); ListObjectsV2Response 响应 = s3.listObjectsV2(请求); response.contents().forEach(对象 -> { System.out.println("对象键：" + object.key()); }); } ### 异步 S3 上传导入 software.amazon.awssdk.core.async.AsyncRequestBody; 导入 software.amazon.awssdk.services.s3.model.PutObjectRequest; S3AsyncClient s3AsyncClient = S3AsyncClient.builder().build(); PutObjectRequest 请求 = PutObjectRequest.builder() .bucket("我的桶") .key("异步上传.txt") .build(); CompletableFuture future = s3AsyncClient.putObject( request, Async.fromString("你好，异步世界！")); future.thenAccept(响应 -> { System.out.println("上传完成：" + response.eTag()); }).异常(错误-> { System.err.println("上传失败：" + error.getMessage()); 返回空值； }); ## 性能考虑因素 1. **连接池** ：默认最大连接数为 50。针对高吞吐量应用程序增加连接数。 2. **超时**：始终设置`apiCallTimeout`和`apiCallAttemptTimeout`。 3. **客户端重用**：创建客户端一次，在整个应用程序生命周期中重用。 4. **流处理**：立即关闭流以防止连接池耗尽。 5. **I/O 异步**：使用异步客户端进行 I/O 绑定操作。 6. **OpenSSL** ：将 OpenSSL 与 Netty 结合使用以获得更好的 SSL 性能。 7. **指标**：启用 CloudWatch 指标来监控性能。 ## 安全最佳实践 1. **切勿对凭据进行硬编码**：使用凭据提供程序或环境变量。 2. **使用 IAM 角色**：如果可能，优先使用 IAM 角色而不是访问密钥。 3. **轮换凭证**：对长期密钥实施凭证轮换。 4. **最小权限**：授予所需的最低权限。 5. **启用 SSL**：始终使用 HTTPS 端点（默认）。 6. **审核日志记录**：启用 AWS CloudTrail 进行 API 调用审核。 ## 相关技能 * `aws-sdk-java-v2-s3` \- S3 特定模式和示例 * `aws-sdk-java-v2-dynamodb` \- DynamoDB 模式和示例 * `aws-sdk-java-v2-lambda` \- Lambda 模式和示例 ## 参考文献有关详细文档，请参阅 [references/]()： * [开发人员指南]() \- 综合指南和架构概述 * [API 参考]() \- 核心类的完整 API 文档 * [最佳实践]() \- 深入的最佳实践和配置示例 ## 其他资源 * [AWS SDK for Java 2.x 开发人员指南]() * [AWS SDK for Java 2.x API 参考]() * [最佳实践]() * [GitHub 存储库]() ## 限制和警告 * 切勿在源代码中硬编码凭证；使用凭据提供程序或环境变量。 * 服务客户端是线程安全的，应该重用；不要为每个请求创建新客户端。 * 始终关闭流响应（`ResponseInputStream`）以防止连接池耗尽。 * 设置适当的超时，防止挂起请求；默认超时可能不适合所有用例。 * 了解AWS服务速率限制；实施指数退避重试。 * IAM角色应遵循最小权限原则；避免使用过于宽松的政策。 * 异步客户端需要适当的事件循环管理；确保有足够的线程并发。 * LocalStack并未实现所有AWS服务；验证集成测试的兼容性。 * SDK指标会影响性能；如果不需要，请在生产中禁用。

AWS SDK Java V2 核心

包含技能