本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 Amazon Q 开发者版转换 Java 应用程序 **注意** AWS Transform 自定义版现在可用于 Java 升级。Agentic AI 可以处理版本升级、SDK 迁移等，并且每次执行都会得到改进。[开始使用](https://docs.aws.amazon.com/transform/latest/userguide/custom-get-started.html) Amazon Q 支持对 Java 应用程序执行以下类型的转换： + Java 语言版本与依赖项版本升级 + 嵌入式 SQL 转换（用于 Oracle 到 PostgreSQL 数据库迁移场景） 要开始操作，请参阅您所需执行的转换类型对应的主题文档。 **Topics** + [ ## 配额 ](#quotas-java-transformation-ide) + [ # 使用 Amazon Q 开发者版升级 Java 版本 ](code-transformation.md) + [ # 使用 Amazon Q 开发者版转换 Java 应用程序中的嵌入式 SQL ](transform-sql.md) + [ # 通过 Amazon Q 开发者版在命令行中转换代码 ](transform-CLI.md) + [ # 查看转换作业历史记录 ](transformation-job-history.md) + [ # Java 转换故障排查 ](troubleshooting-code-transformation.md) ## 配额 在 IDE 和命令行中使用 Amazon Q 转换 Java 应用程序时，需遵循以下配额限制： + **单任务代码行数**：Amazon Q 在单个转换作业中可处理的最大代码行数。 + **每月代码行数**：Amazon Q 每月可处理的最大代码行数。 + **并发任务数**：您可同时运行的最大转换作业数量。此配额适用于 IDE 中的所有转换操作，包括 [Visual Studio 中的 .NET 转换。](transform-dotnet-IDE.md) + **每月任务数**：您每月可运行的最大转换作业数量。 | 资源 | 配额 | | --- | --- | | 单任务代码行数 | 免费套餐：1000 行代码 | | 每月代码行数 | 免费套餐：2000 行代码 | | 并发任务 | 每位用户 1 个任务 每个 AWS 账户 25 个职位 | | 每月任务数 | 专业套餐：1000 个任务 免费套餐：100 个任务 | # 使用 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)将更多项目内容作为上下文包含在内，并一次获取有关多个文件的建议。 # 使用 Amazon Q 开发者版转换 Java 应用程序中的嵌入式 SQL 用于在 IDE 中进行代码转换的 Amazon Q Developer 代理可以帮助您使用 (DMS) 将嵌入式 SQL 转换为完成 Oracle 到 PostgreSQL 数据库 AWS Database Migration Service 的AWS 迁移。 AWS DMS 是一项云服务，可以迁移关系数据库、数据仓库、NoSQL 数据库和其他类型的数据存储。 AWS DMS 中的 DMS 架构转换功能，可帮助您转换数据库架构和代码对象，以便应用到目标数据库。有关更多信息，请参阅[什么是 AWS Database Migration Service？](https://docs.aws.amazon.com/dms/latest/userguide/Welcome.html) 在《*AWS Database Migration Service 用户指南》*中。 使用 AWS DMS 和 DMS 架构转换迁移数据库时，可能需要转换应用程序中的嵌入式 SQL 以使其与目标数据库兼容。您无需手动转换，可通过 IDE 中的 Amazon Q 实现自动化转换。Amazon Q 会利用 DMS 架构转换生成的元数据，将应用中的嵌入式 SQL 转换为与目标数据库兼容的版本。 目前，Amazon Q 仅支持将“从 Oracle 数据库迁移到 PostgreSQL 数据库”场景下的 Java 应用程序中的 SQL 进行转换。只有当您的应用包含 Oracle SQL 语句时，IDE 中才会显示 SQL 代码转换选项。有关更多信息，请参阅先决条件。 ## 步骤 1：先决条件 继续之前，请确保您已完成[在 IDE 中设置 Amazon Q](q-in-IDE-setup.md) 中的步骤。 在启动 SQL 转换的代码转换作业前，请确保满足以下先决条件： + 您正在迁移的 Java 应用程序包含嵌入式 SQL，且迁移场景为“从 Oracle 数据库迁移到 PostgreSQL 数据库”。应用程序中必须包含 Oracle SQL 语句，才有资格进行转换。 + 您已使用 AWS DMS 架构转换完成数据库架构的转换流程。有关更多信息，请参阅《数据库迁移指南》**中的[使用 DMS 架构转换将 Oracle 数据库迁移到 Amazon RDS for PostgreSQL](https://docs.aws.amazon.com/dms/latest/sbs/schema-conversion-oracle-postgresql.html)。 + 架构转换完成后，您已从 AWS DMS 控制台下载了迁移项目文件。 ## 步骤 2：配置应用程序 要转换嵌入式 SQL 代码，您的 Java 项目必须至少包含一个 `.java` 文件。 如果您使用的是 JetBrains IDE，则必须将 “项目结构” 设置中的 “SDK” 字段设置为适用的 JDK。有关配置项目结构设置的信息，请参阅 JetBrains 文档中的[项目结构设置](https://www.jetbrains.com/help/idea/project-settings-and-structure.html)。 ## 步骤 3：转换嵌入式 SQL 要将 Java 应用程序中的嵌入式 SQL 代码转换为与 PostgreSQL 目标数据库兼容的格式，请完成以下步骤： 1. 在已安装 Amazon Q 的 IDE 中，打开包含待转换嵌入式 SQL 的 Java 代码库。 1. 选择 Amazon Q 图标以打开聊天面板。 1. 让 Amazon Q 在聊天面板中转换您的应用程序。 1. 如果您的 Java 应用程序符合 SQL 转换条件，Amazon Q 会提示您选择要执行的转换类型。输入 **SQL conversion**。 1. Amazon Q 会提示您上传从 Amazon S3 获取的架构元数据文件。Amazon Q 会在聊天中提供获取该文件的操作说明。 1. Amazon Q 会提示您提供包含嵌入式 SQL 的项目以及数据库架构文件，从聊天面板的下拉菜单中选择相应的文件。 1. 确认 Amazon Q 从数据库架构中获取的详情准确无误。 1. Amazon Q 开始转换 SQL 代码，此过程可能需要几分钟。 1. SQL 代码转换完成后，Amazon Q 会生成一个差异对比文件，显示对文件所做的所有更新。查看差异对比中的变更，然后确认接受变更以更新代码。 Amazon Q 还会提供一份转换摘要，详细说明所做的变更。 1. 更新代码后，返回 AWS DMS 控制台验证新 SQL 是否与迁移后的数据库兼容。 # 通过 Amazon Q 开发者版在命令行中转换代码 您可以使用 Amazon Q 开发者版命令行转换工具，从命令行对应用程序进行代码转换。要转换代码，您只需提供源代码路径及所有必要的配置文件，Amazon Q 会通过一系列步骤生成新代码。在整个转换过程中，Amazon Q 会在您的本地环境中构建代码，以验证变更的有效性。有关更多信息，请参阅 [在本地环境中构建代码](#local-builds)。Amazon Q 会在您的存储库中创建一个新分支，并将代码更改提交到该分支。转换完成后，您可将该分支合并到原始分支，从而将变更整合到代码库中。 要开始使用，需先安装命令行工具并完成身份验证，然后参考相关命令配置并启动转换作业。 **Topics** + [ ## 在本地环境中构建代码 ](#local-builds) + [ ## 命令 ](#commands) + [ # 通过 Amazon Q 开发者版在命令行中运行转换作业 ](run-CLI-transformations.md) + [ # 在命令行中排查转换问题 ](troubleshooting-CLI-transformations.md) + [ # Amazon Q 开发者版命令行转换工具版本历史记录 ](transform-CLI-versions.md) ## 在本地环境中构建代码 代码转换过程中，Amazon Q 会在您的本地环境中执行验证构建。Amazon Q 在服务端通过多步操作对代码进行转换。每完成一步转换，Amazon Q 会将代码发送到您的本地环境，对已做的变更进行构建和测试。测试完成后，代码会被送回服务端，继续下一步转换。 在本地环境中执行构建操作能让 Amazon Q 运行需要访问私有资源的测试，从而帮助验证转换后的代码。为降低在本地环境中构建 AI 生成代码的安全风险，Amazon Q 会审查并更新其生成的代码，以解决潜在的安全问题。 **注意** Amazon Q 会根据您项目的请求、描述及内容执行转换。为确保安全，请避免在项目存储库中包含外部未经验证的构件，且务必对转换后的代码进行功能和安全性双重验证。 ## 命令 有关运行这些命令的 step-by-step说明，请参见[通过 Amazon Q 开发者版在命令行中运行转换作业](run-CLI-transformations.md)。 要配置转换并验证 Amazon Q 开发者版专业套餐身份，请运行以下命令： ``` qct configure ``` 要启动 Java 升级转换，请运行以下命令。对于**，您可以输入`JAVA_1.8``JAVA_8`、`JAVA_11`、`JAVA_17`、或`JAVA_21`。对于**，您可以输入`JAVA_17`或`JAVA_21`。`--source_version` 和 `--target_version` 均为可选参数。`--trust` 用于启用转换功能，同时对代码进行验证以保障安全性。 ``` qct transform --source_folder --source_version --target_version --trust ``` 要启用 SQL 转换，请运行以下命令： ``` qct transform --source_folder --sql_conversion_config_file ``` 要查看当前使用的命令行转换工具版本，请运行以下命令： ``` qct -v ``` 要获取转换相关帮助信息，请运行以下命令： ``` qct -h ``` 要查看转换作业历史记录，请运行以下命令： ``` qct history ``` 有关查看和管理转换作业历史记录的更多信息，请参阅[在命令行中查看作业历史记录](transformation-job-history.md#cli-job-history)。 # 通过 Amazon Q 开发者版在命令行中运行转换作业 若要使用 Amazon Q 开发者版命令行工具在命令行中转换代码，请完成以下步骤。 ## 先决条件 在命令行中启动转换作业前，必须满足以下先决条件： + 如果您要升级 Java 代码版本，您的项目需符合[通过 Amazon Q 升级 Java 版本的先决条件](code-transformation.md#java-upgrade-prerequisites)。 + 如果您要转换 Java 应用中的嵌入式 SQL，您的应用需符合[通过 Amazon Q 转换嵌入式 SQL 的先决条件](transform-sql.md#sql-transform-prereqs)。 + 您的命令行环境中已安装 Python （用于安装命令行工具），且受支持的 Python 版本不低于 3.12。 + 您正在 macOS 或 Linux 系统上运行转换作业。 + 应用程序大小不超过 2GB。 + 如果您希望 Amazon Q 升级特定依赖项，需已配置[依赖项升级文件](#step-3-dependency-upgrade-file)。 ## 步骤 1：选择身份验证方式并添加权限 可通过 IAM Identity Center 进行身份验证，以在命令行中运行转换作业。请确保您拥有适当的权限。 **注意** 命令行中执行的转换作业不支持客户托管密钥。 ### 添加权限 用于身份验证的 Amazon Q 开发者版订阅所关联的 IAM 身份，必须具备在命令行中执行转换作业的权限。继续操作前，请确保您的 IAM 身份拥有[支持用户在命令行上运行转换](id-based-policy-examples-users.md#id-based-policy-examples-allow-cli-transformations)中定义的权限。 ### 通过 Amazon Q 开发者版订阅使用 IAM Identity Center 进行身份验证 要通过 IAM Identity Center 验证身份，您需由管理员[添加为 Amazon Q 开发者版专业套餐的员工用户并完成订阅](subscribe-users.md)，且需提供订阅对应的起始 URL 以完成身份验证。您或您的管理员可在 Amazon Q 开发者版控制台中找到该起始 URL。有关更多信息，请参阅[查找用于 Amazon Q 开发者版的起始 URL](manage-account-details.md)。 要添加所需权限，请参阅[添加权限](#transform-CLI-add-permissions)。 您需在[步骤 4：配置和身份验证](#step-4-configure-auth)中提供该起始 URL。 ## 步骤 2：安装工具 1. [下载 Amazon Q 命令行转换工具](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.2.2.zip)并解压缩。 要下载工具的旧版本，请参阅[版本历史记录](transform-CLI-versions.md)。 1. 建议在 Python 中创建虚拟环境以安装该工具。要创建虚拟环境，请在您希望安装工具的目录中打开终端窗口，然后运行以下命令： ``` python -m venv qct-cli ``` 1. 要激活虚拟环境，请运行以下命令： ``` source qct-cli/bin/activate ``` 1. 要在命令行中安装该工具，请根据您的计算机架构运行以下命令，其中包含该工具的解压缩路径： ------ #### [ Linux\$1aarch64 ] ``` pip install /Linux_aarch64/amzn_qct_cli-1.2.2-py3-none-any.whl ``` ------ #### [ Linux\$1x86\$164 ] ``` pip install /Linux_x86_64/amzn_qct_cli-1.2.2-py3-none-any.whl ``` ------ **注意** 如果您使用的是旧版本的命令行转换工具，请将 `1.2.2` 替换为您下载的[版本号](transform-CLI-versions.md)。 1. 要验证该工具是否已安装，请运行以下命令： ``` which qct ``` ## 步骤 3：创建依赖项升级文件（可选） 您可向 Amazon Q 提供*依赖项升级文件*，这是一个 YAML 文件，用于列出项目依赖项及转换过程中需升级到的版本。通过提供该文件，您可指定 Amazon Q 可能无法自动识别的第三方依赖项和第一方依赖项，确保其得到升级。 第一方依赖项：指您的组织维护的库、插件和框架，仅在本地或组织专用网络中可用。Amazon Q 在本地环境中构建代码时，可访问这些第一方依赖项。有关更多信息，请参阅 [在本地环境中构建代码](transform-CLI.md#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：配置和身份验证 在启动转换作业前，您必须通过 IAM Identity Center 完成身份验证，并提供转换所需的配置详情。 1. 要启动转换配置流程，请运行以下命令： ``` qct configure ``` 1. 系统会提示您为每个受支持的 Java 版本输入 JDK 路径。您只需指定 Java 应用源版本的 JDK 路径，无需提供目标版本的路径。 1. 接下来，为通过 IAM Identity Center 验证身份，系统会提示您输入 Amazon Q 开发者版专业套餐订阅配置文件对应的起始 URL。 然后，按以下格式输入您的订阅 AWS 区域 地点：`us-east-1`。有关受支持区域的列表，请参阅[支持的区域](regions.md)。有关区域代码的列表，请参阅《AWS 一般参考 指南》**中的[区域端点](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints)。 1. 您的配置偏好会保存到 configuration.ini 文件中。 ## 步骤 5：运行转换作业 根据您要执行的转换类型，查看所需配置和命令。 **注意** 代码转换过程中，请勿关闭本地计算机，因为客户端构建需要稳定的网络连接。 ------ #### [ Java upgrade ] **修改转换计划** 在 Java 版本升级过程中，Amazon Q 会生成一份转换计划，您可在转换开始前查看该计划。对于该计划，您可请求进行以下修改： + 指定 Amazon Q 需升级的库（从计划包含的库列表中选择） + 提示示例： + 仅升级 、 和 + 不升级 或 + 指定库需升级到的目标版本 + 提示示例： + 将 升级到此版本（而非 版本） + 指定 Amazon Q 需执行的步骤 + 提示示例： + 仅完成步骤 1-7 + 不执行步骤 5-9 + 添加需额外升级的依赖项（仅在升级到更新的 JDK 版本时可用此选项） + 提示示例： + 同时将 升级到 **升级 Java 代码** 1. 运行以下命令启动 Java 升级转换作业。将 `` 替换为待转换代码所在文件夹的路径，将 `` 替换为 `JAVA_17` 或 `JAVA_21`。 ``` qct transform --source_folder --target_version ``` 额外命令选项： + 若需指定待升级的依赖项，请添加 `--dependency_upgrade_file` 选项，并附上您的依赖项升级文件路径。 + 若无需查看或更新转换计划，请在命令中添加 `--no-interactive` 标志。此时 Amazon Q 不会请求您对计划提供反馈，您也无法请求修改计划。 1. 转换开始前，系统会验证您的 Maven 版本。如果您的 Maven 版本不低于最低支持版本，会看到以下输出： ``` Running command: mvn --version at: path/to/current/directory Your Maven version is supported for transformations. ``` 如果您的 Maven 版本不受支持，需先更新版本才能继续。有关更多信息，请参阅[先决条件](#CLI-transformation-prerequisites)。 1. 如果您未添加 `--no-interactive` 标志，Amazon Q 会提示您对转换计划提供反馈。您可使用自然英语说明希望进行的修改，若 Amazon Q 支持该修改，会更新转换计划。 1. Amazon Q 开始转换。并在过程中输出状态更新。转换完成后，Amazon Q 会提供转换结果、日志及配置文件的输出路径。 升级后的代码会提交到 Amazon Q 创建的新分支中。根据您运行 `qct configure` 时的选择，Amazon Q 会通过一次或多次提交完成代码提交。 1. 若要在 Java 版本升级后执行另一次转换，请在第一次转换代码提交所在的同一分支中启动第二次转换。 ------ #### [ SQL conversion ] 开始前，请确保您已阅读[使用 Amazon Q 开发者版转换 Java 应用程序中的嵌入式 SQL](transform-sql.md)，了解此类转换所需满足的先决条件。 1. 要转换嵌入式 SQL，您必须先创建一个 YAML 文件，其中包含来自 [AWS DMS 架构转换](https://docs.aws.amazon.com/dms/latest/sbs/schema-conversion-oracle-postgresql.html)的架构元数据文件路径。 以下是该文件的必填格式： ``` schema_conv_metadata_path: ``` 1. 运行以下命令启动 SQL 转换作业。将 `` 替换为待转换代码所在文件夹的路径，将 `` 替换为您在步骤 1 中创建的 YAML 文件路径。 ``` qct transform --source_folder --sql_conversion_config_file ``` 1. 若 Amazon Q 在您的架构元数据文件中检测到多个架构，会停止转换并列出所有检测到的架构。请选择用于 SQL 转换的架构，然后在 YAML 文件中添加新字段 `schema: `。 1. Amazon Q 开始转换。并在过程中输出状态更新。转换完成后，Amazon Q 会提供转换结果、日志及配置文件的输出路径。 升级后的代码会提交到 Amazon Q 创建的新分支中。 ------ ## 暂停或取消转换作业 您可以选择暂停或取消当前的转换作业。转换作业最多可暂停 12 小时，之后可恢复继续执行。 **要暂停或取消代码转换作业，请执行以下步骤：** 1. 在 CLI 终端中，按下键盘上的 **Ctrl\$1C**。 1. 选择是要暂停还是取消转换。 + 若要暂停代码转换作业，请输入 `1`。您可在 12 小时内使用以下 QCT 命令恢复作业，继续进行代码转换：``qct transform --source_folder=≤/Path/Given/Originally/To/QCT>``。 + 若要取消代码转换作业，请输入 `2`。 # 在命令行中排查转换问题 以下信息可帮助您排查使用 Amazon Q 开发者版在命令行中转换应用程序时遇到的常见问题。 ## 为什么我的持有者令牌无法刷新？ 如果您看到以下错误，则表明用于身份验证的持有者令牌需要刷新。 ``` Refreshing bearer token ('Error refreshing bearer token due to: ', InvalidGrantException('An error occurred (InvalidGrantException) when calling the CreateToken operation: ')) ('Error getting bearer token due to: ', RuntimeError(('Error refreshing bearer token due to: ', InvalidGrantException('An error occurred (InvalidGrantException) when calling the CreateToken operation: ')))) ``` 要解决此错误，请运行以下命令： ``` rm ~/.aws/qcodetransform/credentials.json ``` 删除过期的凭证文件后，重新运行 `qct transform` 命令以重启转换作业。 ## 为何未使用命令行工具的最新版本？ 当您下载命令行转换工具的新版本后，有时系统仍会使用旧版本的工具。 要确保使用工具的最新版本，请下载工具的[最新版本](transform-CLI-versions.md)。然后根据您的计算机架构运行以下命令，其中包含该工具的解压缩路径： ------ #### [ Linux\$1aarch64 ] ``` pip install /Linux_aarch64/amzn_qct_cli-1.2.2-py3-none-any.whl --force-reinstall ``` ------ #### [ Linux\$1x86\$164 ] ``` pip install /Linux_x86_64/amzn_qct_cli-1.2.2-py3-none-any.whl --force-reinstall ``` ------ **注意** 如果您使用的是旧版本的命令行转换工具，请将 `1.2.2` 替换为您下载的[版本号](transform-CLI-versions.md)。 # Amazon Q 开发者版命令行转换工具版本历史记录 以下信息详细列出了 Amazon Q 开发者版命令行转换工具当前及过往版本的发布详情。该表包含各版本的下载链接、发布日期和发行说明。 **** | 版本 | 发行日期 | 发行说明 | | --- | --- | --- | | [1.2.2（最新）](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.2.2.zip) | 2026年2月26日 | 在 QCT CLI 中添加了 AWS 自定义转换的宣传横幅。执行转换命令时显示横幅和帮助文本。新的--skip-banner标志，用于抑制横幅输出。 | | [1.2.1](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.2.1.zip) | 2025 年 9 月 9 日 | 更新了 Maven 扩展，使其 POMs 在初始项目上传期间包括第一方父项 | | [1.2.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.2.0.zip) | 2025 年 8 月 7 日 | 新增了支持，现在支持查看作业历史记录、Maven Java 项目的模块结构可视化。 | | [1.1.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.1.0.zip) | 2025 年 7 月 21 日 | 新增了支持，现在支持收集转换相关的遥测数据。 | | [1.0.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-1.0.0.zip) | 2025 年 6 月 27 日 | 命令行转换工具现已正式发布，仅支持订阅 Amazon Q Developer Pro，通过 AWS IAM 身份中心进行身份验证。新增对欧洲地区（法兰克福）订阅的支持。 | | [0.6.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.6.0.zip) | 2025 年 6 月 6 日 | 新增了支持，现在支持提供依赖项升级文件、对转换计划进行迭代。 | | [0.5.2](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.5.2.zip) | 2025 年 4 月 16 日 | 缺陷修复，解决了作业恢复时出现的问题，以及包含第一方依赖项的应用程序转换失败问题。 | | [0.5.1](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.5.1.zip) | 2025 年 3 月 13 日 | 通过 IAM 验证身份时，不再需要提供 AWS 区域；同时包含缺陷修复程序，可在输出日志中显示作业状态。 | | [0.5.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.5.0.zip) | 2025 年 2 月 28 日 | 包括支持通过使用 IAM 进行身份验证。 AWS CLI | | [0.4.1](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.4.1.zip) | 2025 年 2 月 17 日 | 错误修复，包括支持输入 Amazon Q Developer 订阅的配置 AWS 区域 位置。 | | [0.4.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.4.0.zip) | 2025 年 2 月 14 日 | 新增了支持，现在支持将 Java 应用程序升级至 Java 21。 | | [0.3.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.3.0.zip) | 2025 年 2 月 12 日 | 新增了支持，现在支持转换 Java 应用程序中的嵌入式 SQL。 | | [0.2.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.2.0.zip) | 2025 年 2 月 3 日 | 新增了支持，现在支持通过多次提交获取升级后的 Java 代码。 | | [0.1.0](https://desktop-release.codewhisperer.us-east-1.amazonaws.com/amzn_qct_cli/amzn_qct_cli-0.1.0.zip) | 2024 年 11 月 27 日 | 初始版本。支持通过命令行升级 Java 代码版本。 | # 查看转换作业历史记录 Amazon Q 会全面汇总您的 Java 转换作业历史记录，支持您在 IDE 和命令行中跟踪、查看转换作业详情。 转换作业历史记录包含有关作业的以下信息： + **日期**：转换作业的执行时间 + **项目名称**：已转换项目的名称 + **状态**：转换作业的当前状态 + **持续时间**：转换作业的完成时长 + **任务 ID**：转换作业的唯一标识符 + **差异补丁**：指向包含所有代码更改的最终差异补丁文件的链接或路径 + **摘要**：指向包含变更详情的转换摘要文件的链接或路径 **注意** 作业历史记录中仅显示该功能发布后执行的转换作业。有关功能发布日期，请参阅 [《Amazon Q 开发者版用户指南》文档历史记录](doc-history.md)。 ## 在 IDE 中查看作业历史记录 **注意** 目前此功能仅在 Visual Studio Code 中可用。 Visual Studio Code 中的“转换中心”会全面展示您的 Java 转换作业历史记录。 转换中心的表格会列出过去 30 天内最新的 10 条转换作业。从表格中，您可访问转换构件，也可刷新作业状态以跟踪进度、获取缺失的构件。 ### 检索转换构件 在作业历史记录表格中，您可访问转换构件（如差异补丁文件、摘要文件）。选择对应的链接，即可在 IDE 中打开差异补丁或摘要。 这些构件会本地存储在 `.aws/transform` 目录中，因此您也可直接从该目录访问过往作业中已下载的转换构件。 ### 刷新作业状态 您可以刷新作业历史记录表中的作业状态。刷新失败的作业可从服务器端获得可能尚未同步到服务器的更新状态（例如在 Amazon Q 能够恢复失败的作业时）。您也可以刷新已完成的作业，以下载尚未显示的构件。 ### 如何针对在 IDE 中运行的作业存储作业历史记录 在 Visual Studio Code 中，所有转换作业信息及构件均本地存储在 `.aws/transform` 目录中。存储的组织结构如下： ``` .aws/transform/ ├── [project-name-1]/ │ ├── [job-id-1]/ │ │ ├── diff.patch │ │ ├── [summary-1]/ │ │ │ └── summary.md │ │ │ └── buildCommandOutput.log │ └── [job-id-2]/ │ ├── diff.patch │ ├── [summary-2]/ │ │ └── summary.md │ │ └── buildCommandOutput.log └── [project-name-2]/ └── [job-id-3]/ ├── diff.patch ├── [summary-3]/ │ └── summary.md │ └── buildCommandOutput.log ``` ## 在命令行中查看作业历史记录 对于通过命令行执行的转换作业，可使用 **qct history** 命令查看转换作业历史记录，并支持自定义选项。 对于 CLI，转换作业的历史信息均本地存储在 `.aws/qcodetransform/history/` 目录中。 ### 使用 qct history 命令 查看转换作业历史记录的基础命令如下： ``` qct history ``` 默认情况下，该命令会显示最新的 10 条转换作业，同时包含所有暂停或进行中的作业。 您还可通过 **--limit** 标志指定要显示的作业历史记录条目数。例如，要显示 20 条作业，请运行以下命令： ``` qct history --limit 20 ``` # Java 转换故障排查 以下信息可帮助您排查使用 Amazon Q 开发者版转换 Java 应用程序时遇到的常见问题。 **Topics** + [ ## 为什么 Amazon Q 无法上传我的项目？ ](#project-upload-fail) + [ ## 为什么我的 Maven 命令失败了？ ](#maven-commands-failing) + [ ## 如何将 Maven 添加到我的 `PATH`？ ](#add-maven-to-path) + [ ## 为什么 Amazon Q 无法构建我的代码？ ](#build-fail) + [ ## 为什么我的转换在 55 分钟后失败了？ ](#build-time-limit) + [ ## 为什么我无法下载转换后的代码？ ](#download-code-fail) + [ ## 如何访问代码转换日志？ ](#logs) + [ ## 如何找到我的转换作业 ID？ ](#job-id) ## 为什么 Amazon Q 无法上传我的项目？ 如果您的项目上传失败，则可能是由以下某个问题所致。请参阅与您在 Amazon Q 中看到的错误相对应的主题。 **Topics** + [ ### 减小项目大小 ](#reduce-project-size) + [ ### 在 IDE 中配置代理设置 ](#configure-proxy) + [ ### 允许访问 Amazon S3 ](#allowlist-s3-bucket) ### 减小项目大小 为了转换您的代码，Amazon Q 会生成一个项目构件，其中包括您的源代码、项目依赖项和构建日志。转换作业的最大项目构件大小为 2 GB。如果您遇到与项目构件大小相关的错误，则必须减小项目的大小或尝试转换较小的项目。您可以在代码转换日志中查看项目构件文件的大小。有关更多信息，请参阅[如何访问代码转换日志？](#logs) ### 在 IDE 中配置代理设置 为了转换您的代码，Amazon Q 会将您的项目构件上传到服务拥有的 Amazon S3 存储桶。在上传过程中，需要使用 SSL 或 TLS 证书在 Amazon S3 和您的 IDE 之间建立通信。如果您使用的是代理服务器，则必须信任您的代理服务器使用的 SSL 或 TLS 证书，否则 Amazon Q 将无法上传您的项目。 如果您收到与代理或证书相关的错误，则可能需要将 IDE 或操作系统配置为信任您的证书或更新其他代理设置。 **注意** 如果您位于组织的代理服务器或防火墙后面，则可能还会遇到与证书无关的问题。如果您完成了以下步骤来配置证书，但仍有问题，请联系您的网络管理员以确保允许您通过 IDE 与 Amazon S3 通信。有关更多信息，请参阅[允许访问 Amazon S3](#allowlist-s3-bucket)。 #### 在 JetBrains 中配置证书 要将 JetBrains IDE Java 运行时环境（JRE）配置为信任代理服务器使用的 SSL 或 TLS 证书，必须将 SSL 或 TLS 证书导入 JRE 中的 `cacerts` 文件中。该 `cacerts` 文件是一个包含用于安全连接的可信根证书（例如 HTTPS 和 SSL），它是 JRE 安全设置的一部分。要导入证书，请完成以下流程。 **注意** 我们建议在修改 `cacerts` 文件之前对其进行备份，因为任何错误都可能导致安全连接出现问题。 1. 确定 JRE 中 `cacerts` 文件的路径。JetBrains IDE 附带的内部 JRE 中 `cacerts` 文件的路径取决于操作系统和您使用的 JetBrains IDE 版本。 以下是常见操作系统中 `cacerts` 文件路径的示例。选择您的操作系统以查看示例。 **注意** `` 指安装 JetBrains 产品的目录。此目录通常是在安装过程中选择的。 该`jbr`文件夹表示捆绑在一起的 JRE JetBrains IDEs，它是专为与使用而量身定制的 JRE 的特定版本。JetBrains IDEs ------ #### [ Windows ] 安装在 Windows 上的 JetBrains IDE `cacerts` 的文件路径为： ``` \jbr\bin\cacerts ``` 例如，如果您在 Windows 上将 JetBrains IDE 安装在默认位置，则路径可能是： ``` C:\Program Files\JetBrains\jbr\bin\cacerts ``` ------ #### [ macOS ] 安装在 macOS 上的 JetBrains IDE `cacerts` 的文件路径为： ``` /Applications/JetBrains Toolbox//JetBrains Toolbox.app/Contents/jbr/Contents/Home/lib/security/cacerts ``` 例如，如果您在 macOS 上将 JetBrains IDE 安装在默认位置，则路径可能是： ``` /Applications/JetBrains Toolbox/2022.3.4/JetBrains Toolbox.app/Contents/jbr/Contents/Home/lib/security/cacerts ``` ------ #### [ Linux ] 安装在 Linux 上的 JetBrains IDE `cacerts` 的文件路径为： ``` /opt/jetbrains/jbr/lib/security/cacerts ``` ------ 1. 确定需要导入到 `cacerts` 文件中的证书。证书文件通常具有 `.cer`、`.crt` 或 `.der` 文件扩展名。如果您不确定需要添加哪些证书，请联系您的网络管理员。 1. 将证书导入 `cacerts` 密钥库。您可以使用 Java `keytool` 命令执行此操作。 1. 打开命令提示符，然后输入以下命令： ``` keytool -import -alias -file -keystore ``` 1. 对于 ``，您可以为要导入的证书添加一个名称，以便日后参考。此选项为可选项。 1. 对于 ``，请指定要导入的证书的路径。这应该是包含证书的 `.cer`、`.crt` 或 `.der` 文件的路径。 1. 对于 ``，请指定您在步骤 1 中保存的 `cacerts` 密钥库文件的路径。这是您要导入证书的文件。 例如，如果要将名为 `my_certificate.cer` 的证书导入到 Windows 上 IntelliJ IDEA 中捆绑的 JRE 的 `cacerts` 密钥库，并且要为该证书指定别名 `myalias`，则命令可能是： ``` keytool -import -alias myalias -file my_certificate.cer -keystore "C:\Program Files\JetBrains\IntelliJ IDEA 2022.3.2\jbr\bin\cacerts" ``` 1. 在导入过程中，系统将提示您输入密钥库密码。`cacerts` 密钥库的默认密码是 `changeit`。 1. 运行该命令后，系统将要求您信任证书。要确认证书可信并完成导入，请输入 `yes`。 1. 除了 JRE 之外，您可能还需要将证书添加到 IDE 本身。有关更多信息，请参阅 JetBrains 文档中的 [Server Certificates](https://www.jetbrains.com/help/idea/settings-tools-server-certificates.html)。 #### 在 Visual Studio Code 中配置证书 要配置 Visual Studio Code 以信任代理服务器使用的 SSL 或 TLS 证书，请确保已为操作系统配置了以下代理设置。 ##### 在 macOS 上为 Visual Studio Code 配置证书 在 macOS 上为 Visual Studio Code 配置以下代理设置。 ##### 将证书添加到您的 macOS 钥匙串 如果还没有，则必须将代理服务器使用的证书添加到 macOS 钥匙串中。有关向钥匙串添加证书的信息，请参阅《钥匙串访问使用手册》中的[在 Mac 上使用“钥匙串访问”将证书添加到钥匙串](https://support.apple.com/guide/keychain-access/add-certificates-to-a-keychain-kyca2431/mac)。 ##### 安装 Mac CA VSCode 扩展程序 [Mac CA VSCode 扩展程序](https://marketplace.visualstudio.com/items?itemName=linhmtran168.mac-ca-vscode)允许 Amazon Q 访问你在 Mac 上的 Keychain Access 中添加的证书。 安装扩展程序： 1. 在 VS Code 扩展程序窗格中搜索 `mac-ca-vscode`，然后选择 **Install**。 1. 重新启动 VS Code。 ##### 在 macOS 上更新 VS Code 中的代理设置 更新以下设置，确保您的代理已正确配置 VS Code。 1. 在 VS Code 中打开设置。 1. 在搜索栏中输入 `proxy`。 1. 在 **Http: Proxy** 字段中，添加您的代理 URL。 1. 取消选择 **Http: Proxy Strict SSL**。 1. 在 **Http: Proxy Support** 下拉列表中，选择 **on**。 1. 在设置搜索栏中，输入 `http.experimental.systemCertificatesV2`。选择 **Http › Experimental: System Certificates V2**。 ##### 在 Windows 上为 Visual Studio Code 配置证书 在 Windows 上为 Visual Studio Code 配置以下代理设置。 ##### 在 Windows 上将证书添加为受信任的根证书 如果还没有，则必须将代理服务器使用的证书添加到 Windows 上的受信任的根证书颁发机构存储中。要添加证书，请完成以下流程： 1. 打开搜索工具或 Run 命令窗口。 1. 输入以下命令以打开 Certificate Manager 工具： ``` certmgr.msc ``` 1. 选择 **Trusted Root Certification Authorities** 存储。 1. 右键单击 **Certificates**，选择 **All Tasks**，然后选择 **Import...**。 1. 按照给出的说明导入您的代理证书。 1. 导入证书后，确认证书已添加。 在 **Trusted Root Certification Authorities** 存储中，双击 **Certificates**。右键单击您添加的证书，然后选择 **Properties**。在 **Certificate purposes** 下，**Enable all purposes for this certificate** 选项应该是选中状态。 ##### 安装 Win-CA 扩展 VSCode 程序 [Win-CA VSCode 扩展](https://marketplace.visualstudio.com/items?itemName=ukoloff.win-ca)允许 Amazon Q 访问你在 Windows 中添加到可信根证书中的证书。 安装扩展程序： 1. 在 VS Code 设置窗格中搜索 `win-ca `。 1. 在 **Inject** 下拉列表中，选择 **append**。 ##### 在 Windows 上更新 VS Code 中的代理设置 更新以下设置，确保您的代理已正确配置 VS Code。 1. 在 VS Code 中打开设置。 1. 在搜索栏中输入 `proxy`。 1. 在 **Http: Proxy** 字段中，添加您的代理 URL。 1. 取消选择 **Http: Proxy Strict SSL**。 1. 在 **Http: Proxy Support** 下拉列表中，选择 **on**。 1. 在设置搜索栏中，输入 `http.experimental.systemCertificatesV2`。选择 **Http › Experimental: System Certificates V2**。 1. 重新启动 VS Code。 ### 允许访问 Amazon S3 在转换期间，Amazon Q 会将您的转码上传到服务拥有的 Amazon S3 存储桶。如果您的网络或组织尚未配置对 Amazon S3 的访问权限，则 Amazon Q 将无法上传您的项目。 为确保 Amazon Q 可以上传您的项目，请确保将代理配置和其他网络组件 [例如数据丢失防护（DLP）策略] 配置为允许访问 Amazon S3。您可能还需要将 Amazon Q 上传项目的 Amazon S3 存储桶列入允许列表。有关更多信息，请参阅[Amazon S3 存储桶 URLs 和 ARNs 允许名单](firewall.md#data-perimeters)。 如果您转换大型项目，DLP 策略或其他网络组件如果未配置为允许访问 Amazon S3 存储桶，则可能会导致延迟并妨碍成功上传。如果您选择不将存储桶列入允许列表，则可能需要转换一个较小的项目，以便 Amazon Q 可以将其上传。 ## 为什么我的 Maven 命令失败了？ 以下是你可能会在JetBrains和中看到的Maven配置问题Visual Studio Code IDEs。如果您解决了问题，但仍然看到 Maven 错误，则可能是您的项目出现了问题。使用错误日志中的信息来解决项目中的任何问题，然后尝试再次转换您的项目。 ### 在 JetBrains 中更新 Maven 配置 如果由于 Maven 命令问题导致 JetBrains 中转换失败，则错误日志将显示在 **Run** 选项卡上。使用日志中的信息解决问题。以下是您可能需要解决的一些问题： + 确保您的 Maven 主路径设置为 **Bundled**。在 **Settings** 对话框中，展开 **Build, Execution, Deployment** 部分。展开 **Build Tools** 部分，然后展开 **Maven**。在 **Maven home path** 下拉列表中，选择 **Bundled**。 + 确保 Java 运行时环境（JRE）正在使用您的项目 JDK。在 **Settings** 对话框中，展开 **Build, Execution, Deployment** 部分。展开 **Maven** 并选择 **Runner**。在 **JRE** 下拉列表中，选择 **Use Project JDK**。 + 确保 Maven 已启用。前往 **Settings**，然后选择 **Plugins**。搜索 Maven，然后选择 Maven 插件。如果您看到 **Enable** 按钮，请选择该按钮以启用 Maven。 ### 在 Visual Studio Code 中更新 Maven 配置 如果由于 Maven 命令问题导致 VS Code 中的转换失败，则会在新选项卡中打开包含错误日志的文本文件。使用日志中的信息解决问题。 确保您配置了以下任一选项： + 您的项目在项目根文件夹中包含一个 Maven 包装器 + 您的 `PATH` 中有 Amazon Q 支持的 Maven 版本 有关更多信息，请参阅[如何将 Maven 添加到我的 `PATH`？](#add-maven-to-path) ## 如何将 Maven 添加到我的 `PATH`？ 要在不使用 Maven 包装器的情况下在 VS Code 中转换代码，您必须安装 Maven 并将其添加到 `PATH` 变量中。 要检查您是否已正确安装 Maven，请在 Visual Studio Code 之外的新操作系统终端运行 `mvn -v`。您应该会看到 Maven 版本的输出。 如果您是在 Visual Studio Code 终端中而不是您的操作系统终端中获得输出，或者如果找不到该命令，则需要将 Maven 添加到您的 `PATH`。 要将 Maven 添加到您的 `PATH`，请按照您计算机的说明进行操作。 ------ #### [ macOS ] 要将 Maven 添加到您的 macOS `PATH` 中，请完成以下步骤。 1. 找到您的 Maven 安装目录或安装 Maven 的文件夹，然后保存该文件夹的路径。 1. 在您选定的编辑器中打开 Shell 的配置文件。对于最新的 macOS 版本，默认 shell 为 `zsh`，默认配置文件位于 `~/.zshrc`。 将以下行添加到配置文件底部。将 `M2_HOME` 的值设置为您在步骤 1 中保存的路径： ``` export M2_HOME="your Maven installation directory" export PATH="${M2_HOME}/bin:${PATH}" ``` 这些命令使 `mvn` 命令可在所有终端中使用。 1. 关闭所有操作系统终端窗口并退出所有 Visual Studio Code 实例。 1. 要验证 Maven 是否已添加到您的 `PATH`，请打开一个新的操作系统终端并运行以下命令： ``` mvn -v ``` 您应该会看到 Maven 版本的输出。 1. 看到 Maven 输出后，请重新启动 Visual Studio Code。您可能还需要重新启动计算机。打开一个新的 Visual Studio Code 终端，并运行以下命令： ``` mvn -v ``` 输出应与步骤 4 中的输出相同。如果 Visual Studio Code 输出不同，请尝试以下操作以确保您的设置正确： + 检查 Visual Studio Code 中您的 `PATH` 变量。IDE 扩展程序可能正在更改 `PATH`，使其与您的局部 `PATH` 变量不同。卸载扩展程序以将其从您的 `PATH` 中移除。 + 检查 Visual Studio Code 中您的默认 Shell。如果它被设置为 `zsh` 以外的其他值，请对 Shell 重复这些步骤。 ------ #### [ Windows ] 要将 Maven 添加到您的 Windows `PATH` 中，请完成以下步骤： 1. 找到您的 Maven 安装目录或安装 Maven 的文件夹，然后保存该文件夹的路径。 1. 打开“Environment Variables”窗口： 1. 选择 Windows 按钮以打开搜索栏。 1. 输入 `Edit environment variables for your account` 并选择它。 1. 在 **Environment Variables** 窗口中，查找 Path 变量。如果您已经有 Path 变量，请选择 **Edit...** 来更新它。如果看不到 Path 变量，请选择 **New...** 添加一个。 1. 在出现的 **Edit environment variable** 窗口中，双击现有路径进行编辑，或者选择 **New** 以添加新的路径条目。 将现有 Maven 路径条目替换为在步骤 1 中保存的路径，或者将该路径添加为新条目。在路径末尾添加 `\bin` 作为后缀，如下例所示： ``` C:\Users\yourusername\Downloads\apache-maven-3.9.6-bin\apache-maven-3.9.6\bin ``` 1. 选择 **OK** 保存路径条目，然后在 **Environment Variables** 窗口中再次选择 **OK**。 1. 打开新的命令提示符，然后运行以下命令： ``` mvn -v ``` 您应该会看到 Maven 版本的输出。 ------ ## 为什么 Amazon Q 无法构建我的代码？ 如果在 Amazon Q 构建您的代码时转换失败，可能是因为您的项目没有针对 Amazon Q 构建代码的环境进行正确配置。您可能需要更新构建配置或代码实现。 查看 Amazon Q 提供的构建日志输出，以确定是否可以对项目进行更改。以下是一些可能阻碍 Amazon Q 构建代码的常见问题。 ### 移除 pom.xml 中的绝对路径 如果您的 pom.xml 文件中有绝对路径，Amazon Q 将无法找到相关文件，因此可能无法构建您的代码。 以下是 `pom.xml` 文件中可能包含的绝对路径的示例： ``` /Library/Java/JavaVirtualMachines/jdk-11.0.11.jdk/Contents/Home/lib/tools.jar ``` 您可以使用指针创建相对路径，而不要使用绝对路径。以下是如何用相对路径替换之前的绝对路径的示例： ``` ${java.home}/../lib/tools.jar ``` ### 在单元测试中移除本地或外部数据库 Amazon Q 在构建您的代码时会在您的项目中运行任何单元测试。如果单元测试调用本地或外部数据库，Amazon Q 将无法访问该数据库，从而导致构建失败。为防止生成构建失败，在提交转换之前，必须从单元测试中移除数据库调用或移除单元测试。 ## 为什么我的转换在 55 分钟后失败了？ 如果您的代码转换作业在 55 分钟后失败，则您的代码构建时间可能超过了构建时间限制。目前，构建代码的时间限制为 55 分钟。 如果您的本地构建时间需要 55 分钟或更长时间，请缩短项目构建时间来转换代码。如果您的本地构建速度比使用代码转换构建的速度快，请检查您的项目中是否存在可能失败或在其他环境中耗时更长的任务。考虑禁用长时间运行的测试用例。还要考虑针对访问可能无法从安全 IDE 环境或 Internet 获得的资源的尝试使用超时设置。 ## 为什么我无法下载转换后的代码？ 如果您在转换完成后无法下载代码，可能是由以下某个问题所致。请参阅与您在 Amazon Q 中看到的错误相对应的主题。 **Topics** + [ ### 减小项目大小 ](#reduce-project-size-output) + [ ### 在 30 天内下载代码差异 ](#download-30-hrs) + [ ### 在 IDE 中配置代理设置 ](#configure-proxy-download) + [ ### 移除 JetBrains 代理设置中的通配符 ](#remove-wildcard) ### 减小项目大小 转换完成后，Amazon Q 会生成一个输出构件（其中包含与升级后的代码的差异信息）和转换摘要（包含有关所做更改的信息）。输出构件必须不超过 1 GB，IDE 才能下载它。 如果输出构件超出限制，您将无法下载升级后的代码或转换摘要。尝试转换较小的项目，以防止生成较大的输出构件。如果问题仍然存在，请联系 支持。有关 支持 与 Amazon Q 联系的信息，请参阅[使用 Amazon Q 开发者版与 支持 聊天](support-chat.md)。 ### 在 30 天内下载代码差异 包含升级后代码的代码差异文件仅在转换完成后的 30 天内可用。如果距离转换完成时间已超过 30 天，请重新启动转换以下载差异文件。 ### 在 IDE 中配置代理设置 Amazon Q 会从服务拥有的 Amazon S3 存储桶下载升级后的代码。下载过程的一部分涉及使用 SSL 或 TLS 证书在 Amazon S3 和您的 IDE 之间建立通信。如果您使用的是代理服务器，则必须信任您的代理服务器使用的 SSL 或 TLS 证书，否则 Amazon Q 将无法上传您的项目。 要下载代码，您可能需要将 IDE 配置为信任证书或更新其他代理设置。有关更新代理设置的更多信息，请参阅 [在 IDE 中配置代理设置](#configure-proxy)。 ### 移除 JetBrains 代理设置中的通配符 如果您已在 JetBrains IDE 中配置了代理设置，则在下载升级后的代码时可能会看到以下错误： ``` software.amazon.awssdk.core.exception.SdkClientException: Unable to execute HTTP request: Dangling meta character '*' near index 0 ``` 这可能是由于您的 IDE 的代理设置的 **No proxy for** 字段中存在通配符（\$1）所致。Amazon Q 使用的 Java SDK 不支持此字段中的通配符条目。 要下载您的代码，请从 **No proxy for** 字段中删除所有通配符，然后重新启动 IDE。如果您需要指定应绕过代理的主机，请使用正则表达式而不是通配符。要更新 JetBrains IDE 中的代理设置，请参阅JetBrains文档中的 [HTTP 代理](https://www.jetbrains.com/help/idea/settings-http-proxy.html)。 ## 如何访问代码转换日志？ ### JetBrains 中的访问日志 有关如何访问 JetBrains 日志文件的信息，请参阅 JetBrains 文档中的[查找 IDE 日志文件](https://intellij-support.jetbrains.com/hc/en-us/articles/207241085-Locating-IDE-log-files)。 要查找 Amazon Q 在 JetBrains 中发出的日志，请在 IDE 日志中搜索以下字符串： ``` software.aws.toolkits.jetbrains.services.codemodernizer ``` 代码转换日志以前面的字符串开头。Maven 生成的日志显示在 **Run** 选项卡上，并且在日志条目前后都有前面的字符串。 ### Visual Studio Code 中的访问日志 要查找 Amazon Q 在 VS Code 中发出的日志，请完成以下步骤： 1. 在顶部导航栏中选择**视图**，然后选择**命令面板**。 1. 在出现的命令面板中搜索 `Amazon Q: View Logs`。 1. 日志将在 IDE 中打开。要在日志文件中搜索 `CodeTransformation`，请使用 `CMD + F` 或 `Control + F`。 VS Code 中的代码转换日志前缀为 `CodeTransformation:`。以下是 VS Code 针对 Maven 复制依赖关系错误生成的日志的示例： ``` 2024-02-12 11:29:16 [ERROR]: CodeTransformation: Error in running Maven copy-dependencies command mvn = /bin/sh: mvn: command not found ``` ## 如何找到我的转换作业 ID？ ### 在 JetBrains 中查找您的任务 ID 要在 JetBrains 中查找转换作业 ID，请转到 **Transformation Hub** 的 Transformation details 选项卡，然后选择 **Show Job Status**（时钟）图标。 ### 在 Visual Studio Code 中查找您的任务 ID 要在 VS Code 中查找转换作业 ID，请转到 **Transformation Hub** 并选择 **Show Job Status**（时钟）图标。