本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 Amazon Q 开发者版升级 Java 版本
Amazon Q 开发者版可在集成式开发环境（IDE）中将您的 Java 应用程序升级到更新的语言版本。Amazon Q 可以对您的代码进行升级的更改包括更新已弃用的代码组件， APIs 以及升级代码中的库、框架和其他依赖项。
要转换代码，Amazon Q 会先使用源语言版本构建您的代码，并验证是否具备执行转换所需的全部信息。Amazon Q 成功转换代码后，您需在 IDE 中验证并确认这些变更。由于 Amazon Q 开发者版仅会对代码进行“最小必要修改”以确保升级后的代码与目标 JDK 兼容，因此若需升级项目的库和依赖项，还需执行额外的转换操作。有关 Amazon Q 如何转换代码的更多信息，请参阅 [Amazon Q 开发者版如何为 Java 语言升级转换代码](how-CT-works.md)。
**Topics**
+ [支持的 Java 升级和 IDEs](#supported-languages-IDEs)
+ [步骤 1：先决条件](#java-upgrade-prerequisites)
+ [步骤 2：配置您的项目](#configure-project)
+ [步骤 3：创建依赖项升级文件（可选）](#create-dependency-upgrade-file)
+ [步骤 4：转换代码](#transform-code-java)
+ [Amazon Q 开发者版如何为 Java 语言升级转换代码](how-CT-works.md)
## 支持的 Java 升级和 IDEs
目前，Amazon Q 支持以下 Java 源代码版本及对应的目标升级版本。将代码转换到相同 Java 版本的操作，主要包含升级该源代码版本中的库和其他依赖项。
**支持的 Java 升级版本**
| 源代码版本 | 支持的目标版本 |
| --- | --- |
| Java 8 | Java 17 和 Java 21 |
| Java 11 | Java 17 和 Java 21 |
| Java 17 | Java 17 和 Java 21 |
| Java 21 | Java21 |
Amazon Q 支持以下方面的 Java 升级 IDEs：
+ 中的模块 JetBrains IDEs
+ Visual Studio Code 中的项目和工作区
## 步骤 1：先决条件
继续之前，请确保您已完成[在 IDE 中设置 Amazon Q](q-in-IDE-setup.md) 中的步骤。
在开始代码转换作业之前，确保您满足以下先决条件：
+ 您的项目使用[受支持的 Java 版本](#supported-languages-IDEs)编写，且基于 Maven 构建。
+ 您的项目能在 IDE 中通过 Maven 成功构建，目前支持 Maven 3.8 及更高版本。
+ 您的项目源 JDK 在本地可用，并且是源代码的版本。例如，如果您正在转换 Java 8 代码，则您的本地 JDK 安装应该是 JDK 8。
+ 您的项目将在 55 分钟或更短的时间内完成构建。
+ 您的项目配置正确，并且指定了正确的 JDK 版本。有关更多信息，请参阅[步骤 2：配置您的项目](#configure-project)。
+ 您的项目不需要访问您私有网络中的资源，包括虚拟私有云（VPC）或本地网络。例如，如果您的项目包含连接到网络中数据库的单元测试，则转换将失败。
+ 您的项目没有使用在 Java 项目中打包除 Java 以外语言的插件。例如，如果您的项目除了 Java 源 JavaScript 代码之外还使用执行前端代码，则转换将失败。[frontend-maven-plugin](https://github.com/eirslett/frontend-maven-plugin)
+ 您的本地网络允许上传到 Amazon Q 用来转换您的代码的 Amazon S3 存储桶。有关更多信息，请参阅[允许访问数据边界中的 Amazon S3 存储桶](firewall.md#data-perimeters)。
+ 您的应用程序仅使用 UTF-8 字符。如果您的应用程序使用非 UTF-8 字符，Amazon Q 仍会尝试执行代码转换。
## 步骤 2：配置您的项目
要配置您的项目，请使用您正在使用的 IDE 的以下信息。
### 在 JetBrains 中配置项目
要在 JetBrains 中配置项目，您可能需要指定以下项目和模块设置。
如果您的模块使用与项目相同的 JDK 和语言级别，则无需更新模块设置。
+ 项目 SDK：用于编译项目的 JDK。
+ 项目语言级别：项目中使用的 Java 版本。
+ 模块 SDK：用于编译模块的 JDK。
+ 模块语言级别：您的模块中使用的 Java 版本。
+ Maven Runner JRE：用来构建模块的 JDK。
**更新项目和模块设置**
要更新项目或模块的 SDK 和语言级别设置，请完成以下步骤：
1. 在 JetBrains IDE 中，选择 **File**，然后选择 **Project Structure**。
1. 此时会打开“Project Structure”窗口。在 **Project Settings** 下，选择 **Project**。
1. 要更新您的项目 JDK，请从 **SDK** 旁边的下拉列表中进行选择。
1. 要更新项目语言，请从 **Language level** 旁边的下拉列表中进行选择。
1. 在 **Project Settings** 下，选择 **Modules**。
1. 要更新您的模块 JDK，请从 **SDK** 旁边的下拉列表中进行选择。
1. 要更新模块语言，请从 **Language level** 旁边的下拉列表中进行选择。
有关更多信息，请参阅 JetBrains 文档中的 [Project structure settings](https://www.jetbrains.com/help/idea/project-settings-and-structure.html) 和 [Module structure settings](https://www.jetbrains.com/help/idea/configure-modules.html)。
**更新 Maven 设置**
要更新 Maven Runner JRE，请完成以下步骤：
1. 在 JetBrains IDE 中，选择齿轮图标，然后在出现的菜单中选择 **Settings**。
1. 在 **Settings** 窗口中，依次选择 **Build, Execution, Deployment**、**Build Tools**、**Maven** 以及 **Runner**。
1. 在 JRE 字段中，选择用于构建要转换的模块的 JDK。
### 在 VS Code 中配置项目
要在 VS Code 中配置项目，您的项目必须包含以下内容：
+ 项目根文件夹中的 `pom.xml` 文件
+ 项目目录中的 `.java` 文件
如果您的项目包含 Maven 包装器可执行文件（适用于 macOS 的 `mvnw` 或适用于 Windows 的 `mvnw.cmd`），请确保它位于项目的根目录中。Amazon Q 将使用包装器，无需进行其他 Maven 配置。
如果您不使用 Maven 包装器，请安装 Maven。有关更多信息，请参阅 Apache Maven 文档中的 [Installing Apache Maven](https://maven.apache.org/install.html)。
安装 Maven 后，将其添加到您的 `PATH` 变量中。有关更多信息，请参阅 [如何将 Maven 添加到我的 `PATH`？](troubleshooting-code-transformation.md#add-maven-to-path)您的 Java `runtime` 变量还应指向 JDK 而不是 JRE。要确认您的配置是否正确，请运行 `mvn -v`。输出应显示您的 Maven 版本和指向 JDK 路径的 `runtime` 变量。
## 步骤 3：创建依赖项升级文件（可选）
您可向 Amazon Q 提供*依赖项升级文件*，这是一个 YAML 文件，用于列出项目依赖项及转换过程中需升级到的版本。通过提供该文件，您可指定 Amazon Q 可能无法自动识别的第三方依赖项和第一方依赖项，确保其得到升级。
第一方依赖项：指您的组织维护的库、插件和框架，仅在本地或组织专用网络中可用。Amazon Q 在本地环境中构建代码时，可访问这些第一方依赖项。有关更多信息，请参阅 [在本地环境中构建代码](how-CT-works.md#java-local-builds)。第三方依赖项：指公开可用的开源依赖项，并非您的组织专属。
您可在 YAML 文件中指定需升级的第一方依赖项，Amazon Q 会在 JDK 升级（例如从 Java 8 到 17）过程中对其进行升级。初始 JDK 升级完成后，您可启动单独的转换作业（如从 17 到 17、从 21 到 21）来升级第三方依赖项。
Amazon Q 完成最低版本 JDK 升级后，您可启动单独的转换作业以升级所有第三方依赖项；或者，也可在 YAML 文件中指定第三方依赖项及其版本，仅在库升级转换过程中升级这些指定的依赖项。
转换过程中，Amazon Q 会提示您提供依赖项升级文件。如需提供，请先确保文件配置正确。YAML 文件中必须包含以下字段：
+ name：依赖项升级文件的名称。
+ description（可选）：依赖项升级文件的描述，及该文件对应的转换场景。
+ dependencyManagement：包含需升级的依赖项和插件列表。
+ dependencies：包含需升级的库的名称和版本。
+ plugins：包含需升级的插件的名称和版本。
+ identifier：库、插件或其他依赖项的名称。
+ targetVersion：依赖项需升级到的版本。
+ versionProperty（可选）：依赖项的版本（在应用的 `pom.xml` 文件中通过 `properties` 标签定义）。
+ originType：依赖项类型，需指定为 FIRST\$1PARTY 或 THIRD\$1PARTY。
以下是依赖项升级 YAML 文件及 Amazon Q 可解析的必要配置的示例：
```
name: dependency-upgrade
description: "Custom dependency version management for Java migration from JDK 8/11/17 to JDK 17/21"
dependencyManagement:
dependencies:
- identifier: "com.example:library1"
targetVersion: "2.1.0"
versionProperty: "library1.version" # Optional
originType: "FIRST_PARTY"
- identifier: "com.example:library2"
targetVersion: "3.0.0"
originType: "THIRD_PARTY"
plugins:
- identifier: "com.example.plugin"
targetVersion: "1.2.0"
versionProperty: "plugin.version" # Optional
originType: "THIRD_PARTY"
```
## 步骤 4：转换代码
要测试 IDE 设置，请下载并解压缩示例项目，然后为 IDE 完成以下步骤。如果您能够查看提议的更改和转换摘要，您就可以转换自己的代码项目。如果转换失败，则说明您的 IDE 配置不正确。要解决配置问题，请查看[步骤 2：配置您的项目](#configure-project)和[问题排查](troubleshooting-code-transformation.md)。
**注意**
在代码转换期间，请勿关闭本地计算机或使其进入睡眠状态。初始构建和验证构建均依赖客户端环境，且需要稳定的网络连接。
要升级您的代码项目或模块的代码语言版本，请完成以下步骤。
------
#### [ JetBrains ]
1. 在 JetBrains 中打开要升级的模块。确保您已在 IDE 中成功构建项目。
1. 选择 Amazon Q 徽标，然后在打开的聊天面板中让 Amazon Q 转换您的应用程序。
1. 此时将出现**转换您的应用程序**弹出窗口。从下拉列表中选择要升级的项目，然后选择**转换**。
1. Amazon Q 会提示您提供升级依赖项文件。如果您已配置包含待升级依赖项及对应版本的 YAML 文件，上传该文件即可。Amazon Q 会验证文件配置是否正确。若出现错误，请回顾[步骤 3：创建依赖项升级文件（可选）](#create-dependency-upgrade-file)中描述的文件格式和必填字段。
1. Amazon Q 开始转换。您可以在**转换详细信息**选项卡中查看进度。
1. 转换完成后，您可以先验证升级后的代码再更新项目。要查看新代码，请转到**转换详细信息**选项卡，然后选择**查看差异**。在出现的**应用补丁**窗口中，选择一个文件以打开包含源代码和升级后代码的差异视图。
1. 要接受 Amazon Q 所做的更改，请选择**查看差异**以打开**应用补丁**窗口。选择所有更新的文件，然后选择**确定**以就地更新您的项目。
1. 要详细了解您的代码是如何升级的，以及建议的后续步骤，请在**转换详细信息**选项卡上选择**查看转换摘要**。
------
#### [ Visual Studio Code ]
1. 在 VS Code 中打开要升级的项目或工作区。确保您已在 IDE 中成功构建项目。
1. 选择 Amazon Q 徽标，然后在打开的聊天面板中让 Amazon Q 转换您的应用程序。
1. 从 IDE 顶部的搜索栏中选择要升级的项目。
1. 如果 Amazon Q 找不到您的源代码版本，它会提示您选择代码版本。选择编写源代码的版本，然后在弹出窗口中选择**转换**以继续。
1. 如果出现提示，请输入 JDK 的 `JAVA_HOME` 路径。有关更多信息，请参阅[配置您的 VS Code 项目](#configure-vsc)。
1. Amazon Q 会提示您提供升级依赖项文件。如果您已配置包含待升级依赖项及对应版本的 YAML 文件，上传该文件即可。Amazon Q 会验证文件配置是否正确。若出现错误，请回顾[步骤 3：创建依赖项升级文件（可选）](#create-dependency-upgrade-file)中描述的文件格式和必填字段。
1. Amazon Q 开始转换。您可以在**转换中心**选项卡上查看进度。
1. 转换完成后，**提议的更改**选项卡打开。要在更新项目之前验证升级后的代码，请选择**下载提议的更改**。选择一个文件以打开包含源代码和升级后代码的差异视图。
1. 要接受 Amazon Q 所做的更改，请前往**提议的更改**选项卡并选择**接受**。
1. 要详细了解您的代码是如何升级的，以及建议的后续步骤，请在**转换中心**中选择**浏览和更多操作**省略号按钮，然后选择**显示转换摘要**。
------
# Amazon Q 开发者版如何为 Java 语言升级转换代码
为转换您的代码，Amazon Q 开发者版会生成一个转换计划，用于升级项目的代码语言版本。转换代码后，它会提供转换摘要和文件差异信息，以便您在接受更改之前查看更改内容。由于 Amazon Q 开发者版仅会对代码进行“最小必要修改”以确保升级后的代码与目标 JDK 兼容，因此若需升级项目的库和依赖项，还需执行额外的转换操作。以下各部分提供了有关 Amazon Q 如何执行转换的更多详细信息。
## 构建代码并创建转换计划
要开始转换您的代码，Amazon Q 会在本地构建您的项目，并生成包含源代码、项目依赖项和构建日志的构建构件。
生成构建构件后，Amazon Q 会在安全的构建环境中构建您的代码，并创建针对您要升级的项目或模块定制的转换计划。转换计划概述了 Amazon Q 将尝试进行的具体更改，包括新的依赖项版本、主要代码更改以及针对已弃用代码的建议替代方案。这些更改基于您的代码的初步构建，并且可能会在转换过程中发生变化。
## 转换您的代码
在执行代码转换时，Amazon Q 会依据转换计划中的建议变更，尝试将您的代码升级到目标 Java 版本 当它进行更改时，它会重新构建并运行源代码中的现有单元测试，以迭代方式修复遇到的任何错误。目前支持以下源代码版本到目标版本的 JDK 升级：
+ Java 8 到 17
+ Java 8 到 21
+ Java 11 到 17
+ Java 11 到 21
+ Java 17 到 21
为确保代码与目标 Java 版本兼容，Amazon Q 仅会进行“最小必要修改”。Amazon Q 完成最低版本 JDK 升级后，您可启动单独的转换作业以升级所有第三方依赖项；或者，也可在 YAML 文件中指定第三方依赖项及其版本，仅在库升级转换过程中升级这些指定的依赖项。
Amazon Q 在升级您的代码时会尝试进行以下更改：
+ 根据目标 Java 版本的官方建议，更新已废弃的代码组件
+ 将常用库和框架升级到与目标 Java 版本兼容的版本。这包括将以下库和框架更新到其最新可用的主要版本：
+ Apache Commons IO
+ Apache HttpClient
+ bc-fips
+ Cucumber-JVM
+ Hibernate
+ jackson-annotations
+ JakartaEE
+ Javax
+ javax.servlet
+ jaxb-api
+ jaxb-impl
+ jaxen
+ jcl-over-slf4j
+ json-simple
+ jsr305
+ junit
+ junit-jupiter-api
+ Log4j
+ Micronaut
+ Mockito
+ mockito-core
+ Okio
+ PowerMockito
+ Quarkus
+ slf4j
+ slf4j-api
+ Spring Boot
+ Spring Framework
+ Spring Security
+ Swagger
+ testng
**注意**
代码转换过程中，请勿关闭本地计算机，因为客户端构建需要稳定的网络连接。
## 在本地环境中构建代码
代码转换过程中，Amazon Q 会在您的本地环境中执行验证构建。Amazon Q 在服务端通过多步操作对代码进行转换。每完成一步转换，Amazon Q 会将代码发送到您的本地环境，对已做的变更进行构建和测试。测试完成后，代码会被送回服务端，继续下一步转换。
在本地环境中执行构建操作能让 Amazon Q 运行需要访问私有资源的测试，从而帮助验证转换后的代码。为降低在本地环境中构建 AI 生成代码的安全风险，Amazon Q 会审查并更新其生成的代码，以解决潜在的安全问题。
## 查看转换摘要并接受更改
转换完成后，Amazon Q 会提供一份转换摘要，其中包含有关其所做更改的详细信息，包括最终构建的状态，该状态表明您的整个项目是否已升级。您还可以查看构建日志摘要，以了解阻碍 Amazon Q 在升级版本中构建代码的任何问题。
转换摘要还包括转换计划中提议的更改与 Amazon Q 最终为升级您的代码所做的更改之间的差异，以及原始计划中未包含的任何其他更改。
查看转换摘要后，您可以在文件差异视图中查看 Amazon Q 提议的更改。在您接受更改之前，Amazon Q 建议的任何代码更改都不会影响您当前的项目文件。转换后的代码在转换完成后的最多 30 天内可用。
## 完成部分成功的转换
根据代码库的复杂性和具体情况，在某些情况下，转换可能会部分成功。这意味着 Amazon Q 只能转换项目中的某些文件或代码区域。在这种情况下，您必须手动更新剩余的代码，这样您的项目才能使用更新的语言版本进行构建。
为了帮助转换代码的其余部分，您可以在 IDE 中使用 Amazon Q 聊天功能。您可以让 Amazon Q 查看部分更新的文件，并提供新的代码来解决诸如编译错误之类的问题。您还可以使用[功能开发和 [Workspace 上下文](workspace-context.md)等功能](q-in-IDE-chat.md#develop-code)将更多项目内容作为上下文包含在内，并一次获取有关多个文件的建议。