本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 使用 Amazon Q Developer 升級 Java 版本
Amazon Q Developer 可在整合式開發環境 (IDE) 中，將您的 Java 應用程式升級至較新的語言版本。Amazon Q 可進行變更來升級您的程式碼，這些變更包括更新已棄用的程式碼元件和 API，以及升級程式碼中的程式庫、架構和其他相依性。
為了轉換您的程式碼，Amazon Q 會先在來源語言版本中建置您的程式碼，並確認其包含執行轉換所需的資訊。Amazon Q 成功轉換程式碼後，您可以在 IDE 中驗證和接受變更。由於 Amazon Q Developer 會進行必要的最低程度變更，讓升級後的程式碼與目標 JDK 相容，因此需要額外的轉換才能升級專案的程式庫和相依性。如需 Amazon Q 如何轉換程式碼的詳細資訊，請參閱 [Amazon Q Developer 如何轉換程式碼以進行 Java 語言升級](how-CT-works.md)。
**Topics**
+ [支援的 Java 升級和 IDE](#supported-languages-IDEs)
+ [步驟 1：事前準備](#java-upgrade-prerequisites)
+ [步驟 2：設定您的專案](#configure-project)
+ [步驟 3：建立相依性升級檔案 (選用)](#create-dependency-upgrade-file)
+ [步驟 4：轉換您的程式碼](#transform-code-java)
+ [Amazon Q Developer 如何轉換程式碼以進行 Java 語言升級](how-CT-works.md)
## 支援的 Java 升級和 IDE
Amazon Q 目前針對轉換支援下列 Java 原始程式碼版本和目標版本。將程式碼轉換為相同 Java 版本的過程包括升級原始程式碼版本中的程式庫和其他相依性。
**支援的 Java 升級**
| 原始程式碼版本 | 支援的目標版本 |
| --- | --- |
| Java 8 | Java 17 和 Java 21 |
| Java 11 | Java 17 和 Java 21 |
| Java 17 | Java 17 和 Java 21 |
| Java 21 | Java 21 |
Amazon Q 在下列 IDE 中支援 Java 升級：
+ JetBrains IDE 中的模組
+ Visual Studio Code 中的專案和工作空間
## 步驟 1：事前準備
繼續進行之前，請確定您已完成[在 IDE 中設定 Amazon Q ](q-in-IDE-setup.md)中的步驟。
在您開始程式碼轉換任務之前，務必確定符合以下先決條件：
+ 您的專案是以[支援的 Java 版本](#supported-languages-IDEs)撰寫，並以 Maven 為基礎建置。
+ 您的專案已在您的 IDE 中使用 Maven 成功建置。目前支援 Maven 3.8 或更新版本。
+ 您的專案來源 JDK 可在本機使用，且是原始程式碼的版本。例如，若您要轉換 Java 8 程式碼，則本機 JDK 安裝應為 JDK 8。
+ 您的專案會在 55 分鐘內建置完成。
+ 您的專案已正確設定，並已指定正確的 JDK 版本。如需詳細資訊，請參閱[步驟 2：設定您的專案](#configure-project)。
+ 您的專案不需要存取您私有網路上的資源，包括虛擬私有雲端 (VPC) 或內部部署網路。例如，若您的專案包含會連線至您網路中資料庫的單元測試，則轉換將會失敗。
+ 您的專案不會在 Java 專案中使用封裝 Java 以外語言的外掛程式。例如，如果您的專案除了 Java 原始程式碼之外，還使用 [frontend-maven-plugin](https://github.com/eirslett/frontend-maven-plugin) 執行前端 JavaScript 程式碼，則轉換將會失敗。
+ 您的本機網路允許上傳至 Amazon Q 用來轉換程式碼的 Amazon S3 儲存貯體。如需詳細資訊，請參閱[允許存取資料周界中的 Amazon S3 儲存貯體](firewall.md#data-perimeters)。
+ 您的應用程式僅使用 UTF-8 字元。如果您的應用程式使用非 UTF-8 字元，Amazon Q 仍會嘗試轉換您的程式碼。
## 步驟 2：設定您的專案
若要設定專案，請針對您要使用的 IDE 使用下列資訊。
### 在 JetBrains 中設定專案
若要在 JetBrains 中設定專案，您可能需要指定下列專案和模組設定。
如果您的模組與專案使用相同的 JDK 和語言層級，則不需要更新模組設定。
+ 專案 SDK - 用來編譯專案的 JDK。
+ 專案語言層級 - 專案中使用的 Java 版本。
+ 模組 SDK - 用來編譯模組的 JDK。
+ 模組語言層級 - 模組中使用的 Java 版本。
+ Maven Runner JRE - 您用來建置模組的 JDK。
**更新專案和模組設定**
若要更新專案或模組的 SDK 和語言層級設定，請完成下列步驟：
1. 從您的 JetBrains IDE 中選擇**檔案**，然後選擇**專案結構**。
1. 「專案結構」視窗隨即開啟。在**專案設定**下，選擇**專案**。
1. 若要更新您的專案 JDK，請從 **SDK** 旁的下拉式清單中選擇。
1. 若要更新您的專案語言，請從**語言層級**旁的下拉式清單中選擇。
1. 請在 **Project Settings (專案詳細資訊)** 下選擇 **Modules (模組)**。
1. 若要更新您的模組 JDK，請從 **SDK** 旁的下拉式清單中選擇。
1. 若要更新您的模組語言，請從**語言層級**旁的下拉式清單中選擇。
如需詳細資訊，請參閱 JetBrains 文件中的[專案結構設定](https://www.jetbrains.com/help/idea/project-settings-and-structure.html)和[模組結構設定](https://www.jetbrains.com/help/idea/configure-modules.html)。
**更新 Maven 設定**
若要更新 Maven Runner JRE，請完成下列步驟：
1. 從您的 JetBrains IDE 中選擇齒輪圖示，然後在出現的功能表中選擇**設定**。
1. 在**設定**視窗中選擇**建置、執行、部署**，然後依序選擇**建置工具**、**Maven**、**執行器**。
1. 在 JRE 欄位中，選擇用來建置您要轉換之模組的 JDK。
### 在 VS Code 中設定專案
若要在 VS Code 中設定專案，您的專案必須包含下列項目：
+ 專案根資料夾中的 `pom.xml` 檔案
+ 專案目錄中的 `.java` 檔案
如果您的專案包含 Maven 包裝函式可執行檔 (`mvnw` 適用於 macOS，或 `mvnw.cmd` 適用於 Windows)，請確定其位於專案的根目錄。Amazon Q 將使用包裝函式，而且不需要其他 Maven 組態。
如果您不使用 Maven 包裝函式，請安裝 Maven。如需詳細資訊，請參閱 Apache Maven 文件中的[安裝 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)。
**注意**
在程式碼轉換期間，請勿關閉、關上或讓本機電腦進入睡眠狀態。初始和驗證組建會使用用戶端環境，因此需要穩定的網路連線。
若要升級程式碼專案或模組的程式碼語言版本，請針對您的 IDE 完成下列步驟。
------
#### [ 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 程式碼 ]
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 開始進行轉換。您可以在 **Transformation Hub** 索引標籤上檢視進度。
1. 轉換完成後，**提議的變更**索引標籤便會開啟。若要在更新專案之前驗證升級後的程式碼，請選擇**下載提議的變更**。選擇檔案以開啟包含原始程式碼和升級後程式碼的差異檢視。
1. 若要接受 Amazon Q 所做的變更，請前往**提議的變更**索引標籤，然後選擇**接受**。
1. 若要取得程式碼如何升級和建議的後續步驟的詳細資訊，請在 **Transformation Hub** 上選擇**檢視和更多動作**省略符號按鈕，然後選擇**顯示轉換摘要**。
------
# Amazon Q Developer 如何轉換程式碼以進行 Java 語言升級
為了轉換您的程式碼，Amazon Q Developer 會產生轉換計畫，並利用該計畫來升級專案的程式碼語言版本。轉換程式碼之後，它會提供轉換摘要和檔案差異，供您在接受變更之前檢閱變更。由於 Amazon Q Developer 會進行必要的最低程度變更，讓升級後的程式碼與目標 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
Amazon Q 會進行必要的最低程度變更，讓您的程式碼與目標 Java 版本相容。一旦 Amazon Q 執行最低 JDK 升級，您就可以初始化另一次轉換來升級所有第三方相依性。或者，您可以在 YAML 檔案中指定第三方相依性及其版本，以在程式庫升級轉換期間僅升級這些相依性。
升級程式碼時，Amazon Q 會嘗試進行下列變更：
+ 根據目標 Java 版本建議更新已棄用的程式碼元件
+ 將熱門程式庫和架構升級至與目標 Java 版本相容的版本。這包括將下列程式庫和架構更新為其最新的可用主要版本：
+ Apache Commons IO
+ Apache HttpClient
+ bc-fips
+ Cucumber-JVM
+ 休眠
+ 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
+ 測試
**注意**
請勿在程式碼轉換期間關閉或關上本機電腦，因為用戶端組建需要穩定的網路連線。
## 在本機環境中建置程式碼
在轉換期間，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 檢閱部分更新的檔案，並提供新的程式碼來解決問題，例如編譯錯誤。您也可以使用[特徵開發](q-in-IDE-chat.md#develop-code)和[工作區內容](workspace-context.md)等功能，將更多專案納入內容，並一次取得多個檔案的建議。