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）：並行処理、ストリーミング、バックプレッシャー向け
• サービスと設定プロファイルごとにクライアントを 1 つ再利用します

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

環境に応じたデフォルト設定で DefaultCredentialsProvider を使用します。

• ローカル開発：共有 AWS 設定、SSO、または環境変数
• CI/CD：ウェブ 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