适用于 Java 的 AWS SDK 迁移工具

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

该工具支持 SDK 服务客户端和 S3 Transfer Manager 高级库的代码修改规则。不支持其他高级别 API（例如 V1 的 DynamoDBMapper 到 V2 的 DynamoDB 增强型客户端 API）的代码修改规则。

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

使用迁移工具

迁移 Maven 项目

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

如果需要，导航到 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 项目

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

如果需要，导航到 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 代码，但有些类和方法并未包括在内。对于这些类和方法，请按照分步说明手动迁移代码。

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


/*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());

以下列表中的链接可带您前往查看迁移信息，以帮助您手动迁移代码。

适用于 Java 的 AWS SDK 版本 1 和版本 2 之间的 S3 客户端差异
S3 Transfer Manager（TransferManager）
DynamoDB 对象映射（DynamoDBMapper）
EC2 元数据实用程序（EC2MetadataUtils）
Waiter（AmazonDynamoDBWaiters）
IAM 策略生成器（策略）
CloudFront 预签名（CloudFrontUrlSigner、CloudFrontCookieSigner）
S3 事件通知（S3EventNotification）
SDK 指标发布（1.x 文档、2.x 文档）
不支持的代码模式 - 需要手动迁移的常见代码模式的详细示例

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

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

文档惯例

如何迁移

不支持的代码模式