aws-sdk-java-v2-core 是做什麼的？
提供 AWS SDK for Java 2.x 的用戶端設定、憑證解析、HTTP 用戶端調校、超時、重試與測試模式。適用於建立或強化 AWS 服務用戶端、配置 Spring Boot Bean、除錯驗證或區域問題，或選擇同步與非同步 SDK 使用方式。
總覽
此技能涵蓋以下核心領域：
- 用戶端建立：使用
SdkClientBuilder和SdkDefaultClientBuilder建立服務用戶端。 - 憑證解析：設定
CredentialsProvider鏈（env、system 屬性、profile、ECS/EC2 中繼資料）。 - 區域解析：設定
Region（使用Region.of()或DefaultRegionProvider）。 - HTTP 用戶端調校：選擇 Apache 或 Netty HTTP 用戶端，並調校連線、超時、閒置連線管理等。
- 重試與逾時：設定
RetryPolicy（自訂退避、節流重試）與ApiCallTimeout。 - 同步 vs 非同步：選擇
SyncClient或AsyncClient的考量與實作細節。 - Spring Boot 整合：將 AWS 用戶端注入為
@Bean並使用@ConfigurationProperties。 - 測試：使用
Mockito模擬用戶端、使用WireMock模擬 HTTP 端點、使用AmazonS3Client的本機測試模式。
使用方式
建立 S3 用戶端（同步）
S3Client s3 = S3Client.builder()
.region(Region.of("us-west-2"))
.credentialsProvider(DefaultCredentialsProvider.create())
.httpClient(ApacheHttpClient.builder()
.maxConnections(50)
.socketTimeout(Duration.ofSeconds(10))
.build())
.overrideConfiguration(b -> b
.retryPolicy(RetryPolicy.builder()
.numRetries(3)
.backoffStrategy(ExponentialBackoffRetryStrategy.builder()
.baseDelay(Duration.ofMillis(200))
.maxBackoffTime(Duration.ofSeconds(20))
.build())
.build())
.apiCallTimeout(Duration.ofSeconds(30)))
.build();
使用 Spring Boot 配置
@Configuration
public class AwsConfig {
@Bean
public S3Client s3Client(
@Value("${aws.region:us-east-1}") String region,
@Value("${aws.s3.endpoint-override:#{null}}") String endpointOverride) {
var builder = S3Client.builder()
.region(Region.of(region))
.credentialsProvider(DefaultCredentialsProvider.create());
if (endpointOverride != null && !endpointOverride.isEmpty()) {
builder.endpointOverride(URI.create(endpointOverride));
}
return builder.build();
}
}
設定 application.yml
aws:
region: eu-west-1
s3:
endpoint-override: http://localhost:4566
常見問題與解決方案
| 問題 | 解決方案 |
|---|---|
CredentialsProviderException | 確認 AWS 憑證已透過環境變數 (AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY) 或 IAM 角色設定。 |
SocketTimeoutException | 增加 socketTimeout（預設 10 秒）或 apiCallTimeout（預設 30 秒）。 |
| 請求限制 (Throttling) | 啟用重試並使用指數退避策略。 |
| 區域不符 | 明確設定 Region 或在環境變數 AWS_REGION 中指定。 |
| 非同步用戶端記憶體不足 | 使用 EventLoopGroup 並限制並行請求數（使用 Semaphore）。 |
最佳實踐
- 重複使用用戶端：將 AWS 用戶端建立為單例或 Spring Bean，避免重複建立。
- 設定明確的超時：總是設定
socketTimeout與apiCallTimeout。 - 選擇適當的 HTTP 用戶端：同步使用
ApacheHttpClient，非同步使用NettyNioAsyncHttpClient（或AwsCrtAsyncHttpClient以獲得最佳效能）。 - 使用非同步編程：對於高吞吐量或連線數多的場景，選擇非同步用戶端。
- 記錄與監控：啟用 SDK 層級記錄（設定
software.amazon.awssdk的日誌級別為DEBUG）。
支援的平台
- AWS Lambda（Java 執行環境）
- Amazon ECS / Fargate（使用 ECS 中繼資料端點取得憑證）
- Amazon EC2（使用 IMDS）
- 本機開發（透過環境變數或
~/.aws/credentials設定檔） - Spring Boot 應用程式