适用于 Java 的 Amazon SDK 迁移工具

适用于 Java 的 Amazon SDK 提供了一种迁移工具，可帮助自动将适用于 Java 的 SDK 1.x (V1) 代码迁移到 2.x (V2)。该工具使用OpenRewrite开源源代码重构工具来执行迁移。 OpenRewrite 使用代码修改规则（称为 “配方”）自动将源代码从 V1 更新为 V2 语法和模式。

该工具支持 SDK 服务客户端和 S 3 传输管理器高级库的代码修改规则。不支持其他高级版本（ APIs 例如 V1 DynamoDBMapper到 V2 的 Dynamo DB 增强型客户端 API）的代码修改规则。

有关限制的更多详细信息，请参阅本页末尾。有关带有手动迁移步骤的不支持的常见代码模式的详细示例，请参阅不支持的代码模式。

使用迁移工具

迁移 Maven 项目

按照以下说明使用 Maven 插件工具迁移基于 Java 1.x 的 SDK 1.x 项目。OpenRewrite

导航到你的 Maven 项目的根目录

打开终端（命令行）窗口，然后导航到基于 Maven 的应用程序的根目录。

运行插件的rewrite-maven-plugin命令

您可以从两种模式（Maven 目标）中进行选择：dryRun和。run

dryRun 模式

在该dryRun模式下，插件会在控制台输出中生成差异日志，并在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值。

** <sdkversion> 替换为 2.x SDK 版本。访问 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 项目

按照以下说明使用 Gradle 插件工具迁移基于 Java 的 SDK 1.x 项目。OpenRewrite

导航到 Gradle 项目的根目录

打开终端（命令行）窗口，导航到基于 Gradle 的应用程序的根目录。

创建 Gradle 初始化脚本

在目录中创建包含以下内容的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 代码，但有些类和方法并未包括在内。对于这些类和方法，请按照step-by-step 说明手动迁移您的代码。

对于某些不支持的代码修改规则，迁移工具可能会添加以下内容开头的注释：


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

在注释之后，该工具会输出该方法或类的 V2 版本的通用存根。例如，在以下输出中，迁移工具尝试迁移 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 的 Amazon SDK
S3 传输管理器 (TransferManager)
DynamoDB 对象映射 (Dynam o) DBMapper
EC2 元数据实用程序 (EC2MetadataUtils)
服务员 () AmazonDynamo DBWaiters
IAM 策略生成器（策略）
CloudFront 预签名 (CloudFrontUrlSigner, CloudFrontCookieSigner)
S3 事件通知 (S3EventNotification)
SDK 指标发布（1.x 文档、2.x 文档）
不支持的代码模式-需要手动迁移的常见代码模式的详细示例

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

如何迁移

不支持的代码模式