aws-sdk-java-v2-core

AWS SDK for Java 2.x 核心模式

概述

使用此技能，以适用于生产环境的安全默认值配置 AWS SDK for Java 2.x 客户端。

重点关注以下关键决策：

• 如何解析凭证和区域
• 如何配置同步和异步 HTTP 客户端
• 如何应用超时、重试、生命周期管理和测试

让 SKILL.md 专注于设置和交付流程。更深入的 API 详情和扩展示例请参阅 references/ 文件。

适用场景

• 创建或强化 AWS SDK for Java 2.x 服务客户端
• 配置用于 AWS 集成的 Spring Boot Bean
• 排查身份验证、区域或凭证问题
• 在同步（S3Client、DynamoDbClient）和异步（S3AsyncClient、SqsAsyncClient）客户端之间进行选择

说明

1. 选择服务客户端类型

• 同步客户端（S3Client、DynamoDbClient）适用于请求/响应流程
• 异步客户端（S3AsyncClient、SqsAsyncClient）适用于并发、流式处理或背压场景
• 每个服务和配置配置文件复用一个客户端

2. 配置凭证和区域解析

使用 DefaultCredentialsProvider，并采用适应环境的默认设置：

• 本地开发：共享 AWS 配置、SSO 或环境变量
• CI/CD：Web 身份或注入的环境变量
• AWS 运行环境：ECS 任务角色、EKS IRSA 或 EC2 实例配置文件

仅在多账户访问、测试隔离或切换配置文件时覆盖默认设置。

验证：启动时调用 StsClient.getCallerIdentity()，确认凭证已解析。

3. 配置 HTTP 客户端、超时和重试

明确设置适用于生产环境的值：

• API 调用超时和单次尝试超时
• 连接超时以及最大连接数或并发数
• 与服务配额和幂等性相匹配的重试策略

同步使用 ApacheHttpClient，异步使用 NettyNioAsyncHttpClient。

验证：在故障条件下确认超时和重试行为。

4. 将客户端配置为应用级依赖项

在 Spring Boot 中：

• 将客户端作为 @Bean 单例公开
• 通过构造函数注入
• 将凭证和区域保存在配置文件中

验证：检查客户端不会在高频执行路径中创建。

如果生命周期未自动管理，请在关闭时关闭自定义 HTTP 客户端和 SDK 客户端。

5. 在集成边界处理故障

在边界层：

• 捕获 SdkException 或特定服务的异常
• 区分可重试故障与身份验证、配额和验证故障
• 记录请求上下文，但绝不记录机密或原始凭证

6. 发布前运行集成测试

• 在目标环境中验证区域和调用者身份
• 使用 LocalStack、Testcontainers 或沙盒账户运行测试
• 在 Spring Boot 配置中使用 @PostConstruct，在启动时因缺少凭证而快速失败

StsClient stsClient = StsClient.builder().build();
GetCallerIdentityResponse identity = stsClient.getCallerIdentity();
// Logs: Successfully authenticated as: {identity.arn()}

示例

示例 1：显式设置 HTTP 和超时参数的 Spring Boot 同步客户端

@Configuration
public class AwsClientConfiguration {

    @Bean
    S3Client s3Client() {
        return S3Client.builder()
            .region(Region.of("eu-south-2"))
            .credentialsProvider(DefaultCredentialsProvider.create())
            .httpClientBuilder(ApacheHttpClient.builder()
                .maxConnections(100)
                .connectionTimeout(Duration.ofSeconds(3)))
            .overrideConfiguration(ClientOverrideConfiguration.builder()
                .apiCallAttemptTimeout(Duration.ofSeconds(10))
                .apiCallTimeout(Duration.ofSeconds(30))
                .build())
            .build();
    }
}

示例 2：适用于高并发工作负载的异步客户端

SqsAsyncClient sqsAsyncClient = SqsAsyncClient.builder()
    .region(Region.US_EAST_1)
    .credentialsProvider(DefaultCredentialsProvider.create())
    .httpClientBuilder(NettyNioAsyncHttpClient.builder()
        .maxConcurrency(200)
        .connectionTimeout(Duration.ofSeconds(3))
        .readTimeout(Duration.ofSeconds(20)))
    .overrideConfiguration(ClientOverrideConfiguration.builder()
        .apiCallTimeout(Duration.ofSeconds(30))
        .build())
    .build();

最佳实践

• 除非项目要求另有规定，否则默认使用 DefaultCredentialsProvider。
• 对服务端服务明确选择区域。
• 复用 SDK 客户端，而不是按请求创建客户端。
• 调整重试策略时考虑服务配额和幂等性。
• 在 SDK 之上进行业务映射，而不是在控制器内部进行。
• 让集成测试靠近创建客户端的配置。
• 将深入的特定服务示例移至 S3、DynamoDB、Bedrock 或 Secrets Manager 等专用技能。

限制与警告

• 不要在源代码、示例或配置文件中嵌入访问密钥或会话令牌。
• 静态凭证仅适用于范围严格受限的本地测试。
• 缺少区域或凭证解析无效的问题通常要到首次调用时才会失败，因此请明确验证启动时的各项假设。
• 异步客户端需要管理底层 HTTP 资源的生命周期。
• 过多重试可能会加剧限流并增加延迟。
• 代理、TLS 和指标发布器 API 可能因所选 HTTP 堆栈和 SDK 版本而异；请根据项目中已使用的版本调整示例。

参考资料

• references/api-reference.md
• references/best-practices.md
• references/developer-guide.md

相关技能

• aws-sdk-java-v2-secrets-manager
• aws-sdk-java-v2-s3
• aws-sdk-java-v2-dynamodb
• aws-sdk-java-v2-bedrock