本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 適用於 Java 的 AWS SDK 遷移工具 適用於 Java 的 AWS SDK 提供遷移工具，可協助自動將適用於 Java 的 SDK 1.x (V1) 程式碼遷移至 2.x (V2)。此工具使用開放原始碼、原始程式碼重構工具 [OpenRewrite](https://docs.openrewrite.org/) 來執行遷移。OpenRewrite 使用程式碼修改規則 （稱為「配方」)，將您的原始程式碼從 V1 自動更新為 V2 語法和模式。 此工具支援 SDK 服務用戶端和 [S3 Transfer Manager](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/s3/transfer/TransferManager.html) 高階程式庫的程式碼修改規則。不支援其他高階 APIs的程式碼修改規則，例如 V1 [https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html](https://docs.aws.amazon.com/AWSJavaSDK/latest/javadoc/com/amazonaws/services/dynamodbv2/datamodeling/DynamoDBMapper.html)到 V2 的 [DynamoDB 增強型用戶端 API](dynamodb-enhanced-client.md)。 如需限制的詳細資訊，請參閱[此頁面的結尾](#migration-tool-limitations)。如需手動遷移步驟的常見不支援程式碼模式的詳細範例，請參閱[不支援的程式碼模式](migration-tool-unsupported-patterns.md)。 ## 使用遷移工具 ### 遷移 Maven 專案 請依照下列指示，使用 [OpenRewrite Maven 外掛程式工具遷移適用於 Java 的 SDK 1.x Maven](https://docs.openrewrite.org/reference/rewrite-maven-plugin) 型專案。 1. 導覽至 Maven 專案的根目錄 開啟終端機 （命令列） 視窗，然後導覽至 Maven 型應用程式的根目錄。 1. 執行外掛程式的`rewrite-maven-plugin`命令 您可以選擇兩種模式 (Maven 目標）： `dryRun`和 `run`。 **`dryRun`**** 模式** 在 `dryRun`模式中，外掛程式會在主控台輸出中產生 diff 日誌，並在 `target/rewrite` 資料夾中產生名為 `rewrite.patch`的修補程式檔案。此模式可讓您預覽將要進行的變更，因為原始程式碼檔案不會進行任何變更。 下列範例示範如何在 `dryRun` 模式中叫用 外掛程式。 ``` mvn org.openrewrite.maven:rewrite-maven-plugin:{{*}}:dryRun \ -Drewrite.recipeArtifactCoordinates=software.amazon.awssdk:v2-migration:{{**}} \ -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2 ``` \*將 {{}} 取代為您在此[測試檔案中](https://github.com/aws/aws-sdk-java-v2/blob/3a01289246f1f4ac814a354051d00030e53ef968/test/v2-migration-tests/src/test/java/software/amazon/awssdk/v2migrationtests/MavenTestBase.java#L54)看到`rewriteMavenPluginVersion`的值。 \*\*以 2.x SDK 版本取代 {{}}。請造訪 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/v2-migration) 以檢查是否有最新版本。 **重要** 請務必使用[測試檔案中](https://github.com/aws/aws-sdk-java-v2/blob/3a01289246f1f4ac814a354051d00030e53ef968/test/v2-migration-tests/src/test/java/software/amazon/awssdk/v2migrationtests/MavenTestBase.java#L54)`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:{{*}}:run \ -Drewrite.recipeArtifactCoordinates=software.amazon.awssdk:v2-migration:{{**}} \ -Drewrite.activeRecipes=software.amazon.awssdk.v2migration.AwsSdkJavaV1ToV2 ``` \*將 {{}} 取代為您在此[測試檔案中](https://github.com/aws/aws-sdk-java-v2/blob/3a01289246f1f4ac814a354051d00030e53ef968/test/v2-migration-tests/src/test/java/software/amazon/awssdk/v2migrationtests/MavenTestBase.java#L54)看到`rewriteMavenPluginVersionvalue`的 。 \*\*將 {{}} 取代為 2.x SDK 版本。請造訪 [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/v2-migration) 以檢查是否有最新版本。 執行 命令後，編譯您的應用程式並執行測試以驗證變更。 ### 遷移 Gradle 專案 請依照下列指示，使用 [OpenRewrite Gradle 外掛程式工具遷移適用於 Java 的 SDK 1.x Gradle](https://docs.openrewrite.org/reference/gradle-plugin-configuration) 型專案。 1. 導覽至 Gradle 專案的根目錄 開啟終端機 （命令列） 視窗，然後導覽至 Gradle 型應用程式的根目錄。 1. 建立 Gradle init 指令碼 在 目錄中建立具有下列內容`init.gradle`的檔案。 ``` initscript { repositories { maven { url "https://plugins.gradle.org/m2" } } dependencies { classpath("org.openrewrite:plugin:{{*}}") } } rootProject { plugins.apply(org.openrewrite.gradle.RewritePlugin) dependencies { rewrite("software.amazon.awssdk:v2-migration:latest.release") } afterEvaluate { if (repositories.isEmpty()) { repositories { mavenCentral() } } } } ``` \*將 {{}} 取代為您在此[測試檔案中](https://github.com/aws/aws-sdk-java-v2/blob/master/test/v2-migration-tests/src/test/resources/software/amazon/awssdk/v2migrationtests/gradle/before/init.gradle#L6)看到的版本。 1. 執行 `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指示](migration-steps.md)手動遷移您的程式碼。 對於某些不支援的程式碼修改規則，遷移工具可能會新增以下列開頭的註解： ``` /*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](migration-s3-client.md) + [S3 Transfer Manager](migration-s3-transfer-manager.md) (TransferManager) + [DynamoDB 物件映射](migration-ddb-mapper.md) (DynamoDBMapper) + [EC2 中繼資料公用程式](migration-imds.md) (EC2MetadataUtils) + [等待程式](migration-waiters.md) (AmazonDynamoDBWaiters) + [IAM 政策建置器](migration-iam-policy-builder.md) （政策） + [CloudFront 預先簽署 ](migration-cloudfront-presigning.md)(CloudFrontUrlSigner、CloudFrontCookieSigner) + [S3 事件通知 ](migration-s3-event-notification.md)(S3EventNotification) + SDK 指標發佈 ([1.x 文件](https://docs.aws.amazon.com/sdk-for-java/v1/developer-guide/generating-sdk-metrics.html)、[2.x 文件](metrics.md)) + [不支援的程式碼模式](migration-tool-unsupported-patterns.md) – 需要手動遷移的常見程式碼模式的詳細範例