本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 与 Amazon Q 开发者版就代码问题进行交互 在您的集成开发环境 (IDE) 中与 Amazon Q Developer 交谈，询问有关构建的问题 AWS 以及软件开发方面的帮助。Amazon Q 可以解释编码概念和代码片段，生成代码和单元测试，并改进代码，包括调试或重构。 **Topics** + [在 IDE 中使用 Amazon Q](#working-with-q-in-IDE) + [示例任务](#example-tasks) + [问题示例](#example-topics-questions) + [报告 Amazon Q 回复的问题](#report-issues) + [使用 Amazon Q 开发者版进行代码审查](code-reviews.md) + [在 IDE 中使用 Amazon Q 开发者版转换代码](transform-in-IDE.md) + [使用 Amazon Q 开发者版解释和更新代码](explain-update-code.md) + [通过内联聊天与 Amazon Q 开发者版进行交互](q-in-IDE-inline-chat.md) + [在 IDE 中为 Amazon Q 开发者版聊天添加上下文](ide-chat-context.md) + [Amazon Q 开发者版中的聊天历史记录压缩功能](ide-chat-history-compaction.md) + [查看、删除和导出 Amazon Q 开发者版对话历史记录](ide-chat-conversation.md) + [在与 Amazon Q 开发者版的聊天中使用快捷键](q-in-ides-chat-shortcuts.md) + [在 IDE 中为 Amazon Q 聊天选择模型](q-in-ides-chat-models.md) ## 在 IDE 中使用 Amazon Q ### 使用聊天 要开始与 Amazon Q 进行交互，请从 IDE 的导航栏中选择 Amazon Q 图标，然后在文本栏中输入您的问题。要开始在 Visual Studio 中与 Amazon Q 进行交互，请从主菜单中选择**视图**，然后选择 **Amazon Q 聊天**。 向 Amazon Q 提问时，它会使用在 IDE 中打开的当前文件作为上下文，包括编程语言和文件路径。您可以在提示中添加更多上下文，或者在整个聊天会话中将文件、文件夹或整个工作空间指定为上下文。有关更多信息，请参阅 [为聊天添加上下文](ide-chat-context.md)。 如果 Amazon Q 的回复中包含代码，您可以将其复制或通过选择**在光标处插入**直接插入到文件中。Amazon Q 可能会在其回复中包含对其来源的内联引用。 Amazon Q 会保留您在给定会话中的对话，用作未来回复的参考。在整个会话期间，您可以提出后续问题或参考之前的问题和回复。要开始与 Amazon Q 的新对话，请在面板中打开一个新选项卡。您一次最多可以打开 10 个选项卡。Amazon Q 不会在不同对话之间保留上下文。 #### 聊天命令 以下命令可帮助您管理与 Amazon Q 的聊天。 + **/clear**-使用此命令清除当前对话。这将从聊天面板中删除所有之前的对话，并清除 Amazon Q 有关您之前对话的上下文。 + **/compac** t-当上下文窗口接近其容量限制时，使用此命令压缩聊天记录。这会生成对话摘要，同时保留关键信息。 + **/help**-使用此命令可查看 Amazon Q 能做什么和不能做什么的概述、示例问题和可用功能。 ### 代理编码 借助代理编码，Amazon Q 可以充当您的编码伙伴，在开发过程中与您聊天。在 IDE 中，代理编码默认处于启用状态。您可通过对话面板底部的 `` 图标，开启或关闭代理编码功能。 当您要求 Amazon Q 改进您的代码时，它会直接更新您的文件。您可以查看差异中的更改，并可以选择撤消更改。 当 Amazon Q 思考或处理任务时，您可以继续在聊天面板中添加说明，它会将这些说明纳入其工作中。 当您与 Amazon Q 讨论项目时，它会提供 Shell 命令建议。有时，若它判断这些命令风险较低，会自动运行这些命令。 ### 用自然语言聊天 当您在 IDE 中与 Amazon Q 开发者版进行交互时，它支持多语言交互。受支持的自然语言包括中文（普通话）、法语、德语、意大利语、日语、西班牙语、韩语、印地语和葡萄牙语，未来还将支持更多语言。要使用此功能，只需在 IDE 中用您偏好的自然语言发起与 Amazon Q 的对话即可。Amazon Q 会自动检测语言，并以对应的语言提供回复。 ## 示例任务 ### 开发代码功能 **注意** 在本文档和 IDE 中，此功能曾被称为 /dev。 Amazon Q 可以帮助您开发代码功能，对项目进行代码更改，并回答有关集成开发环境 (IDE) 中软件开发任务的问题。您解释要完成的任务，然后 Amazon Q 使用您当前项目或工作空间的上下文来生成可应用于您的代码库的代码。Amazon Q 可以帮助您构建 AWS 项目或您自己的应用程序。 ### 单元测试生成 **注意** 在本文档和 IDE 中，此功能曾经被称为 /test。 Amazon Q 可以生成单元测试，因此您可以在整个软件开发生命周期中自动进行测试。此功能有助于开发者专注于加速功能开发，同时确保代码质量。 ### 文档生成 **注意** 在本文档和 IDE 中，此功能曾被称为 /doc。 Amazon Q 通过为您的代码生成文档和其他文档来帮助您理解代码 READMEs 并更新文档。它可以生成新文档并更新代码库中的现有文档。 ### 代码审查 **注意** 在本文档和 IDE 中，此功能曾经被称为 /review。 Amazon Q 可以检查您的代码库中是否存在安全漏洞和代码质量问题，以改善应用程序在整个开发周期中的状况。有关如何使用此功能的更多信息，请参阅[使用 Amazon Q 开发者版进行代码审查](code-reviews.md)。 ### 转换代码 Amazon Q 可以通过执行语言和操作系统 (OSIDEs) 级别的自动升级和转换，在集成开发环境 () 中转换您的代码。您只需提供待转换的代码，Amazon Q 便会生成相应变更；您可先查看这些变更，再将其应用到文件中。有关更多信息，请参阅 [转换代码](transform-in-IDE.md)。 ## 问题示例 在内部 IDEs，除了生成代码外，Amazon Q 还可以回答有关 AWS 服务 软件开发的问题。Amazon Q 在回答与以下主题领域相关的问题时特别有用。 + 在此基础上 AWS再接再 AWS 服务 厉，包括选择、限制和最佳实践 + 一般软件开发概念，包括编程语言语法和应用程序开发 + 编写代码，包括解释代码、调试代码和编写单元测试 为了在 IDE 中充分利用 Amazon Q，您可以提出一些类似于以下示例的问题： + 部署到亚马逊云科技之前，如何在本地调试我的 Lambda 函数的问题？ + 如何在 Amazon AWS Lambda 和 Amazon 之间做出选择 EC2 以获得可扩展的 Web 应用程序后端？ + 在 TypeScript 中声明变量的语法是什么？ + 如何在 React 中编写应用程序？ + 向我描述此 [*选定代码或应用程序*] 的作用及其工作原理。 + 生成 [*选定代码或函数*] 的测试用例。 ## 报告 Amazon Q 回复的问题 您可以选择使用竖起大拇指（赞成）和大拇指向下（反对）图标为 Amazon Q 生成的每个回复留下反馈。要报告回复的问题，请选择大拇指向下（反对）图标，然后在出现的反馈窗口中输入信息。 # 使用 Amazon Q 开发者版进行代码审查 Amazon Q 开发者版可以审查您的存储库中是否存在安全漏洞和代码质量问题，从而改善整个开发周期内应用程序的状况。您可以查看整个代码库，分析本地项目或工作区中的所有文件，或者查看单个文件。您还可以启用 auto reviews，以便在您编写代码时对其进行评估。 代码审查功能由生成式人工智能和基于规则的自动推理技术共同提供支持。[Amazon Q 探测器](https://docs.aws.amazon.com/codeguru/detector-library)以多年的经验 AWS 和 Amazon.com 安全最佳实践为依据，为基于规则的安全和质量审查提供支持。随着安全策略的更新和探测器的添加，审查会自动加入新的检测器，以确保您的代码符合大多数 up-to-date策略。 有关支持 IDEs 此功能的信息，请参阅[支持 IDEs](q-in-IDE.md#supported-ides-features)。有关支持的语言的信息，请参阅[对代码审查的语言支持](q-language-ide-support.md#code-reviews-language-support)。 **Topics** + [工作方式](#how-code-reviews-work) + [代码问题的类型](#issue-types) + [限额](#quotas) + [使用 Amazon Q 开发者版启动代码审查](start-review.md) + [使用 Amazon Q 开发者版解决代码问题](address-code-issues.md) + [筛选代码问题](filter-code-issues.md) + [Amazon Q 开发者版代码审查中的代码问题严重级别](code-issue-severity.md) ## 工作方式 在代码审查期间，Amazon Q 会同时评估您的自定义代码和代码中引用的第三方库。在开始代码审查之前，Amazon Q 会先执行筛选操作，确保仅审查相关代码；筛选过程中，Amazon Q 会排除不支持的语言、测试代码及开源代码。 Amazon Q 可以查看您最近的代码更改，也可以查看整个文件或项目。要启动审查，请在 IDE 中打开您的代码文件夹，然后让 Amazon Q 在聊天面板中查看您的代码。 默认情况下，如果您只是让 Amazon Q 审阅您的代码，它将只审查 IDE 中活动文件中的代码更改。代码更改由文件中`git diff`命令的输出决定。如果不存在差异文件，Amazon Q 将审查整个代码文件。如果未打开任何文件，它将搜索项目中的任何代码更改以进行审查。 同样，如果您让 Amazon Q 审查您的整个项目或工作空间，它将首先尝试审查您的代码更改。如果不存在差异文件，它将审查您的整个代码库。 ## 代码问题的类型 Amazon Q 会审查您的代码是否存在以下类型的代码问题： + **SAST 扫描：检测源代码中的安全漏洞。**Amazon Q 可识别各种安全问题，例如资源泄漏、SQL 注入和跨站脚本。 + **机密检测：防止泄露代码中的敏感或机密信息。**Amazon Q 会审查您的代码和文本文件以查找硬编码密码、数据库连接字符串和用户名等机密。机密调查结果包括有关未受保护的机密以及如何保护它的信息。 + **IaC 问题：评估基础设施文件的安全状况。**Amazon Q 可以审查您的基础设施即代码（IaC）代码文件，以检测配置错误、合规性和安全问题。 + **代码质量问题：确保代码符合质量、可维护性和效率标准。**Amazon Q 会生成与各种质量问题相关的代码问题，包括但不限于性能问题、机器学习规则和 AWS 最佳实践等问题。 + **代码部署风险：评估与部署代码相关的风险。**Amazon Q 会判断在部署或发布代码期间是否存在风险，包括应用程序性能风险和业务运营中断风险。 + **软件组成分析（SCA）：评估第三方代码。**Amazon Q 会检查代码中集成的第三方组件、库、框架及依赖项，确保第三方代码安全且为最新。 有关 Amazon Q 用于代码审查的完整检测器列表，请参阅 [Amazon Q 检测器库](https://docs.aws.amazon.com/codeguru/detector-library/)。 ## 限额 Amazon Q 安全扫描功能可保持以下配额： + **输入构件大小**：IDE 项目工作区内所有文件的最大大小，包括第三方库、构建 JAR 文件和临时文件。 + **源代码大小**：Amazon Q 在筛选所有第三方库和不支持的文件后扫描的源代码最大大小。 下表描述了为自动扫描和完整项目扫描保持的配额。 | 资源 | 自动审查 | 文件或项目审查 | | --- | --- | --- | | 输入构件大小 | 200 KB | 500 MB | | 源代码大小 | 200 KB | 50 MB | # 使用 Amazon Q 开发者版启动代码审查 Amazon Q 可以查看您的整个文件或代码库，或者在您编写代码时自动查看代码。 在开始之前，请确保您已在支持代码审查功能的 IDE 中安装了 Amazon Q。有关更多信息，请参阅 [在 IDE 中安装 Amazon Q 开发者版扩展程序或插件](q-in-IDE-setup.md)。 **Topics** + [查看文件、项目或工作空间](#project-review) + [示例任务和提示](#code-review-prompts) + [在编写代码时审查](#auto-scan) ## 查看文件、项目或工作空间 您可以通过聊天面板发起审核，让 Amazon Q 审核特定的文件或项目。文件与项目审查同时包含基于规则的审查和生成式人工智能驱动的审查， Amazon Q 完成审核后，您可以调查问题并获取代码修复以修复问题。有关更多信息，请参阅[解决代码问题](address-code-issues.md)。 要开始审阅文件或项目，请在 IDE 中完成以下步骤： ------ #### [ JetBrains ] 1. 在 IDE 中打开要审查的文件或项目。 1. 选择 Amazon Q 图标以打开聊天面板。 1. 使用自然语言描述您要执行的代码审查类型。您可以仅审查最近的代码更改，也可以审查整个文件。代码更改是根据文件上 git diff 命令的输出来确定的。如果适用，除非另有说明，否则默认情况下，Amazon Q 只会审查您的代码更改。 1. 在 IDE 中打开代码项目或文件后，您可以输入类似以下内容： 1. **Review my code changes**— Amazon Q 将审查您的代码库中的任何代码更改 1. **Run a code review on this entire file**— Amazon Q 将审查您文件中的所有代码，而不仅仅是更改 1. **Review this repository**— Amazon Q 将审查您的整个代码库，而不仅仅是更改 有关更详细的代码审查场景和相关提示，请参阅[示例提示](#code-review-prompts)。 1. Amazon Q 将开始审查您的文件或项目。完成后，它会总结最高优先级的问题和意见。 1. 如果检测到任何问题，则会打开 “**代码问题**” 选项卡，其中列出了 Amazon Q 发现的问题。 1. 要了解有关代码问题的更多信息，请导航到 “**代码问题**” 面板。在那里，您可以执行下列操作： 1. 选择一个问题，以重定向到在其中检测到漏洞或低质量代码的文件的特定区域。 1. 要获取代码问题的解释，请选择代码问题名称旁边的放大镜图标。Amazon Q 将提供有关该问题的详细信息，并建议可插入代码中的修复方案。 1. 要修复代码问题，请选择代码问题名称旁边的扳手图标。Amazon Q 将简要解释修复方案，然后在您的代码文件中进行就地修复。您将在文件中看到代码更改，并且可以从聊天面板选择撤销该更改。 1. 您还可以使用自然语言来询问有关问题的更多信息，获取对拟议修复的解释或询问其他解决方案。 1. 有关解决代码问题的更多信息，请参阅[使用 Amazon Q 开发者版解决代码问题](address-code-issues.md)。 ------ #### [ Visual Studio Code ] 1. 在 IDE 中打开要审查的文件或项目。 1. 选择 Amazon Q 图标以打开聊天面板。 1. 使用自然语言描述您要执行的代码审查类型。您可以仅审查最近的代码更改，也可以审查整个文件。代码更改是根据文件上 git diff 命令的输出来确定的。如果适用，除非另有说明，否则默认情况下，Amazon Q 只会审查您的代码更改。 1. 在 IDE 中打开代码项目或文件后，您可以输入类似以下内容： 1. **Review my code changes**— Amazon Q 将审查您的代码库中的任何代码更改 1. **Run a code review on this entire file**— Amazon Q 将审查您文件中的所有代码，而不仅仅是更改 1. **Review this repository**— Amazon Q 将审查您的整个代码库，而不仅仅是更改 有关更详细的代码审查场景和相关提示，请参阅[示例提示](#code-review-prompts)。 1. Amazon Q 将开始审查您的文件或项目。完成后，它会总结最高优先级的问题和意见。 1. 如果检测到任何问题，则会打开 “**代码问题**” 选项卡，其中列出了 Amazon Q 发现的问题。 1. 要了解有关代码问题的更多信息，请导航到 “**代码问题**” 面板。在那里，您可以执行下列操作： 1. 选择一个问题，以重定向到在其中检测到漏洞或低质量代码的文件的特定区域。 1. 要获取代码问题的解释，请选择代码问题名称旁边的放大镜图标。Amazon Q 将提供有关该问题的详细信息，并建议可插入代码中的修复方案。 1. 要修复代码问题，请选择代码问题名称旁边的扳手图标。Amazon Q 将简要解释修复方案，然后在您的代码文件中进行就地修复。您将在文件中看到代码更改，并且可以从聊天面板选择撤销该更改。 1. 您还可以使用自然语言来询问有关问题的更多信息，获取对拟议修复的解释或询问其他解决方案。 1. 有关解决代码问题的更多信息，请参阅[使用 Amazon Q 开发者版解决代码问题](address-code-issues.md)。 ------ #### [ Visual Studio ] 1. 在 Visual Studio 中打开要扫描的项目中的文件。 1. 选择文件底部的 Amazon Q 图标以打开 Amazon Q 任务栏。 1. 从任务栏中选择**运行安全扫描**。Amazon Q 开始扫描您的项目。 在下图中，在 Visual Studio 中，用户选择 **Amazon Q** 图标，系统显示了任务栏，用户可以从中选择**运行安全扫描**。 ![\[Visual Studio 中的 Amazon Q 任务栏显示“运行安全扫描”选项\]](http://docs.aws.amazon.com/zh_cn/amazonq/latest/qdeveloper-ug/images/VS-scans.png) 1. 您的扫描状态将在 Visual Studio 输出窗格中更新。扫描完成后，您会收到通知。 有关查看和处理扫描结果的信息，请参阅[使用 Amazon Q 开发者版解决代码问题](address-code-issues.md)。 ------ ## 示例任务和提示 在启动代码审查时，您可能会遇到多种情况。以下概述了启动代码审查的一些方法以及如何提示 Amazon Q 运行您想要的审查。 + 要仅查看单个文件的代码更改，请执行以下操作： + 在 IDE 中打开该文件并输入 **Review my code** + 输入 **Review the code in ** + 要查看整个代码文件，请执行以下操作： + 打开未做任何更改的文件并输入 **Review my code** + 打开包含更改的文件并输入 **Review my entire code file** + 输入 **Review all the code in ** + 要查看仓库中的所有代码更改，请执行以下操作： + 在 IDE 中打开存储库并输入 **Review my code** + 要查看整个存储库，而不仅仅是更改，请执行以下操作： + 在 IDE 中打开存储库并输入 **Review my repository** ## 在编写代码时审查 **注意** 只有[订阅 Amazon Q 开发者版专业套餐](getting-started-q-dev.md)后，才可使用 Amazon Q 自动审查功能。 自动审查是基于规则的审查，由 [Amazon Q 检测器](https://docs.aws.amazon.com/codeguru/detector-library/)提供支持。Amazon Q 会自动审查您正在编码的文件，一旦在您的代码中发现问题，就会立即生成对应的问题记录。执行自动审查时，Amazon Q 不会就地生成代码修复方案。 使用 Amazon Q 时，自动审查功能默认处于启用状态。可通过以下步骤暂停或恢复自动审查。 **暂停和恢复自动审查** 要暂停自动审查，请完成以下步骤。 1. 从 IDE 窗口底部选择 **Amazon Q**。 Amazon Q 任务栏将打开。 1. 选择**暂停自动审查**。要恢复自动审查，请选择**恢复自动审查**。 # 使用 Amazon Q 开发者版解决代码问题 本节主题将说明如何处理和解决代码问题，以及如何忽略问题（如果适用）。 **Topics** + [在 JetBrains 和 Visual Studio Code 中解决代码问题](address-issues-jetbrains-visualstudiocode.md) + [在 Visual Studio 中解决代码问题](address-issues-visualstudio.md) # 在 JetBrains 和 Visual Studio Code 中解决代码问题 要在 JetBrains 和 Visual Studio Code 中解决代码问题，需选择生成就地修复方案，也可以生成说明以便手动更新代码。 您可以执行以下操作： + 生成就地代码修复方案 + 解释问题并获取新代码 + 忽略该问题，或忽略所有类似问题 ## 为文件生成就地代码修复方案 Amazon Q 可以就地更新您的文件，自动修复其检测到的代码问题。 要自动修复文件中的代码问题，请执行以下操作： ------ #### [ JetBrains ] 1. 在 “**问题**” 工具窗口的 “**Amazon Q Code 问题**” 选项卡中，选择您要解决的代码问题。 1. 将打开一个面板，其中包含有关代码问题的更多信息。如果适用，您将看到有关用于识别代码问题的 Amazon Q 检测器的详细信息。 1. 在面板底部，选择 “**修复**”。 1. 在聊天面板中，Amazon Q 会简要解释修复方案，然后在您的代码文件中执行就地修复。 1. 您将在文件中看到代码更改，并且可以从聊天面板选择撤销该更改。 ------ #### [ Visual Studio Code ] 1. 在**代码问题**选项卡中，选择要解决的代码问题。 1. 选择扳手图标。 下图演示了 Visual Studio Code 中某代码问题对应的扳手图标。 ![\[中代码问题的扳手图标Visual Studio Code，用于生成代码修复。\]](http://docs.aws.amazon.com/zh_cn/amazonq/latest/qdeveloper-ug/images/code-review-fix-vsc.png) 1. 在聊天面板中，Amazon Q 会简要解释修复方案，然后在您的代码文件中执行就地修复。 1. 您将在文件中看到代码更改，并且可以从聊天面板选择撤销该更改。 ------ ## 解释代码问题并获取新代码 Amazon Q 可以深入解释代码问题，并提供修复方案及随附的新代码，供您添加到文件中。 要了解代码问题的解释，请执行以下操作： ------ #### [ JetBrains IDEs ] 1. 在 “**问题**” 工具窗口的 “**Amazon Q Code 问题**” 选项卡中，选择您要解决的代码问题。 1. 将打开一个面板，其中包含有关代码问题的更多信息。如果适用，您将看到有关用于识别代码问题的 Amazon Q 检测器的详细信息。 1. 在面板底部，选择 “**解释**”。 1. 在聊天面板中，Amazon Q 提供了有关该问题的详细信息并提供了解决方法的建议，并提供了可以插入文件中的代码。 1. 要更新您的文件，请按照 Amazon Q 的说明确定添加或替换代码的位置，并将提供的代码复制到文件中的正确位置。添加更新的代码时，请务必移除易受攻击的代码。 ------ #### [ Visual Studio Code ] 1. 在**代码问题**选项卡中，选择要解决的代码问题。 1. 选择放大镜图标。 下图演示了 Visual Studio Code 中某代码问题对应的放大镜图标。 ![\[中代码问题的放大镜图标Visual Studio Code，用于解释代码问题。\]](http://docs.aws.amazon.com/zh_cn/amazonq/latest/qdeveloper-ug/images/code-review-view-details-vsc.png) 1. 在聊天面板中，Amazon Q 提供了有关该问题的详细信息并提供了解决方法的建议，并提供了可以插入文件中的代码。 1. 要更新您的文件，请按照 Amazon Q 的说明确定添加或替换代码的位置，并将提供的代码复制到文件中的正确位置。添加更新的代码时，请务必移除易受攻击的代码。 ------ ## 忽略代码问题 如果检测到的代码问题不适用，您可以选择忽略该问题，或者忽略该问题及所有类似问题（具有同一 CWE 的问题）。这些问题将从“代码问题”选项卡中移除。 要忽略代码问题，请执行以下操作： ------ #### [ JetBrains ] 1. 在 “**问题**” 工具窗口的 “**Amazon Q Code 问题**” 选项卡中，选择要忽略的代码问题。 1. 将打开一个面板，其中包含有关代码问题的更多信息。在面板底部，选择 “**忽略**”。代码问题已从 “代码问题” 面板中删除。 1. 您也可以选择 “**全部忽略**” 来忽略此问题以及同一 CWE 的其他代码问题。 ------ #### [ Visual Studio Code ] 1. 在 “**代码问题**” 选项卡中，选择要忽略的代码问题。 1. 选择忽略图标。 下图演示了 Visual Studio Code 中某代码问题对应的忽略图标。 ![\[中代码问题的忽略图标Visual Studio Code，用于忽略和关闭代码问题。\]](http://docs.aws.amazon.com/zh_cn/amazonq/latest/qdeveloper-ug/images/code-review-ignore-issue-vsc.png) 1. 代码问题已从 “代码问题” 面板中删除。 1. 要忽略类似的问题，请选择省略号图标，然后选择出现的**忽略类似问题**按钮。 ------ # 在 Visual Studio 中解决代码问题 要在 Visual Studio 中查看 Amazon Q 检测到的代码问题，请展开 Visual Studio 主菜单中的**查看**标题并选择**错误列表**，打开 Visual Studio **错误列表**。 您可以使用代码问题中的信息来更新代码。更新代码后，再次审查您的代码，确认问题是否得到解决。 默认情况下，Visual Studio **错误列表**会显示您的代码库的所有警告和错误。要从 Visual Studio **错误列表**中筛选出 Amazon Q 代码问题，请完成以下流程以创建筛选器。 **注意** 只有在您运行代码审查并且 Amazon Q 检测到问题后，代码问题才会显示。 在 Visual Studio 中，代码问题以警告形式呈现。要查看**错误列表**中 Amazon Q 检测到的问题，必须选择**错误列表**标题中的**警告**选项。 **筛选错误列表中的代码问题** 1. 从 Visual Studio 主菜单中选择“查看”，然后选择**错误列表**打开**错误列表**窗格。 1. 从**错误列表**窗格中，右键单击标题行，以打开上下文菜单。 1. 在上下文菜单中，展开**显示列**，然后在展开的菜单中选择**工具**。 1. **工具**列已添加到您的**错误列表**中。 1. 从**工具**列标题中，选择**筛选**图标并选择 **Amazon Q** 以筛选 Amazon Q 代码问题。 # 筛选代码问题 **注意** 您只能在JetBrains IDEs 和中筛选代码问题Visual Studio Code。 筛选代码问题时，“代码问题”面板中仅会显示符合所选条件的问题。您可以根据问题的严重性筛选问题，这样您就只能在面板中看到与所选严重性相关的问题。 您还可以在“代码问题”面板中控制代码问题的排列方式，可按严重性或文件位置对问题进行分组。 要筛选代码问题，请执行以下操作： ------ #### [ JetBrains IDEs ] 1. 从 **Amazon Q Code 问题**选项卡中，选择筛选器图标。 1. 将打开一个包含严重性级别的弹出式菜单。 下图显示了中 “代码问题” 选项卡中的 “严重性” 菜单IntelliJ IDEA。 ![\[中的严重性筛选器菜单IntelliJ IDEA。\]](http://docs.aws.amazon.com/zh_cn/amazonq/latest/qdeveloper-ug/images/jb-filter-issues.png) 1. 选择或取消选择要筛选的严重性级别，然后选择 “**确定”**。只有您选择的严重程度的问题才会显示在 **Amazon Q Code 问题**面板中。 ------ #### [ Visual Studio Code ] 1. 从**代码问题**面板中，选择筛选器图标。 下图演示了 Visual Studio Code 中“代码问题”选项卡对应的筛选器图标。 ![\[Visual Studio Code 中“代码问题”选项卡中的筛选器图标。\]](http://docs.aws.amazon.com/zh_cn/amazonq/latest/qdeveloper-ug/images/filter-issues-vsc.png) 1. 此时会打开**筛选问题**菜单。 选中或取消选中要筛选的严重性级别旁边的复选框，然后选择 “**确定”**。只有符合您所选严重性的问题才会显示在 “**代码问题**” 面板中。 ------ 要对代码问题进行分组，请执行以下操作： ------ #### [ JetBrains IDEs ] 1. 从 **Amazon 二维码问题**面板中，选择分组图标。 1. 将打开 “**分组依**据” 弹出式菜单。 1. 选择 “**严重性**”，在 “代码问题” 面板中根据问题的严重性对问题进行分组。选择 “**位置**”，根据议题所在的代码文件对问题进行分组。 ------ #### [ Visual Studio Code ] 1. 从**代码问题**面板中，选择分组图标。 下图演示了 Visual Studio Code 中“代码问题”选项卡对应的分组图标。 ![\[Visual Studio Code 中“代码问题”选项卡中的分组图标。\]](http://docs.aws.amazon.com/zh_cn/amazonq/latest/qdeveloper-ug/images/group-issues-vsc.png) 1. 此时会打开**分组问题**菜单。 1. 选择 “**严重性**”，在 “代码问题” 面板中根据问题的严重性对问题进行分组。选择 “**位置**”，根据议题所在的代码文件对问题进行分组。 ------ # Amazon Q 开发者版代码审查中的代码问题严重级别 Amazon Q 会为检测到的代码问题定义严重级别，帮助您确定问题的处理优先级，并跟踪应用程序的安全状态。以下章节将说明代码问题严重级别的判定方法，以及各级别对应的含义。 ## 严重级别的计算方式 代码问题的严重级别由生成该问题的检测器决定。系统会通过通用漏洞评分系统（[CVSS](https://nvd.nist.gov/vuln-metrics/cvss/v3-calculator)）为 [Amazon Q 检测器库](https://docs.aws.amazon.com/codeguru/detector-library)中的每个检测器分配一个严重级别。CVSS 会结合漏洞在实际场景中的可利用性（例如，是否可通过互联网利用、是否需要物理访问权限），以及攻击者可获取的权限级别，来评估严重程度。 下表概述了如何根据攻击者成功攻击系统所需的权限级别和努力水平来判定严重级别。 **严重性确定矩阵** | 权限级别 | 工作量水平 | 严重性 | | --- | --- | --- | | 完全控制系统或其输出 | 需要系统访问权限 | 高 | | 完全控制系统或其输出 | 努力上网 | 重大 | | 完全控制系统或其输出 | 通过互联网 | 重大 | | 访问敏感信息 | 需要系统访问权限 | 中 | | 访问敏感信息 | 努力上网 | 高 | | 访问敏感信息 | 通过互联网 | 高 | | 导致系统崩溃或效率下降 | 需要系统访问权限 | 低 | | 导致系统崩溃或效率下降 | 努力上网 | 中 | | 导致系统崩溃或效率下降 | 通过互联网 | 中 | | 提供额外安全保障 | 不可利用 | 信息 | | 提供额外安全保障 | 需要系统访问权限 | 信息 | | 提供额外安全保障 | 努力上网 | 低 | | 提供额外安全保障 | 通过互联网 | 低 | | 最佳实践 | 不可利用 | 信息 | ## 严重级别定义 严重级别定义如下： **严重：应立即解决该代码问题，以防情况恶化。** 严重的代码问题意味着攻击者能以中等程度的努力获取系统控制权或修改系统行为。建议您有限处理严重问题，您还应该考虑资源的重要程度。 **高：该代码问题必须作为近期优先事项来处理。** 高严重级别的代码问题表明，攻击者需付出较大努力才能获取系统控制权或修改系统行为。建议您将高严重级别的问题作为近期优先事项，并立即采取补救措施，您还应该考虑资源的重要程度。 **中等：该代码问题应作为中期优先事项来处理。** 中等严重级别的问题可能导致系统崩溃、无响应或不可用。建议您在方便时尽早调查相关代码，您还应该考虑资源的重要程度。 **低：该代码问题本身无需采取行动。** 低严重级别的问题通常意味着编程错误或反模式。您无需对低严重性问题立即采取行动，但是当您将它们与其他问题关联时，它们可以提供背景信息。 **信息性：无建议的操作。** 信息性问题包含关于质量或可读性改进的建议，或可选 API 操作建议。无需立即采取行动。 # 在 IDE 中使用 Amazon Q 开发者版转换代码 Amazon Q Developer 可以通过执行语言和操作系统 (OSIDEs) 级别的自动升级和转换，在集成开发环境 () 中转换您的代码。您只需提供待转换的代码，Amazon Q 便会生成相应变更；您可先查看这些变更，再将其应用到文件中。 要开始使用，需先在支持转换功能的 IDE 中安装 Amazon Q。随后，可参考对应主题，了解如何通过 Amazon Q 执行您所需的转换类型。 有关 IDEs 该支持转型以及如何安装 Amazon Q 的更多信息，请参阅[在 IDE 中使用 Amazon Q 开发者版](q-in-IDE.md)。 **Topics** + [使用 Amazon Q 开发者版转换 Java 应用程序](transform-java.md) + [使用 Amazon Q 开发者版转换 .NET 应用程序](transform-dotnet-IDE.md) # 使用 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**（时钟）图标。 # 使用 Amazon Q 开发者版转换 .NET 应用程序 Amazon Q 开发者版可通过生成式人工智能驱动的重构工作流，将您基于 Windows 的 .NET 应用程序移植为兼容 Linux 的跨平台 .NET 应用程序。此外，Amazon Q 还能帮助您将跨平台 .NET 应用程序的旧版本升级到新版本。 要转换 .NET 解决方案或项目，Amazon Q 会先分析您的代码库，确定移植应用程序所需的更新内容，并在转换开始前生成一份转换计划。在分析过程中，Amazon Q 会将您的 .NET 解决方案或项目划分为多个代码组，您可在转换计划中查看这些代码组。*代码组*指一个项目及其所有依赖项的集合，它们共同构成一个可编译的代码单元，如动态链接库（DLL）或可执行文件。 在转换期间，Amazon Q 会在转型中心提供 step-by-step更新，您可以在其中监控进度。应用程序转换完成后，Amazon Q 会生成一份摘要，并在差异视图中展示建议的变更；您可先验证这些变更（可选操作），再确认接受。确认接受变更后，Amazon Q 会对您的 .NET 解决方案或项目进行就地更新。 Amazon Q 在将 .NET 应用程序移植到 Linux 时，会执行以下四项关键任务： + **升级语言版本**：将代码中过时的 C\$1 版本替换为兼容 Linux 的 C\$1 版本。 + **从 .NET Framework 迁移到跨平台 .NET**：将依赖 Windows 的 .NET Framework 项目及包迁移到兼容 Linux 的跨平台 .NET。 + **重写代码以实现 Linux 兼容性**：对已废弃、低效的代码组件进行重构和重写。 + **生成 Linux 兼容性就绪报告**：对于需要用户干预才能让代码在 Linux 上编译和运行的开放式任务，Amazon Q 会生成一份详细报告，列出转换后配置应用程序所需执行的操作。 有关 Amazon Q 如何执行 .NET 转换的更多信息，请参阅[工作原理](how-dotnet-transformation-works.md)。 **Topics** + [配额](#quotas-dotnet-transformation) + [在 Visual Studio 中使用 Amazon Q 开发者版移植 .NET 应用程序](port-dotnet-application.md) + [Amazon Q 开发者版如何转换 .NET 应用程序](how-dotnet-transformation-works.md) + [在 IDE 中排查 .NET 转换问题](troubleshooting-dotnet-transformation-IDE.md) ## 配额 在 IDE 中使用 Amazon Q 执行 .NET 转换时，需遵守以下配额限制： + **单任务代码行数**：Amazon Q 在单个转换作业中可处理的最大代码行数。同时也是 .NET 转换的月度总行数限制。 + **并发任务数**：您可同时运行的最大转换作业数量。此配额适用于 IDE 中的所有转换操作（包括 [Java 转换](transform-java.md)）。 | 资源 | 配额 | | --- | --- | | 单任务代码行数 | 100000 行代码 | | 并发任务 | 每位用户 1 个任务 每个 AWS 账户 2 个职位 | # 在 Visual Studio 中使用 Amazon Q 开发者版移植 .NET 应用程序 按照以下步骤，在 Visual Studio 中使用 Amazon Q 开发者版将基于 Windows 的 .NET 应用程序移植为兼容 Linux 的跨平台 .NET 应用程序。 ## 步骤 1：先决条件 继续之前，请确保您已完成[在 IDE 中设置 Amazon Q](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/q-in-IDE.html) 中的步骤。 在启动 .NET 转换作业前，请确保您的应用程序满足以下先决条件： + 您的应用程序仅包含使用 C\$1 编写的 .NET 项目。 + 你的应用程序只有 Microsoft 编写的软件包依赖关系 NuGet + 您的应用程序仅使用 UTF-8 字符。如果您的应用程序使用非 UTF-8 字符，Amazon Q 仍会尝试执行代码转换。 + 如果您的应用程序依赖互联网信息服务（IIS），则仅使用默认的 IIS 配置。 + Amazon Q 会评估您所选项目的类型及其依赖项，以创建代码组。您的代码组仅支持以下项目类型： + 控制台应用程序 + 类库 + Web API + WCF 服务 + 模型视图控制器（MVC）和单页应用程序（SPA）的业务逻辑层 + 测试项目 **注意** Amazon Q 不支持转换界面层组件，例如Razor视图或 WebForms ASPX 文件。若 Amazon Q 在您的解决方案或项目中检测到 UI 层组件，会排除这些组件执行部分转换；之后您可能需要进一步重构代码，才能在目标 .NET 版本上完成编译。 ## 步骤 2：转换应用程序 要转换您的 .NET 解决方案或项目，请完成以下步骤： 1. 在 Visual Studio 中打开您想要转换的、基于 C\$1 的解决方案或项目。 1. 在编辑器中打开任意一个 C\$1 代码文件。 1. 选择**解决方案资源管理器**。 1. 在“解决方案资源管理器”中，右键单击您想要转换的解决方案或项目，然后选择**使用 Amazon Q 开发者版移植**。 1. 将显示**使用 Amazon Q 开发者版移植**窗口。 **选择要转换的解决方案或项目**下拉菜单中，会默认选中您此前选择的解决方案或项目；您可展开该菜单，选择其他需要转换的解决方案或项目。 在**选择 .NET 目标版本**下拉菜单中，选择您要升级到的 .NET 版本。 1. 选择**确认**，开始转换。 1. Amazon Q 开始转换代码。您可查看其生成的转换计划，了解应用程序的具体转换方式。 系统会打开**转换中心**，您可在整个转换过程中通过它监控进度。在 Amazon Q 完成**等待任务转换启动**步骤后，在剩余转换期间，您可离开当前项目或解决方案。 1. 转换完成后，返回**转换中心**，选择**查看差异**，在差异视图中查看 Amazon Q 建议的变更。 1. 选择**查看代码转换摘要**，了解 Amazon Q 所做变更的详细信息；您也可选择**将摘要下载为 .md 文件**，下载转换摘要。 如果**代码组**表格中的任一项目在“Linux 移植状态”下需要手动输入，您必须手动更新部分文件，才能让应用程序在 Linux 上运行。 1. 在**操作**下拉菜单中，选择**下载 Linux 就绪报告**。 1. 系统会打开一个 .csv 文件，其中列出了使应用程序兼容 Linux 前，您需对项目或解决方案完成的所有变更。它包括需更新的项目和文件、待更新项的描述、问题说明。您可参考**建议**列，了解如何解决 Linux 兼容性问题。 1. 若要对文件进行就地更新，请在**操作**下拉菜单中选择**接受变更**。 # Amazon Q 开发者版如何转换 .NET 应用程序 通过以下章节，详细了解 Amazon Q 开发者版执行 .NET 转换的工作原理。 ## 分析应用程序并生成转换计划 在转换开始前，Amazon Q 会先在本地编译您的代码，确保代码可编译且转换配置正确。然后，Amazon Q 会将您的代码上传到安全的加密构建环境 AWS，分析您的代码库，并确定移植应用程序所需的更新。 在分析过程中，Amazon Q 会将您的 .NET 解决方案或项目划分为多个代码组。代码组指一个项目及其所有依赖项的集合，它们共同构成一个可编译的代码单元，如动态链接库（DLL）或可执行文件。即便您未选择转换所有项目依赖项，Amazon Q 也会自动识别编译所选项目所需的依赖项，并一并转换，确保转换后的应用程序可编译且能直接投入使用。 代码分析完成后，Amazon Q 会生成一份转换计划，其中概述了拟执行的变更，包括待转换的代码组列表及其依赖项。 ## 转换应用程序 转换启动后，Amazon Q 会先在安全构建环境中再次编译您的代码，确保代码可远程编译。随后，Amazon Q 开始移植应用程序。转换采用“自下而上”的方式：从最低层级的依赖项开始处理。若 Amazon Q 在移植某个依赖项时遇到问题，会暂停转换并提供错误原因相关信息。 转换包含对应用程序的以下更新： + 将代码中过时的 C\$1 版本替换为兼容 Linux 的 C\$1 版本 + 将 .NET Framework 升级到跨平台 .NET，具体包括： + 识别和迭代替包、库和 APIs + 升级和更换 NuGet 软件包以及 APIs + 迁移到跨平台运行时 + 配置中间件并更新运行时配置 + 替换私有或第三方包 + 处理 IIS 和 WCF 组件 + 调试编译错误 + 重写代码以实现 Linux 兼容性，包括对已废弃、低效的代码进行重构和重写，以适配现有代码的移植需求 ## 查看转换摘要并接受变更 转换完成后，Amazon Q 会提供转换摘要，其中包含有关其对您的应用程序所做的拟议更新的信息，包括更改的文件数量、更新和 APIs 更改的软件包数量。它会标记所有未成功完成的转换（包括受影响的文件或文件片段、尝试编译时遇到的错误）。您还可查看包含编译日志的编译摘要，进一步了解已执行的变更。 转换摘要中还会提供 Linux 移植状态，用于指示应用程序要实现 Linux 兼容性是否需要额外的用户输入。若某个代码组中的任意项目需要您手动处理，可下载一份 Linux 就绪报告，其中包含 Amazon Q 在编译阶段无法解决的与 Windows 特性相关的注意事项。若任一代码组或文件需要人工干预，请查看报告以了解仍需执行的变更类型，以及（如适用）代码更新建议。这些变更必须手动完成，应用程序才能在 Linux 上运行。 在接受变更并对文件进行就地更新前，您可在差异视图中查看 Amazon Q 拟执行的变更。完成文件更新并处理 Linux 就绪报告中的所有事项后，您的应用程序即可在跨平台 .NET 环境中运行。 # 在 IDE 中排查 .NET 转换问题 通过以下章节，排查在 IDE 中使用 Amazon Q 开发者版执行 .NET 转换时的常见问题。 ## 如何判断任务是否在正常推进？ 若在“转换中心”中，Amazon Q 某个步骤耗时过长，您可通过输出日志查看任务是否仍在运行。若日志中持续生成诊断信息，则说明任务仍在正常执行。 要检查输出，请在 Visual Studio 中选择**输出**选项卡。在**显示以下来源的输出:**菜单中，选择 **Amazon Q 语言客户端**。 下方屏幕截图展示了 Amazon Q 在转换过程中生成的输出示例。 ![\[Amazon Q 开发者版代码转换中心的屏幕截图，显示了 Amazon Q 语言客户端的输出。\]](http://docs.aws.amazon.com/zh_cn/amazonq/latest/qdeveloper-ug/images/code-transform-troubleshoot4.png) ## 为何部分项目未被选中进行转换？ Amazon Q 仅支持转换 C\$1 语言编写的特定项目类型。目前，Amazon Q 不支持移植 UI 层组件，也不支持转换使用 VB.NET 或 F\$1 语言编写的项目。有关支持的项目类型及 .NET 项目转换的其他先决条件，请参阅[步骤 1：先决条件](port-dotnet-application.md#transform-dotnet-prerequisites)。 ## 若项目或解决方案无法转换，如何获取支持？ 如果您无法自行解决问题，可以联系 支持 或您的 AWS 账户 团队提交支持案例。 要获得支持，请提供转换任务 ID， AWS 以便调查失败的作业。要查找转换作业 ID，请在 Visual Studio 中选择**输出**选项卡。在**显示以下来源的输出:**菜单中，选择 **Amazon Q 语言客户端**。 ## 如何避免防火墙干扰转换作业？ 如果您所在组织使用了防火墙，可能会干扰 Visual Studio 中的转换操作。您可暂时禁用 Node.js 中的安全检查，以排查或测试阻碍转换运行的因素。 环境变量 `NODE_TLS_REJECT_UNAUTHORIZED` 控制着重要的安全检查。设置`NODE_TLS_REJECT_UNAUTHORIZED`为 “0” 会禁用 Node.js 拒绝未经授权 TLS/SSL 的证书。这意味着： + 接受自签名证书 + 允许过期证书 + 允许主机名不匹配的证书 + 忽略其他所有证书验证错误 如果您的代理使用自签名证书，可设置以下环境变量（无需禁用 `NODE_TLS_REJECT_UNAUTHORIZED`）： ``` NODE_OPTIONS = —use-openssl-ca NODE_EXTRA_CA_CERTS = Path/To/Corporate/Certs ``` 否则，您必须指定代理使用的 CA 证书，才能禁用 `NODE_TLS_REJECT_UNAUTHORIZED`。 **要在 Windows 中禁用 NODE\$1TLS\$1REJECT\$1UNAUTHORIZED，请执行以下操作：** 1. 打开“开始”菜单，搜索**环境变量**。 1. 选择**编辑系统环境变量**。 1. 在**系统属性**窗口中，选择**环境变量**。 1. 在**系统变量**下，选择**新建**。 1. 设置**变量名**为 NODE\$1TLS\$1REJECT\$1UNAUTHORIZED，**变量值**为 0。 1. 选择**确定**，保存更改。 1. 重启 Visual Studio。 # 使用 Amazon Q 开发者版解释和更新代码 Amazon Q 开发者版可以解释和更新集成式开发环境（IDE）中特定的代码行。要更新代码，使用 Amazon Q 更改给定代码行或代码块，它会生成反映您要求的更改的新代码。然后，您可以将更新的代码直接插入到源代码的文件中。 可从以下选项中进行选择： + **解释**：用自然语言解释您的代码。 + **重构**：除其他改进外，还提高了代码的可读性或效率。 + **修复**：调试代码。 + **生成测试**：为当前文件或所选代码创建单元测试。 + **优化**：增强代码性能。 + **发送到提示**：将突出显示的代码发送到 Amazon Q 聊天面板并询问代码相关问题。 ## 将代码发送到 Amazon Q 要通过 Amazon Q 解释或更新您的代码，请完成以下步骤。 1. 在 IDE 中突出显示代码文件的一部分。 1. 右键单击突出显示的代码，打开上下文窗口。选择 **Amazon Q**，然后选择**解释**、**重构**、**修复**、**生成测试**、**优化**或**发送到提示**。 如果选择**发送到提示**，Amazon Q 会将突出显示的代码复制到聊天面板，您可以在其中输入有关代码的问题。 1. 要将突出显示的代码替换为新生成的代码，您可以复制代码或通过选择**插入代码**将其直接插入到文件中。Amazon Q 将原始代码替换为更新的代码。 # 通过内联聊天与 Amazon Q 开发者版进行交互 *内联聊天*功能允许您直接在 IDE 的主编码窗口中与 Amazon Q 进行交互。要使用内联聊天功能，只需突出显示需要获取建议的代码，在弹出的小型输入界面中输入指令。Amazon Q 会继续为您生成代码，并在主编码窗口内以差异视图的形式呈现。之后，您可选择接受或拒绝这些变更。 内联聊天的优势在于，它能避免在“聊天窗口”与“主编码窗口”之间切换时产生的上下文切换问题。 通常在审查代码、编写单元测试或执行其他需要以代码形式获取答案的任务时，可使用内联聊天功能。如果您需要以文本形式获取答案（例如，想要“解释这段代码”的答案），那么使用[聊天窗口]()是更合适的选择。 通过内联聊天生成代码建议时，Amazon Q 只会考虑当前文件中的代码，不会查看其他文件或项目中的代码。 ## Amazon Q 内联聊天的实际应用 内联聊天会话如下所示。 1. 突出显示需要获取建议的代码，然后根据所使用的 IDE 选择以下选项： + 在 Visual Studio Code 和 JetBrains 中，按下 `⌘+I`（Mac）或 `Ctrl+I`（Windows） + 在 Eclipse 中，按下 `⌘+Shift+I`（Mac）或 `Ctrl+Shift+I`（Windows） + 或者，您也可以右键单击选中的代码，依次选择 **Amazon Q** 和**内联聊天** 此时主编码窗口顶部会弹出一个小型输入界面，您可以在其中输入提示词，例如 **Fix this code**。 ![\[内联聊天输入界面。\]](http://docs.aws.amazon.com/zh_cn/amazonq/latest/qdeveloper-ug/images/inline-chat-input-screen.png) 1. Amazon Q 会生成代码，并以差异视图的形式呈现。 ![\[内联聊天的差异视图。\]](http://docs.aws.amazon.com/zh_cn/amazonq/latest/qdeveloper-ug/images/inline-chat-diff.png) 1. 可以通过选择**接受**或**拒绝**来确认是否接受变更，也可以按键盘快捷键（`Enter` 或 `Esc`）。 ![\[内联聊天“接受”和“拒绝”按钮。\]](http://docs.aws.amazon.com/zh_cn/amazonq/latest/qdeveloper-ug/images/inline-chat-accept.png) ## 示例主题和问题 在线聊天始终以代码形式返回答案，因此您可以输入以下这类提示： + 为这段代码添加文档注释 + 重构这段代码 + 为这个函数编写单元测试 ## 差异视图格式 内联聊天会将差异视图分为多个区块显示：上方是现有代码，下方是建议的代码。不支持 side-by-side差异。 # 在 IDE 中为 Amazon Q 开发者版聊天添加上下文 在集成式开发环境（IDE）中与 Amazon Q 聊天时，您可以向其提供文件、文件夹等额外*上下文*，帮助 Amazon Q 定制并优化回答内容。 向 Amazon Q 提供上下文有两种方式： + **手动添加**：要手动提供上下文，请在聊天窗口中输入 **@**。**@** 将弹出“上下文选择器”弹窗，您可以从中选择需纳入上下文的内容；您也可输入 **@** 后直接开始输入文件、文件夹或其他上下文类型的名称，系统会自动补全。有关更多信息，请参阅 [手动添加的上下文类型](#context-explicit)。 + **自动添加**：要自动提供上下文，请在聊天之外单独设置上下文。此后，项目中的任何开发者在聊天窗口输入问题时，Amazon Q 都会自动参考该上下文。有关更多信息，请参阅 [自动添加的上下文类型](#context-automatic)。 Amazon Q 生成回答后，会在回答内容起始位置正上方的**上下文**下拉列表中，显示用于生成回答的文件。 ## 手动添加的上下文类型 您在聊天中输入 **@** 后，可选择以下类型的上下文： + **@workspace**：Amazon Q 会将您项目的工作区作为回答的上下文。**@workspace** 选项需先配置。有关更多信息，请参阅 [向 IDE 中的 Amazon Q 开发者版聊天添加工作区上下文](workspace-context.md)。 + **文件夹**：Amazon Q 会显示当前项目中的文件夹列表，您选择的文件夹将作为回答的上下文。 + **文件**：Amazon Q 会显示当前项目中的文件列表，您选择的文件将作为回答的上下文。 + **代码**：Amazon Q 会显示当前项目中的类、函数、全局变量列表，您选择的内容将作为回答的上下文。 + **图片**：Amazon Q 允许您添加图片作为提示词的上下文，适用于根据 UI 原型图或时序图生成代码等场景。支持的图片格式为 JPEG、PNG、GIF 或 WebP，单张图片最大尺寸为 3.75 MB，像素不超过 8000×8000。单条消息中最多可包含 20 张图片（含上下文置顶图片）。 + **提示词**：Amazon Q 会显示您已保存的提示词列表，您选择的提示词将作为回答的上下文。**提示词**选项需先进行部分配置。有关更多信息，请参阅 [将提示词保存到库中，用于 Amazon Q 开发者版聊天](context-prompt-library.md)。 ## 自动添加的上下文类型 如果您已完成以下类型上下文的设置，Amazon Q 会自动将其用于生成回答： + **项目规则**：Amazon Q 会自动将您定义的一组项目规则作为上下文。有关更多信息，请参阅 [创建用于 Amazon Q 开发者版聊天的项目规则](context-project-rules.md)。 + **自定义内容**：Amazon Q 会自动将源代码存储库作为上下文。 # 向 IDE 中的 Amazon Q 开发者版聊天添加工作区上下文 当您在集成式开发环境 (IDE) 中与 Amazon Q 聊天时，您可以将 **@workspace** 添加到问题中，以自动包含工作区代码中最相关的代码块作为上下文。Amazon Q 开发者版根据定期更新的索引来确定相关性。 借助工作区上下文，Amazon Q 增强了功能，包括定位文件、了解如何跨文件使用代码以及生成利用多个文件（包括未打开的文件）的代码。 **Topics** + [设置](#setup) + [使用工作区上下文提问](#ask-questions-workspace-context) ## 设置 在继续操作之前，请确保您安装了最新版本的 IDE。然后，您可以完成以下设置步骤。 ### 启用索引 为了将您的工作区用作上下文，Amazon Q 会创建工作区存储库的本地索引，包括代码文件、配置文件和项目结构。在编制索引期间，Amazon Q 会过滤掉非必要的文件，例如二进制文件或 `.gitignore` 文件中指定的文件。 为新工作区编制索引可能需要 5 到 20 分钟。在这段时间内，预计 IDE 中的 CPU 使用率会提高。初次编制索引后，当您对工作区进行更改时，索引会逐渐更新。 首次添加工作区上下文时，必须在 IDE 中启用索引。完成以下步骤以启用索引： 1. 在 Amazon Q 聊天面板中向您的问题添加 **@workspace**。 1. Amazon Q 会提示您启用索引。在 IDE 中选择**设置**，重定向到 Amazon Q 设置。 若未出现提示，您可在 IDE 底部选择 **Amazon Q**，然后在弹出的 Amazon Q 任务栏中选择**打开设置**。 1. 勾选**工作区索引**旁的复选框。 ### 配置索引（可选） 索引编制过程无需进行任何配置，但是您可以选择指定专用于索引的线程数。如果增加使用的线程数，索引将更快地完成，同时会占用更多的 CPU。要更新索引配置，可在**工作区索引工作线程数**设置中指定线程数量。此外，您还可以设置可用于工作区上下文索引的文件最大大小，并启用图形处理器（GPU）以加速索引过程。 ## 使用工作区上下文提问 要将您的工作区作为上下文添加到您与 Amazon Q 的对话中，请打开您要提问的相关工作区，然后在聊天面板中将 **@workspace** 添加到您的问题中。您必须在要向其添加工作区上下文的任何问题中添加 @workspace。 如果您想开始谈论其他工作区，请打开相应工作区，然后打开一个新的聊天选项卡。在问题中包含 **@workspace** 以添加新工作区作为上下文。 您可以向 Amazon Q 询问工作区中的任何文件，包括未打开的文件。除了现有的对话式编码功能外，Amazon Q 还可以解释文件、查找代码和跨文件生成代码。 以下是您可以在聊天中利用工作区上下文向 Amazon Q 提问的示例问题： + @workspace 处理授权的代码在哪里？ + @workspace 这个项目中有哪些带有应用程序逻辑的关键类？ + @workspace 解释一下 main.py + @workspace 为这个项目添加身份验证 + @workspace 这个项目中使用了哪些第三方库或软件包，用途是什么？ + @workspace 为函数添加单元测试 ** # 将提示词保存到库中，用于 Amazon Q 开发者版聊天 在 IDE 中与 Amazon Q 聊天时，您可以创建常用提示词库。将这些提示词存储在库中后，无需每次重新输入，即可轻松将其插入对话。已保存的提示词可在多个对话和项目中使用。 提示词会保存到 `~/.aws/amazonq/prompts` 文件夹中。 **要将提示词保存到提示词库中，请执行以下操作** 1. 在 IDE 中打开 Amazon Q 聊天窗口。 1. 输入 **@**，然后选择**提示词**。 1. 选择**创建新提示词**。（您可能需要向下滚动才能找到它。） 1. 在**提示词名称**中，输入提示词名称（例如 **Create\$1sequence\$1diagram**），然后按 Enter。请注意，提示名称不能包含空格。 Amazon Q 会在 `~/.aws/amazonq/prompts` 文件夹中创建一个名为 `Create_sequence_diagram.md` 的提示词文件，然后在您的 IDE 中打开该文件。 1. 在提示词文件中添加详细提示内容。例如： `Create a sequence diagram using Mermaid that shows the sequence of calls between resources. Ignore supporting resources like IAM policies and security group rules.` 1. 保存该提示词文件。 **要使用已保存的提示词，请执行以下操作** 1. 在 IDE 中打开 Amazon Q 聊天窗口。 1. 输入 **@**，然后选择**提示词**。 1. 选择你保存的提示，例如 **create\$1Sequence\$1D** iagram。 1. （可选）根据需要，在聊天输入窗口中补充细节。您可以输入更多文本，也可以添加更多类型的上下文。提示词示例可能如下所示…… `@Create_sequence_diagram using the files in the @lib folder` 1. 提交提示词，等待 Amazon Q 生成回答。 # 固定上下文内容 **注意** 目前，上下文固定功能仅在 VS Code IDE 中可用。 通过上下文固定功能，您可以指定在整个聊天会话中所有消息都会包含的上下文内容。固定某个上下文内容后，它会自动添加到当前聊天的每一条消息中，无需重复输入 **@workspace**、**@file** 或 **@folder** 等命令。 固定的上下文内容有两种来源：一是您可手动固定经常参考的内容；二是 Amazon Q 可能会自动添加上下文（例如您当前活跃的文件）以提升响应质量。固定的上下文内容会显示在聊天面板文本输入框的顶部，您可以自主移除任何不需要包含的上下文。 为确保上下文边界清晰，固定的内容仅适用于当前聊天选项卡。打开新选项卡时，您将从初始状态开始，仅包含默认固定上下文（如活跃文件）。 ## 使用固定上下文 **要添加固定上下文内容，请执行以下操作** 1. 在 IDE 中打开 Amazon Q 聊天面板。 1. 在对话中使用 **@workspace**、**@file**、**@folder** 或 **@prompt** 等上下文命令后，点击目标上下文内容进行固定。 或者，您也可以点击“@Pin Context”按钮，查看可用选项并选择要固定的上下文。 1. 固定后的上下文将显示在聊天面板顶部的固定上下文区域。 ### 固定上下文内容的方法 共有三种固定上下文内容的方式： 1. 使用“@Pin Context”菜单： + 点击聊天面板中的“@Pin Context”按钮。 + 从可用选项中选择目标上下文内容。 1. 使用上下文菜单和键盘快捷键： + 在聊天输入框中键入“@”，调出上下文菜单。 + 导航至目标上下文内容。 + 按 Option/Alt \$1 Enter 键固定所选项目。 1. 从输入提示中固定： + 如果您已在输入框中输入上下文命令（如 **@workspace**、**@file**、**@folder** 或 **@prompt**），请将鼠标指针悬停在输入框中的该上下文内容上。 + 点击该内容即可完成固定。 固定完成后，上下文内容将显示在聊天文本输入框顶部的固定上下文区域。 **要移除固定上下文内容，请执行以下操作** + 如需移除某一固定上下文内容，点击该内容标签左侧的“X”即可。此操作适用于用户手动固定的上下文内容和系统自动添加的上下文内容。 # 创建用于 Amazon Q 开发者版聊天的项目规则 在 IDE 中与 Amazon Q 聊天时，您可以创建项目规则库。这些规则用于定义团队通用的编码标准和最佳实践。例如，您可以制定一条规则，要求所有 Python 代码必须使用类型提示，或所有 Java 代码必须添加 Javadoc 注释。将这些规则存储在项目中，可确保无论开发人员经验水平如何，都能保持编码一致性。 项目规则通过项目 `project-root/.amazonq/rules` 文件夹中的 Markdown 文件定义。 创建项目规则后，只要开发者在该项目中与 Amazon Q 对话，Amazon Q 就会自动将这些规则作为上下文，生成回答时也会确保遵循这些规则。有关如何为聊天添加上下文的更多信息，请参阅[在 IDE 中为 Amazon Q 开发者版聊天添加上下文](ide-chat-context.md)。 您可以通过文件系统直接创建项目规则，也可以通过 Amazon Q 聊天界面创建。 **要通过 Amazon Q 聊天界面创建项目规则，请执行以下操作** 1. 在 IDE 中打开 Amazon Q 聊天面板。 1. 在聊天输入框中，点击**规则**按钮。 1. 选择**创建新规则**。 1. 在弹出的对话框中，为规则输入名称。 系统会在项目的 `project-root/.amazonq/rules` 文件夹中，创建一个以此名称命名的 Markdown 文件。 1. 在编辑器中添加规则内容。 1. 保存该文件。 **要通过文件系统创建项目规则，请执行以下操作** 1. 在 IDE 中打开项目的根文件夹。 1. 在项目根文件夹中，创建以下文件夹： `project-root/.amazonq/rules` 该文件夹用于存储所有项目规则。 1. 在 `project-root/.amazonq/rules` 路径下，创建一个项目规则文件。它必须为 Markdown 文件。例如： `cdk-rules.md` 1. 打开项目规则 Markdown 文件。 1. 在文件中添加详细的提示。例如： ``` All Amazon S3 buckets must have encryption enabled, enforce SSL, and block public access. All Amazon DynamoDB Streams tables must have encryption enabled. All Amazon SNS topics must have encryption enabled and enforce SSL. All Amazon SNS queues must enforce SSL. ``` 1. 保存该文件。 1. （可选）添加更多项目规则 Markdown 文件。 至此，您已创建一个或多个项目规则。此后，只要开发者在该项目中与 Amazon Q 对话，Amazon Q 就会自动将这些规则作为上下文使用。 **要在 Amazon Q 聊天界面中管理规则，请执行以下操作** 1. 在 IDE 中打开 Amazon Q 聊天面板。 1. 在聊天输入框中，点击**规则**按钮，查看所有可用规则。 1. 点击某条规则，可切换其在当前聊天会话中的“启用/禁用”状态： + 带有勾选标记的规则为“已启用”状态，会应用于当前对话。 + 无勾选标记的规则为“已禁用”状态，在当前会话中不生效。 # 为 Amazon Q 聊天生成存储库 Amazon Q 可以自动生成存储库文件，这些文件可提供项目结构、技术堆栈和产品信息的快速索引。此功能可分析项目中的关键文件以创建摘要文件，从而帮助 Amazon Q 了解您的代码库，而不必在每次提问时都分析整个项目。 生成存储库文件时，Amazon Q 会在下方创建一个`memory-bank`子文件夹`.amazonq/rules`，其中包含以下自动生成的文件： + `product.md`— 您的项目及其功能概述。 + `structure.md`— 项目的架构、文件夹组织和关键组件。 + `tech.md`— 您的技术堆栈、框架、依赖关系和编码标准。 + `guidelines.md`— 您的项目的开发标准和模式。 当您与 Amazon Q 聊天时，这些文件会自动用作背景信息，为其提供有关您的项目的背景信息。 ## 为您的项目生成存储库 要生成存储库，请完成以下步骤。 1. 在 IDE 中打开 Amazon Q 聊天面板。 1. 在聊天输入框中，选择**规则**按钮。 1. 选择 “**生成存储库**”。 1. 将打开一个新的聊天选项卡，Amazon Q 开始分析您的项目以创建存储库文件。 1. 完成后，您可以通过选择 “**规则**” 按钮来查看文件。 当你提问时，你可以选择和取消选择要用作上下文的单个文件。 1. 如果您的项目发生变化，您可以让 Amazon Q 生成新的存储库文件来更新其上下文。为此，请选择 “**规则**” 按钮，然后选择 “**重新生成存储库**”。 ## 自定义存储库生成 您可以通过创建自定义项目规则来自定义存储库文件的生成方式。例如，您可以创建一条规则，为生成的文件指定语言或格式： ``` When generating the memory bank files like product.md, structure.md, and tech.md, always generate content in Spanish and include detailed code examples. ``` 将存储库规则保存在项目`project-root/.amazonq/rules`文件夹中的文件中。 有关创建自定义项目规则的更多信息，请参阅[创建用于 Amazon Q 开发者版聊天的项目规则](context-project-rules.md)。 # Amazon Q 开发者版中的聊天历史记录压缩功能 在 IDE 中与 Amazon Q 开发者版交互时，对话内容会不断累积到聊天历史记录中。这些历史记录是重要的上下文，能帮助 Amazon Q 理解您的项目并提供更贴合需求的响应。但底层模型对每次请求中可包含的对话历史量存在限制。 ## 理解上下文窗口限制 上下文窗口指 Amazon Q 单次交互中可处理的最大信息量，包含以下内容： + 您当前的问题或请求 + 对话中的过往消息 + 您共享的代码片段和文件 + 关于您项目的系统信息 当上下文窗口接近容量上限时，Amazon Q 引用对话前期内容的能力可能会受到影响。 ## 聊天历史记录压缩的工作原理 聊天历史记录压缩功能可在保留对话关键信息的同时，减少上下文的使用量。压缩过程如下： 1. Amazon Q 分析您的对话历史记录 1. 生成包含关键点、问题和决策的简洁摘要 1. 该摘要会替代上下文窗口中的详细对话历史记录 1. 完整对话仍可在聊天界面中查看 通过压缩，您无需在达到上下文窗口限制时开启全新聊天，即可继续当前对话且不丢失重要上下文。 ## 使用聊天历史记录压缩功能 您可通过两种方式使用压缩功能： ### 手动压缩 要手动压缩聊天历史记录，请执行以下操作： 1. 在聊天输入框中输入 **/compact** 1. Amazon Q 会处理您的请求，并显示确认消息，同时附带压缩后对话的摘要 当您希望继续当前对话，但发现响应速度变慢或回答相关性降低时，可使用手动压缩。 ### 自动压缩提示 当上下文窗口容量达到约 80% 时，Amazon Q 会显示提示压缩的通知。该通知包含： + 推荐压缩的原因说明 + 可立即触发压缩的按钮 ## 压缩后的情况 完成压缩后： + 在当前会话结束前，完整对话历史记录仍可在聊天界面中查看 + Amazon Q 生成响应时会使用压缩后的摘要（而非完整历史） + 上下文窗口中会包含压缩摘要，而非详细历史记录 + 重启 IDE 后，详细的聊天历史记录将重置 ## 相关命令 ### 清除聊天历史记录 除压缩外，您也可使用 **/clear** 命令彻底清除聊天历史记录： 1. 在聊天输入框中输入 **/clear** 1. Amazon Q 会从显示界面和上下文窗口中移除所有过往对话历史记录 ### 压缩与清除历史记录的选择场景 选择压缩的情况： + 您希望继续当前的对话主体 + 过往上下文对当前任务仍有意义 + 您希望保留对话的整体方向和核心信息 选择清除历史记录的情况： + 您要开启全新任务或主题 + 过往对话已不再相关 + 您希望确保过往上下文不会影响新响应 + 您需要从对话中移除潜在敏感信息 # 查看、删除和导出 Amazon Q 开发者版对话历史记录 在集成式开发环境（IDE）中与 Amazon Q 对话时，Amazon Q 会将每个对话选项卡保存为独立的对话记录。您可以查看、搜索和删除这些对话记录，也可以将其导出为 Markdown 或 HTML 格式的文件。 Amazon Q 会将您的对话记录存储在本地计算机的主目录中。 Amazon Q 会为每个工作区单独保存对话记录，因此如果您无法看到对话历史记录，可能是因为当前处于错误的工作区。Amazon Q 仅显示当前工作区的对话历史记录。 请按照以下说明查看、搜索、删除和导出对话记录。 **要查看和搜索过往对话，请执行以下操作** 1. 在 IDE 中登录 Amazon Q。 1. 打开 Amazon Q 聊天选项卡。 1. 通过以下任一方式打开聊天历史记录： + 在聊天面板的右上角，选择**查看聊天历史记录**按钮。 + 按下 `ctrl+F`（Windows 和 Linux）或 `⌘ F`（Mac）。 1. 请执行以下操作之一： + 选择您想要查看的对话。对话按日期分类。 + 使用聊天历史记录顶部附近的搜索栏查找对话。Amazon Q 会匹配与您输入文本完全一致的对话。 **要删除单个对话，请执行以下操作** 1. 在 IDE 中登录 Amazon Q。 1. 请执行以下操作之一： + 若已打开某个聊天会话的选项卡，在输入框中输入 **/clear**，即可删除该选项卡中的聊天内容。 + 打开一个 Amazon Q 聊天选项卡，然后通过以下任一方式打开聊天历史记录： + 在聊天面板的右上角，选择**查看聊天历史记录**按钮。 + 按下 `ctrl+F`（Windows 和 Linux）或 `⌘ F`（Mac）。 在想要删除的对话旁，点击垂直省略号（⋮），然后选择**删除**。 **要将对话导出为 Markdown 或 HTML 格式，请执行以下操作** 1. 在 IDE 中登录 Amazon Q。 1. 请执行以下操作之一： + 若已启动某个聊天会话，在聊天面板的右上角，点击**导出**按钮，即可导出当前选项卡中显示的对话。 + 打开一个 Amazon Q 聊天选项卡，然后通过以下任一方式打开聊天历史记录： + 在聊天面板的右上角，选择**查看聊天历史记录**按钮。 + 按下 `ctrl+F`（Windows 和 Linux）或 `⌘ F`（Mac）。 在想要导出的对话旁，点击垂直省略号（⋮），然后选择**导出**，即可将对话导出为 Markdown 或 HTML 格式的文件。 默认情况下，Amazon Q 会将文件命名为 `q-dev-chat-yyyy-mm-dd.md|html`，并保存到您项目的根目录中。 # 在与 Amazon Q 开发者版的聊天中使用快捷键 Amazon Q 提供键盘快捷键，帮助您高效地与代理聊天界面交互。使用快捷键可让您无需在键盘和鼠标之间切换，从而保持工作流的连贯性。 **注意** 键盘快捷键目前仅在 Visual Studio Code IDE 中可用。 ## 键盘快捷键 **Amazon Q 聊天的键盘快捷键** | 操作 | Visual Studio Code 快捷键 | | --- | --- | | 执行命令 | Shift \$1 Cmd \$1 Enter (Mac) Shift \$1 Ctrl \$1 Enter (Windows) Shift \$1 Meta \$1 Enter (Linux) | | 拒绝命令 | Shift \$1 Cmd \$1 R (Mac) Shift \$1 Ctrl \$1 R (Windows) Shift \$1 Meta \$1 R (Linux) | | 停止生成 | Shift \$1 Cmd \$1 Backspace (Mac) Shift \$1 Ctrl \$1 Backspace (Windows) Shift \$1 Meta \$1 Backspace (Linux) | ## 自定义键盘快捷键 您可通过 IDE 中的标准键盘快捷键自定义界面修改快捷键。Amazon Q 采用各 IDE 原生的快捷键系统，因此您所做的任何修改都会同步反映在 Amazon Q 界面中。工具提示和 UI 元素中显示的快捷键会自动更新，与您的自定义按键映射保持一致。 ## 快捷键查找方式 Amazon Q 提供多种方式帮助您查找键盘快捷键： + **工具提示**：请将鼠标指针悬停在“执行命令”按钮、“拒绝命令”按钮或“停止”按钮上，即可查看当前对应的键盘快捷键 + **设置界面**：在 IDE 的键盘快捷键自定义界面中，可查看所有快捷键的完整列表 ## 快捷键行为规则 + 仅当焦点位于 Amazon Q 对话面板中时，代理聊天相关的键盘快捷键才会生效 + 此设计可避免与 IDE 已有的按键绑定产生冲突 + 如果您修改了快捷键，可能需要刷新 IDE，才能让工具提示中显示的快捷键同步更新为修改后的内容 # 在 IDE 中为 Amazon Q 聊天选择模型 在 IDE 中与 Amazon Q 聊天时，您可以选择希望其使用的模型。所选模型将在后续所有对话会话中持续生效。 下表介绍了 IDE 中 Amazon Q 聊天可用的模型及其上下文窗口信息。 **** | 模型 | 上下文窗口 | | --- | --- | | Claude Sonnet 3.7 | 200K | | Claude Sonnet 4（默认） | 200K | ## 在 IDE 中选择聊天所用模型 要选择 IDE 中 Amazon Q 聊天时使用的模型，请执行以下操作： 1. 在 IDE 中打开 Amazon Q 聊天面板。 1. 在文本框底部，选择模型菜单下拉列表。从可用选项中选择您希望使用的模型。 所选模型将持续生效，直至您手动更改。 ## 上下文窗口 上下文窗口指 Amazon Q 处理并响应您的请求时可调用的上下文总量，包括您的对话历史记录以及所有显式或自动获取的上下文。上下文以令牌为计量单位，涵盖文本和代码内容。 有关上下文的更多信息，请参阅[为聊天添加上下文](ide-chat-context.md)。