AWS SDK for Java 2.x コアパターン

概要

このスキルを使用して、AWS SDK for Java 2.x クライアントを本番環境対応のデフォルト設定でセットアップします。

以下の重要な判断に焦点を当てます：

• 認証情報とリージョンがどのように解決されるか
• 同期および非同期 HTTP クライアントの設定方法
• タイムアウト、リトライ、ライフサイクル管理、テストの適用方法

SKILL.md はセットアップと配信フローに焦点を当てます。より詳しい API 詳細と拡張例については references/ ファイルを参照してください。

いつ使用するか

• AWS SDK for Java 2.x サービスクライアントを作成または強化するとき
• Spring Boot Bean を AWS 統合用に配線するとき
• 認証、リージョン、または認証情報の問題をデバッグするとき
• 同期クライアント（S3Client、DynamoDbClient）と非同期クライアント（S3AsyncClient、SqsAsyncClient）のどちらを使用するか選択するとき

指示

1. サービスクライアントのタイプを選択する

• リクエスト/レスポンスフローの場合は同期クライアント（S3Client、DynamoDbClient）
• 同時実行、ストリーミング、またはバックプレッシャーの場合は非同期クライアント（S3AsyncClient、SqsAsyncClient）
• サービスおよび設定プロファイルごとに 1 つのクライアントを再利用します

2. 認証情報とリージョン解決を設定する

環境対応のデフォルト設定で DefaultCredentialsProvider を使用します：

• ローカル開発：共有 AWS 設定、SSO、または環境変数
• CI/CD：Web ID またはインジェクトされた環境変数
• AWS ランタイム：ECS タスクロール、EKS IRSA、または EC2 インスタンスプロファイル

マルチアカウントアクセス、テスト分離、またはプロファイル切り替えの場合のみオーバーライドします。

確認：スタートアップ時に StsClient.getCallerIdentity() を呼び出して、認証情報が解決されることを確認します。

3. HTTP クライアント、タイムアウト、リトライを設定する

本番値を明示的に設定します：

• API 呼び出しタイムアウトと試行タイムアウト
• 接続タイムアウトと最大接続数または同時実行数
• サービスクォータとべき等性に合わせたリトライ戦略

同期には ApacheHttpClient、非同期には NettyNioAsyncHttpClient を使用します。

確認：障害条件下でタイムアウトとリトライ動作を確認します。

4. クライアントをアプリケーションレベルの依存関係として配線する

Spring Boot では：

• クライアントを @Bean シングルトンとして公開する
• コンストラクタを通じて注入する
• 認証情報とリージョンを設定ファイルに保持する

確認：ホット実行パス内でクライアントが作成されていないことを確認します。

ライフサイクルが自動的に管理されない場合は、シャットダウン時にカスタム HTTP クライアントと SDK クライアントをクローズします。

5. 統合境界で障害を処理する

境界レイヤーで：

• SdkException またはサービス固有の例外をキャッチする
• 再試行可能な障害を認証、クォータ、検証障害から区別する
• リクエストコンテキストをログ出力し、シークレットまたはクレデンシャルをログ出力しない

6. 出荷前に統合テストを実行する

• ターゲット環境でリージョンと呼び出し元の ID を確認する
• 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