透過使用 GitHub Copilot 現代化重新架構專案

本文說明如何利用 GitHub Copilot 現代化中的重構架構功能，將專案從舊框架重寫為現代架構，例如從 Struts 到 Spring MVC。

概觀

重新架構功能讓你能利用 AI 驅動的多代理工作流程，將整個專案從舊有框架轉變為現代架構。 與其手動逐檔遷移，不如用自然語言描述所需的轉換，現代化代理則負責分析、規劃與程式碼產生。

常見的重新架構情境包括：

  • Struts 到 Spring MVC
  • 從 Struts 遷移至 Spring Boot
  • 從 JSP 過渡到 Thymeleaf
  • EJB到Spring Boot
  • 將 WebSphere 應用程式遷移至 Spring Boot
  • 從傳統的 Servlet 型應用程式過渡到現代的 Spring 架構
  • Windows Forms（WinForms）桌面應用程式到 Angular 網頁應用程式
  • 從 ASP.NET MVC 前端應用程式到 Angular 網頁應用程式

先決條件

  • Visual Studio Code 已安裝 GitHub Copilot 現代化擴充功能。
  • 一個 GitHub Copilot 訂閱。 更多資訊請參閱Copilot計畫。
  • （可選）Python 3.7 或更高版本用於建立知識圖譜，讓代理人在重寫過程中更清楚理解專案結構。 如果沒有 Python，知識圖譜步驟會被跳過。
  • （可選） Node.js 18 或更高版本，用於執行 Playwright 測試作為執行時驗證的一部分。 如果無法取得 Node.js，則會跳過 Playwright 測試步驟。
  • （可選）Docker Desktop 用於執行時驗證。 若無法使用 Docker，則跳過執行時驗證步驟。

使用重新架構代理程式

請使用 GitHub Copilot Chat 面板中的 modernize 代理程式。

請依照以下步驟重新設計專案：

  1. 在 Visual Studio Code 中開啟你的專案。

  2. 打開 GitHub Copilot Chat面板。

  3. 從代理程式清單中選取 modernize 代理程式。

  4. 描述你想要進行的轉換。 例如：

    Rewrite the entire project from Struts to Spring MVC using rearchitecture agent

代理人協調多代理人團隊，執行以下步驟：

  1. 分析 - 檢視現有程式碼庫，識別框架模式、依賴關係及模組邊界。
  2. 規劃 - 產生結構化的實施計畫，包含有序任務與需求可追溯性。
  3. 執行 - 依照計畫執行程式碼轉換，並在每步進行驗證檢查。

這很重要

分析與規劃階段結束後，客服會暫停並要求你確認後才開始程式碼產生。 此時請仔細檢視計畫。 你可以在代理人繼續實施前，請求修改計畫、調整優先順序或新增限制。

提供更多背景

你可以透過在提示中提供更多上下文來改善轉換結果：

  • 指定目標框架版本，例如「使用 Spring Boot 3.2 和 Java 21。」
  • 參考文件連結或遷移指南。
  • 描述組織特定的模式或慣例。
  • 指定優先處理哪些模組或套件。

例如：

Rewrite the entire project from Struts to Spring MVC using Spring Boot 3.2.
Refer to the Spring MVC migration guide at https://docs.spring.io/spring-framework/reference/web/webmvc.html.
Keep the existing backend business logic unchanged.

常見問題疑難排解

在重新架構的過程中，代理會在你的專案目錄中產生構件 .github/modernize/ 。 出現問題時，利用這些資源來診斷。

審查產生的產物

該 .github/modernize/rearchitecture 目錄包含以下主要資源：

  • board.md - 追蹤每個階段及其狀態的任務板。 請查看此檔案，了解哪些任務通過、失敗或需要迭代。
  • artifacts/ - 每項任務的詳細報告。 檔案遵循命名慣例，例如 t21-tester-report.md 初始測試報告或 t21.2-tester-report.md 重試迭代。
  • learn.md - 每個角色在任務執行期間記錄的發現、錯誤發現與技術的累積知識庫。 請查看此檔案，了解客服遇到的問題及其解決方法。
  • team/ - 角色專屬章程，定義每位代理人的職責。

當品質閘失敗時，代理會產生迭代工件（例如， t21.1） t21.2來記錄修復嘗試。 尋找這些編號迭代，以了解問題是如何被偵測並解決的。

檢視分析與計畫

在客服開始寫程式碼之前，它會產生分析和規劃的產物，你應該先檢視。 這些產物讓你能看到代理人對你的專案的理解，以及它打算打造什麼。

分析產物包括：

  • 架構摘要：現有技術堆疊、專案結構、資料模型及整合點的概述。 請查看此摘要，以確認代理人正確識別您專案的關鍵組成部分。 尋找 artifacts/t2-architect-architecture-summary.md、artifacts/t2-architect-tech-stack.md和 artifacts/t2-architect-data-model.md等檔案。
  • 功能清單：原始應用程式中所有功能目錄，每個功能分配需求 ID（例如）。 REQ-001 請確認這份清單是否完整且準確。 尋找 artifacts/t3-pm-spec.md。
  • 目標架構設計：新應用程式的建議 API 合約、模組結構及技術選擇。 尋找像是 artifacts/t5-architect-api-contracts.md 和 artifacts/t5-architect-integration.md的檔案。

規劃資料包括：

  • 實施計畫：一份有序的任務清單，並以相依關係分階段進行。 每個任務都會對應到功能清單中的一個或多個需求。 尋找 artifacts/t7-teamlead-plan.md。
  • 測試策略：針對單元測試、整合測試及端對端測試的規劃方法。 尋找 artifacts/t7-teamlead-testing-strategy.md。

代理程式在生成這些構件後暫停，等待你的確認。 利用這個機會：

  • 確認庫存中沒有缺少任何功能。
  • 檢查目標架構是否符合你的期望。
  • 在實作開始前調整任務優先順序或增加限制。

在此階段仔細審查有助於避免在實施與驗證階段進行昂貴的重工。

建置與啟動失敗

若轉換後的應用程式無法編譯或啟動，請採用以下方法：

  1. 檢查測試器報告中的工件（例如，t21-tester-report.md）以確認是否有建置輸出和堆疊追蹤。
  2. 在產物中搜尋異常類型或錯誤訊息，以找出根本原因。
  3. 如果代理建立了修正迭代（例如，t21.1、t21.3），請審查那些產出物，看看嘗試了哪些變更。

常見的根本原因包括舊有類別與新產生類別間的命名衝突、錯誤的 Spring 配置檔配置，以及 中缺少或衝突的 pom.xml依賴關係。 例如，如果舊有控制器和現代控制器共用類別名稱，Spring 在啟動時會拋出 a ConflictingBeanDefinitionException 。

執行階段錯誤

如果應用程式啟動但 API 呼叫會回傳錯誤（例如 500 或 400 個回應），則可採用以下方法：

  1. 檢查測試器報告工件中失敗的端點及相關錯誤訊息。
  2. 檢視安全發現工件（例如 t20-security-findings.md）以找出設定問題。
  3. 檢查產生的實體類別與控制器程式碼，檢查資料庫結構與 ORM 映射之間的不符。

常見的根本原因包括在 @Column 註解中出現的資料庫保留關鍵字衝突、DTO 字段類型與實體字段類型不符，以及請求物件上缺少驗證註解。

品質閘失效與迭代

代理在重新架構過程中強制執行多個品質閘。 當閘門失敗時，代理程式會自動建立修正任務並重試驗證。 常見的閘極故障包括：

  • 架構審查：代理檢查實作是否符合設計的 API 合約、DTO 結構及端點映射。 失敗通常包括缺少端點、欄位被重新命名或驗證註解缺失。 檢視建築師報告中的產出物（例如 t19-architect-review.md）以找出具體發現。
  • 合規審查：代理人驗證實施符合初始章程中定義的所有原則。 常見的失敗是，當章程要求時，卻缺少瀏覽器層級的端對端測試。 檢視小組領導審查工件（例如 t22-teamlead-review.md），找出哪些原則未被滿足。
  • 功能一致性簽核：經辦人驗證所有目錄需求均已實作。 部分簽核代表特定功能不完整，例如缺少跨欄位驗證，例如確保 fromDate 位於 toDate 之前。 請檢視 PM 簽核的文檔（例如 t23-pm-signoff.md），以便逐項了解需求的分解情況。

如果代理程式在未解決所有問題的情況下達到迭代上限，請檢視最新的工件檔案以了解剩餘的缺口並手動修正。

執行時驗證的前提條件

代理程式執行可選的執行時驗證步驟，依賴外部工具。 若工具無法使用，則跳過相應步驟：

  • Python 未安裝：跳過知識圖譜步驟。 代理程式仍能執行重新架構，但可能對專案結構的資訊不足。 安裝 Python 3.7 或更新版本，並確保 python3 在你的 PATH 中可用。
  • Node.js 未安裝：跳過 Playwright 瀏覽器層級的端對端測試。 代理程式仍透過 Maven 執行整合測試。 安裝 Node.js 18 或更新版本以啟用瀏覽器測試。
  • Docker 不可用：執行時驗證（在容器中啟動應用程式並驗證其是否提供請求）會被跳過。 該代理程式改依賴單元測試與整合測試。 安裝並啟動 Docker Desktop 以啟用此步驟。

局限性

請留意以下限制：

  • 複雜專案與深度耦合的舊有框架可能需要多次迭代。
  • 你應該在提交變更前仔細審查已產生的程式碼。

提供意見反應

如果你對重構功能有任何回饋，請在 github-copilot-appmod 倉庫 建立問題，或使用 GitHub Copilot 現代化回饋表單。

參見

GitHub Copilot Java 現代化概觀

  • 上次更新時間：