기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다. # AWS SDK for Java 마이그레이션 도구 AWS SDK for Java는 SDK for Java 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) 상위 수준 라이브러리에 대한 코드 수정 규칙을 지원합니다. 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)와 같은 다른 상위 수준 API에 대한 코드 수정 규칙은 지원되지 않습니다. 제한 사항에 대한 자세한 내용은 [이 페이지의 마지막 부분](#migration-tool-limitations)을 참조하세요. 수동 마이그레이션 단계에서 지원되지 않는 일반적인 코드 패턴의 자세한 예제는 [지원되지 않는 코드 패턴](migration-tool-unsupported-patterns.md)을 참조하세요. ## 마이그레이션 도구 사용 ### Maven 프로젝트 마이그레이션 아래 설명에 따라 [OpenRewrite Maven 플러그인 도구](https://docs.openrewrite.org/reference/rewrite-maven-plugin)를 사용하여 SDK for Java 1.x Maven 기반 프로젝트를 마이그레이션합니다. 1. Maven 프로젝트의 루트 디렉터리로 이동 터미널(명령줄) 창을 열고 Maven 기반 애플리케이션의 루트 디렉터리로 이동합니다. 1. 플러그인의 `rewrite-maven-plugin` 명령 실행 `dryRun` 및 `run`의 2가지 모드(Maven 목표) 중에서 선택할 수 있습니다. **`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 ``` \$1**을 이 [테스트 파일](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` 값으로 교체합니다. \$1\$1**을 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 ``` \$1**을 이 [테스트 파일](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`로 교체합니다. \$1\$1**을 2.x SDK 버전으로 교체합니다. [Maven Central](https://central.sonatype.com/artifact/software.amazon.awssdk/v2-migration)에서 최신 버전을 확인하세요. 명령을 실행한 후 애플리케이션을 컴파일하고 테스트를 실행하여 변경 사항을 확인합니다. ### Gradle 프로젝트 마이그레이션 아래 설명에 따라 [OpenRewrite Gradle 플러그인](https://docs.openrewrite.org/reference/gradle-plugin-configuration) 도구를 사용하여 SDK for Java 1.x Gradle 기반 프로젝트를 마이그레이션합니다. 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() } } } } ``` \$1**을 이 [테스트 파일](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 코드를 지원하지만, 일부 클래스와 메서드는 적용되지 않습니다. 이러한 클래스 및 메서드의 경우 [단계별 설명](migration-steps.md)에 따라 코드를 수동으로 마이그레이션합니다. 일부 지원되지 않는 코드 수정 규칙의 경우 마이그레이션 도구는 다음으로 시작하는 주석을 추가할 수 있습니다. ``` /*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 클라이언트 차이점 AWS SDK for Java](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) - 수동 마이그레이션이 필요한 일반적인 코드 패턴의 세부 예제 # 마이그레이션 도구의 지원되지 않는 코드 패턴 마이그레이션 도구는 대부분의 v1 코드를 v2로 자동 변환합니다. 그러나 일부 코드 패턴은 수동 마이그레이션이 필요합니다. 이 주제에서는 지원되지 않는 가장 일반적인 패턴의 세부 예제를 제공하고 이를 수동으로 변환하는 방법을 보여줍니다. 다음 패턴 목록이 전부는 아닙니다. 마이그레이션 도구를 실행한 후에도 코드가 컴파일되지 않으면 [단계별 마이그레이션 설명](migration-steps.md)에 따라 나머지 v1 코드를 수동으로 마이그레이션합니다. ## 파라미터를 사용하여 객체 생성자 요청 요청 POJO(Amazon S3 제외)의 경우 마이그레이션 도구는 setter 메서드만 변환합니다. 이 도구는 파라미터가 있는 생성자를 지원하지 않습니다. **지원되는 패턴: setter를 사용하여 객체 요청(작성자 파라미터 없음)** 이전(원래 v1 코드): ``` import com.amazonaws.services.sqs.model.SendMessageRequest; SendMessageRequest request = new SendMessageRequest().withMessageBody("Hello World"); request.setQueueUrl("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue"); ``` 이후(마이그레이션 도구 결과): ``` import software.amazon.awssdk.services.sqs.model.SendMessageRequest; SendMessageRequest request = SendMessageRequest.builder() .messageBody("Hello World").build(); request = request.toBuilder() .queueUrl("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue").build(); ``` **지원되지 않는 패턴: 파라미터를 사용하여 객체 생성자 요청** 마이그레이션 도구는 파라미터가 있는 생성자를 변환할 수 없습니다. 수동 마이그레이션 전, 마이그레이션 도구 사용 후: ``` import software.amazon.awssdk.services.sqs.model.SendMessageRequest; // Import updated to v2. // This pattern requires manual migration. SendMessageRequest request = new SendMessageRequest( "https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue", "Hello World"); ``` 마이그레이션 도구는 가져오기를 v2로 변환하지만 생성자 코드는 변경되지 않고 빌더 패턴을 사용하려면 수동 업데이트가 필요합니다. 수동 마이그레이션 후: ``` import software.amazon.awssdk.services.sqs.model.SendMessageRequest; SendMessageRequest request = SendMessageRequest.builder() .messageBody("Hello World") .queueUrl("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue") .build(); ``` ## 개별 파라미터가 있는 서비스 클라이언트 메서드 마이그레이션 도구는 요청 객체(Amazon S3 제외) 대신 개별 파라미터를 사용하는 서비스 클라이언트 메서드를 변환할 수 없습니다. 이전(v1 코드): ``` import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClient; AmazonSQS sqs = new AmazonSQSClient(); // The following v1 method takes individual parameters. sqs.sendMessage("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue", "Hello World"); ``` 이후(마이그레이션 도구 결과 - 컴파일되지 않음): ``` import software.amazon.awssdk.services.sqs.SqsClient; // Import updated to v2. // No import statement for the v2 request POJO. SqsClient sqs = SqsClient.builder().build(); // Does not compile–v2 methods only accept request POJOs. sqs.sendMessage("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue", "Hello World"); ``` 요청 객체를 사용하려면 메서드 인수를 수동으로 업데이트해야 합니다. ``` import software.amazon.awssdk.services.sqs.SqsClient; import software.amazon.awssdk.services.sqs.model.SendMessageRequest; // Add manually. SqsClient sqs = SqsClient.builder().build(); // Corrected v2 code. SendMessageRequest request = SendMessageRequest.builder() .queueUrl("https://sqs.us-west-2.amazonaws.com/0123456789012/demo-queue") .messageBody("Hello World") .build(); sqs.sendMessage(request); ``` ## 요청 제한 시간 메서드 마이그레이션 도구는 요청 객체에 제한 시간을 설정하는 메서드를 변환하지 않습니다. 이전(v1 코드): ``` import com.amazonaws.services.sqs.model.SendMessageRequest; SendMessageRequest request = new SendMessageRequest(); request.setSdkRequestTimeout(7); ``` 이후(마이그레이션 도구 결과 - 컴파일되지 않음): ``` import software.amazon.awssdk.services.sqs.model.SendMessageRequest; // Import updated to v2. SendMessageRequest request = SendMessageRequest.builder().build(); // Does not compile. request.setSdkRequestTimeout(7); ``` v2의 `overrideConfiguration` 메서드를 사용하려면 수동으로 마이그레이션해야 합니다. ``` import software.amazon.awssdk.services.sqs.model.SendMessageRequest; import java.time.Duration; SendMessageRequest request = SendMessageRequest.builder().build(); // Corrected v2 code. request = request.toBuilder() .overrideConfiguration(o -> o.apiCallTimeout(Duration.ofSeconds(7))) .build(); ``` ## 파라미터가 있는 서비스 클라이언트 생성자 마이그레이션 도구는 비어 있는 서비스 클라이언트 생성자를 변환하지만 자격 증명 또는 구성과 같은 파라미터를 허용하는 생성자는 변환할 수 없습니다. 이전(v1 코드): ``` import com.amazonaws.auth.AWSCredentials; import com.amazonaws.auth.BasicAWSCredentials; import com.amazonaws.services.sqs.AmazonSQS; import com.amazonaws.services.sqs.AmazonSQSClient; AWSCredentials awsCredentials = new BasicAWSCredentials("akid", "skid"); AmazonSQS sqs = new AmazonSQSClient(awsCredentials); ``` 이후(마이그레이션 도구 결과 - 컴파일되지 않음): ``` import software.amazon.awssdk.auth.credentials.AwsCredentials; import software.amazon.awssdk.auth.credentials.AwsBasicCredentials; import software.amazon.awssdk.services.sqs.SqsClient; // Import updated to v2. AwsCredentials awsCredentials = AwsBasicCredentials.create("akid", "skid"); // Does not compile. SqsClient sqs = new SqsClient(awsCredentials); ``` 빌더 패턴을 사용하려면 서비스 클라이언트 생성자를 수동으로 업데이트해야 합니다. ``` import software.amazon.awssdk.auth.credentials.AwsCredentials; import software.amazon.awssdk.auth.credentials.AwsBasicCredentials; import software.amazon.awssdk.auth.credentials.StaticCredentialsProvider; // Add manually. import software.amazon.awssdk.services.sqs.SqsClient; AwsCredentials awsCredentials = AwsBasicCredentials.create("akid", "skid"); // Corrected v2 code. SqsClient sqs = SqsClient.builder() .credentialsProvider(StaticCredentialsProvider.create(awsCredentials)) .build(); ```