使用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 窗体（WinForms）桌面应用程序迁移到 Angular Web 应用程序
  • 将 ASP.NET MVC 前端应用程序迁移到 Angular Web 应用程序

先决条件

  • Visual Studio Code安装了 GitHub Copilot 现代化扩展。
  • GitHub Copilot订阅。 欲了解更多信息，请参阅 Copilot 计划。
  • （可选） Python 3.7 或更高版本用于生成知识图，这使代理在重写过程中更清楚地了解项目结构。 如果Python不可用，则会跳过知识图步骤。
  • （可选） Node.js 18 或更高版本，用于在运行时验证过程中运行 Playwright 测试。 如果 Node.js 不可用，则跳过 Playwright 测试步骤。
  • （可选）用于运行时验证的 Docker Desktop 。 如果 Docker 不可用，则会跳过运行时验证步骤。

使用重构代理

在 GitHub Copilot 对话助手 面板中使用 modernize 代理。

使用以下步骤重新构建项目：

  1. 在 Visual Studio Code 中打开项目。

  2. 打开 GitHub Copilot 对话助手 面板。

  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 - 任务执行期间每个角色记录的发现、bug 发现和技术的累积知识库。 检查此文件，了解代理遇到的问题及其解决方式。
  • 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.1t21.3），请查看这些项目以查看尝试了哪些更改。

常见的根本原因包括旧类和新生成的类之间的命名冲突、错误的 Spring 配置文件配置以及缺少或冲突的 pom.xml依赖项。 例如，如果旧控制器和新式控制器共享相同的类名称，Spring 会在启动时引发 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 或更高版本，并确保 PATH 中提供了 python3。
  • 未安装Node.js：跳过 Playwright 浏览器级端到端测试。 代理仍通过 Maven 运行集成测试。 安装 Node.js 18 或更高版本以启用浏览器测试。
  • Docker 不可用：跳过运行时验证（在容器中启动应用程序并验证它为请求提供服务）。 该代理依赖单元测试和集成测试。 安装和启动 Docker Desktop 以启用此步骤。

局限性

请记住以下限制:

  • 具有深度耦合旧框架的复杂项目可能需要多次迭代。
  • 提交更改之前，应仔细查看生成的代码。

提供反馈

如果有任何关于重构功能的反馈，请在 github-copilot-appmod 存储库提交问题，或使用 GitHub Copilot 现代化反馈表单。

另见

GitHub Copilot Java 现代化概述

  • Last updated on