適用於 Java 的 AWS SDK 遷移工具

適用於 Java 的 AWS SDK 提供遷移工具，可協助自動將適用於 Java 的 SDK 1.x (V1) 程式碼遷移至 2.x (V2)。此工具使用開放原始碼、原始程式碼重構工具 OpenRewrite 來執行遷移。OpenRewrite 使用程式碼修改規則（稱為「配方」)，將您的原始程式碼從 V1 自動更新為 V2 語法和模式。

此工具支援 SDK 服務用戶端和 S3 Transfer Manager 高階程式庫的程式碼修改規則。不支援其他高階 APIs的程式碼修改規則，例如 V1 DynamoDBMapper到 V2 的 DynamoDB 增強型用戶端 API。

如需限制的詳細資訊，請參閱此頁面的結尾。如需手動遷移步驟的常見不支援程式碼模式的詳細範例，請參閱不支援的程式碼模式。

使用遷移工具

遷移 Maven 專案

請依照下列指示，使用 OpenRewrite Maven 外掛程式工具遷移適用於 Java 的 SDK 1.x Maven 型專案。

導覽至 Maven 專案的根目錄

開啟終端機（命令列）視窗，然後導覽至 Maven 型應用程式的根目錄。

執行外掛程式的rewrite-maven-plugin命令

您可以選擇兩種模式 (Maven 目標）： dryRun和 run。

dryRun 模式

在 dryRun模式中，外掛程式會在主控台輸出中產生 diff 日誌，並在 target/rewrite 資料夾中產生名為 rewrite.patch的修補程式檔案。此模式可讓您預覽將要進行的變更，因為原始程式碼檔案不會進行任何變更。

下列範例示範如何在 dryRun 模式中叫用外掛程式。


mvn org.openrewrite.maven:rewrite-maven-plugin:<rewrite-plugin-version>*:dryRun \
  -Drewrite.recipeArtifactCoordinates=software.amazon.awssdk:v2-migration:<sdkversion>** \
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2

*將 <rewrite-plugin-version> 取代為您在此測試檔案中看到rewriteMavenPluginVersion的值。

**以 2.x SDK 版本取代 <sdkversion>。請造訪 Maven Central 以檢查是否有最新版本。

重要

請務必使用測試檔案中rewrite-maven-plugin顯示的版本，因為其他版本可能無法運作。

來自 dryRun 模式的主控台輸出應該類似下列輸出。


[WARNING] These recipes would make changes to project/src/test/resources/maven/before/pom.xml:
[WARNING]     software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2
[WARNING]         software.amazon.awssdk.v2migration.UpgradeSdkDependencies
[WARNING]             org.openrewrite.java.dependencies.AddDependency: {groupId=software.amazon.awssdk, artifactId=apache-client, version=2.27.0, onlyIfUsing=com.amazonaws.ClientConfiguration}
[WARNING]             org.openrewrite.java.dependencies.AddDependency: {groupId=software.amazon.awssdk, artifactId=netty-nio-client, version=2.27.0, onlyIfUsing=com.amazonaws.ClientConfiguration}
[WARNING]             org.openrewrite.java.dependencies.ChangeDependency: {oldGroupId=com.amazonaws, oldArtifactId=aws-java-sdk-bom, newGroupId=software.amazon.awssdk, newArtifactId=bom, newVersion=2.27.0}
[WARNING]             org.openrewrite.java.dependencies.ChangeDependency: {oldGroupId=com.amazonaws, oldArtifactId=aws-java-sdk-s3, newGroupId=software.amazon.awssdk, newArtifactId=s3, newVersion=2.27.0}
[WARNING]             org.openrewrite.java.dependencies.ChangeDependency: {oldGroupId=com.amazonaws, oldArtifactId=aws-java-sdk-sqs, newGroupId=software.amazon.awssdk, newArtifactId=sqs, newVersion=2.27.0}
[WARNING] These recipes would make changes to project/src/test/resources/maven/before/src/main/java/foo/bar/Application.java:
[WARNING]     software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2
[WARNING]         software.amazon.awssdk.v2migration.S3GetObjectConstructorToFluent
[WARNING]             software.amazon.awssdk.v2migration.ConstructorToFluent
[WARNING]         software.amazon.awssdk.v2migration.S3StreamingResponseToV2
[WARNING]         software.amazon.awssdk.v2migration.ChangeSdkType
[WARNING]         software.amazon.awssdk.v2migration.ChangeSdkCoreTypes
[WARNING]             software.amazon.awssdk.v2migration.ChangeExceptionTypes
[WARNING]                 org.openrewrite.java.ChangeType: {oldFullyQualifiedTypeName=com.amazonaws.AmazonClientException, newFullyQualifiedTypeName=software.amazon.awssdk.core.exception.SdkException}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getRequestId(), newMethodName=requestId}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getErrorCode(), newMethodName=awsErrorDetails().errorCode}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getServiceName(), newMethodName=awsErrorDetails().serviceName}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getErrorMessage(), newMethodName=awsErrorDetails().errorMessage}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getRawResponse(), newMethodName=awsErrorDetails().rawResponse().asByteArray}
[WARNING]                 org.openrewrite.java.ChangeMethodName: {methodPattern=com.amazonaws.AmazonServiceException getRawResponseContent(), newMethodName=awsErrorDetails().rawResponse().asUtf8String}
[WARNING]                 org.openrewrite.java.ChangeType: {oldFullyQualifiedTypeName=com.amazonaws.AmazonServiceException, newFullyQualifiedTypeName=software.amazon.awssdk.awscore.exception.AwsServiceException}
[WARNING]         software.amazon.awssdk.v2migration.NewClassToBuilderPattern
[WARNING]             software.amazon.awssdk.v2migration.NewClassToBuilder
[WARNING]             software.amazon.awssdk.v2migration.V1SetterToV2
[WARNING]         software.amazon.awssdk.v2migration.V1GetterToV2
...
[WARNING]         software.amazon.awssdk.v2migration.V1BuilderVariationsToV2Builder
[WARNING]         software.amazon.awssdk.v2migration.NewClassToBuilderPattern
[WARNING]             software.amazon.awssdk.v2migration.NewClassToBuilder
[WARNING]             software.amazon.awssdk.v2migration.V1SetterToV2
[WARNING]         software.amazon.awssdk.v2migration.HttpSettingsToHttpClient
[WARNING]         software.amazon.awssdk.v2migration.WrapSdkClientBuilderRegionStr
[WARNING] Patch file available:
[WARNING]     project/src/test/resources/maven/before/target/rewrite/rewrite.patch
[WARNING] Estimate time saved: 20m
[WARNING] Run 'mvn rewrite:run' to apply the recipes.

run 模式

當您在 run 模式下執行外掛程式時，它會修改磁碟上的原始碼以套用變更。執行命令之前，請確定您有原始程式碼的備份。

下列範例示範如何在 run 模式中叫用外掛程式。


mvn org.openrewrite.maven:rewrite-maven-plugin:<rewrite-plugin-version>*:run \
  -Drewrite.recipeArtifactCoordinates=software.amazon.awssdk:v2-migration:<sdkversion>** \
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2

*將 <rewrite-plugin-version> 取代為您在此測試檔案中看到rewriteMavenPluginVersionvalue的。

**將 <sdkversion> 取代為 2.x SDK 版本。請造訪 Maven Central 以檢查是否有最新版本。

執行命令後，編譯您的應用程式並執行測試以驗證變更。

遷移 Gradle 專案

請依照下列指示，使用 OpenRewrite Gradle 外掛程式工具遷移適用於 Java 的 SDK 1.x Gradle 型專案。

導覽至 Gradle 專案的根目錄

開啟終端機（命令列）視窗，然後導覽至 Gradle 型應用程式的根目錄。

建立 Gradle init 指令碼

在目錄中建立具有下列內容init.gradle的檔案。


initscript {
    repositories {
        maven { url "https://plugins.gradle.org/m2" }
    }
    dependencies {
        classpath("org.openrewrite:plugin:<rewrite-plugin-version>*")
    }
}

rootProject {
    plugins.apply(org.openrewrite.gradle.RewritePlugin)
    dependencies {
        rewrite("software.amazon.awssdk:v2-migration:latest.release")
    }

    afterEvaluate {
        if (repositories.isEmpty()) {
            repositories {
                mavenCentral()
            }
        }
    }
}

*將 <rewrite-plugin-version> 取代為您在此測試檔案中看到的版本。

執行 rewrite命令

如同 Maven 外掛程式，您可以在 dryRun或 run 模式中執行 Gradle 外掛程式。

dryRun 模式

下列範例示範如何在 dryRun 模式中叫用外掛程式。
```
gradle rewriteDryRun --init-script init.gradle \
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2
```
run 模式

下列範例示範如何在 run 模式中叫用外掛程式。
```
gradle rewriteRun --init-script init.gradle \
  -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2
```

目前限制

雖然遷移透過更新至 V2 對等的程式碼修改規則來升級大多數 V1 程式碼，但某些類別和方法不會涵蓋在內。 V2 對於這些類別和方法，請依照step-by-step指示手動遷移您的程式碼。

對於某些不支援的程式碼修改規則，遷移工具可能會新增以下列開頭的註解：


/*AWS SDK for Java v2 migration: Transform for ...

在註解之後，工具會輸出方法或類別的 V2 版本一般 Stub。例如，在下列輸出中，遷移工具嘗試遷移 V1 S3 用戶端setBucketLifecycleConfiguration的方法：


/*AWS SDK for Java v2 migration: Transform for setBucketLifecycleConfiguration method not supported. 
Please manually migrate your code by using builder pattern, update from BucketLifecycleConfiguration.Rule 
to LifecycleRule, StorageClass to TransitionStorageClass, and adjust imports and names.*/
s3.putBucketLifecycleConfiguration(
        PutBucketLifecycleConfigurationRequest.builder()
            .bucket(bucketName)
            .lifecycleConfiguration(BucketLifecycleConfiguration.builder()
                .build())
            .build());

下方清單中的連結會帶您前往遷移資訊，以協助您手動遷移程式碼。

第 1 版和第 2 版之間的 S3 用戶端差異適用於 Java 的 AWS SDK
S3 Transfer Manager (TransferManager)
DynamoDB 物件映射 (DynamoDBMapper)
EC2 中繼資料公用程式 (EC2MetadataUtils)
等待程式 (AmazonDynamoDBWaiters)
IAM 政策建置器（政策）
CloudFront 預先簽署 (CloudFrontUrlSigner、CloudFrontCookieSigner)
S3 事件通知 (S3EventNotification)
SDK 指標發佈 (1.x 文件、2.x 文件)
不支援的程式碼模式 – 需要手動遷移的常見程式碼模式的詳細範例

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

如何遷移

不支援的程式碼模式