本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 Amazon Q 开发者版升级 Java 版本 Amazon Q 开发者版可在集成式开发环境（IDE）中将您的 Java 应用程序升级到更新的语言版本。为实现代码升级，Amazon Q 可执行的操作包括：更新已废弃的代码组件和 API，以及升级代码中的库、框架和其他依赖项。 要转换代码，Amazon Q 会先使用源语言版本构建您的代码，并验证是否具备执行转换所需的全部信息。Amazon Q 成功转换代码后，您需在 IDE 中验证并确认这些变更。由于 Amazon Q 开发者版仅会对代码进行“最小必要修改”以确保升级后的代码与目标 JDK 兼容，因此若需升级项目的库和依赖项，还需执行额外的转换操作。有关 Amazon Q 如何转换代码的更多信息，请参阅 [Amazon Q 开发者版如何为 Java 语言升级转换代码](how-CT-works.md)。 **Topics** + [支持的 Java 升级版本与 IDE](#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 升级版本与 IDE 目前，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 支持在以下 IDE 中升级 Java： + JetBrains IDE 中的模块 + 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 源代码之外还使用 [frontend-Maven-plugin](https://github.com/eirslett/frontend-maven-plugin) 来执行前端 JavaScript 代码，则转换将失败。 + 您的本地网络允许上传到 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\_PARTY 或 THIRD\_PARTY。 以下是依赖项升级 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. 要详细了解您的代码是如何升级的，以及建议的后续步骤，请在**转换中心**中选择**浏览和更多操作**省略号按钮，然后选择**显示转换摘要**。 ------