Re-arquitetar projetos usando o GitHub Copilot para modernização

Este artigo descreve como usar o recurso de re-arquitetura na modernização do GitHub Copilot para reescrever projetos de estruturas legadas para arquiteturas modernas, como do Struts ao Spring MVC.

Visão geral

O recurso de nova arquitetura permite que você transforme um projeto inteiro de uma estrutura herdada para uma arquitetura moderna usando um fluxo de trabalho de vários agentes habilitados para IA. Em vez de migração manual, arquivo por arquivo, descreva a transformação desejada em linguagem natural e os agentes de modernização lidam com a análise, o planejamento e a geração de código.

Os cenários comuns de re-arquitetura incluem:

• Struts para Spring MVC
• Struts para Spring Boot
• JSP para Thymeleaf
• EJB para Spring Boot
• Aplicativos WebSphere para Spring Boot
• Aplicativos legados baseados em servlets para arquiteturas modernas baseadas em Spring
• aplicativos de desktop Windows Forms (WinForms) para aplicações web em Angular
• Aplicações front-end em ASP.NET MVC para aplicações web em Angular

Pré-requisitos

• Visual Studio Code com a extensão de modernização do GitHub Copilot instalada.
• Uma assinatura GitHub Copilot. Para obter mais informações, consulte planos do Copilot.
• (Opcional) Python 3.7 ou posterior para criar um grafo de conhecimento, o que fornece ao agente uma compreensão mais clara da estrutura do projeto durante o processo de reescrita. Se Python não estiver disponível, a etapa do grafo de conhecimento será ignorada.
• (Opcional) Node.js 18 ou posterior para executar testes do Playwright como parte da validação do tempo de execução. Se Node.js não estiver disponível, a etapa de teste do Dramaturgo será ignorada.
• (Opcional) Docker Desktop para validação de runtime. Se o Docker não estiver disponível, a etapa de validação do runtime será ignorada.

Usar o agente de nova arquitetura

Use o agente de modernização no painel Copilot Chat do GitHub.

Use as seguintes etapas para arquitetar novamente um projeto:

1. Abra seu projeto no Visual Studio Code.

2. Abra o painel GitHub Copilot Chat.

3. Selecione o agente de modernização na lista de agentes.

4. Descreva a transformação que você deseja executar. Por exemplo:

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

O agente coordena uma equipe de vários agentes que executa as seguintes etapas:

1. Análise – Examina a base de código existente, identificando padrões de estrutura, dependências e limites de módulo.
2. Planejamento – Gera um plano de implementação estruturado com tarefas ordenadas e rastreabilidade de requisitos.
3. Execução – aplica transformações de código seguindo o plano, com verificações de validação em cada etapa.

Fornecer mais contexto

Você pode melhorar os resultados da transformação fornecendo contexto adicional em seu prompt:

• Especifique as versões da estrutura de destino, por exemplo, "Use o Spring Boot 3.2 e o Java 21".
• Referenciar links de documentação ou guias de migração.
• Descrever padrões ou convenções específicos da organização.
• Indique quais módulos ou pacotes priorizar.

Por exemplo:

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.

Solucionar problemas comuns

Durante o processo de nova arquitetura, o agente gera artefatos no .github/modernize/ diretório do seu projeto. Use esses artefatos para diagnosticar problemas quando eles surgirem.

Examinar artefatos gerados

O .github/modernize/rearchitecture diretório contém os seguintes recursos principais:

• board.md - O quadro de tarefas que acompanha todas as fases e seu status. Verifique este arquivo para ver quais tarefas foram aprovadas, falharam ou que exigiram iterações.
• artifacts/ - Relatórios detalhados de cada tarefa. Os arquivos seguem uma convenção de nomenclatura, como t21-tester-report.md para o relatório de teste inicial ou t21.2-tester-report.md para uma iteração de repetição.
• learn.md - Uma base de dados de conhecimento cumulativa de descobertas, descobertas de bugs e técnicas registradas por cada função durante a execução da tarefa. Verifique este arquivo para obter informações sobre os problemas encontrados pelo agente e como ele os resolveu.
• team/ - Cartas específicas de função que definem as responsabilidades de cada agente.

Quando uma porta de qualidade falha, o agente cria artefatos de iteração (por exemplo, t21.1, t21.2) que documentam as tentativas de correção. Procure essas iterações numeradas para entender como um problema foi detectado e resolvido.

Examinar a análise e o plano

Antes que o agente comece a escrever código, ele produz artefatos de análise e planejamento que você deve examinar. Esses artefatos proporcionam clareza sobre o que o agente entendeu do seu projeto e o que ele pretende construir.

Os artefatos de análise incluem:

• Resumo da arquitetura: uma visão geral da pilha de tecnologia existente, da estrutura do projeto, do modelo de dados e dos pontos de integração. Verifique este resumo para verificar se o agente identificou corretamente os principais componentes do projeto. Procure arquivos como artifacts/t2-architect-architecture-summary.md, artifacts/t2-architect-tech-stack.mde artifacts/t2-architect-data-model.md.
• Inventário de recursos: um catálogo de todos os recursos no aplicativo original, cada um atribuiu uma ID de requisito (por exemplo, REQ-001). Verifique se essa lista está completa e precisa. Busque artifacts/t3-pm-spec.md.
• Design de arquitetura de destino: os contratos de API propostos, a estrutura do módulo e as opções de tecnologia para o novo aplicativo. Procure arquivos como artifacts/t5-architect-api-contracts.md e artifacts/t5-architect-integration.md.

Os artefatos de planejamento incluem:

• Plano de implementação: uma lista ordenada de tarefas com dependências, agrupadas em fases. Cada tarefa mapeia de volta para um ou mais requisitos do inventário de funcionalidades. Busque artifacts/t7-teamlead-plan.md.
• Estratégia de teste: a abordagem planejada para testes de unidade, testes de integração e testes de ponta a ponta. Busque artifacts/t7-teamlead-testing-strategy.md.

O agente pausa após gerar esses artefatos e aguarda sua confirmação. Use esta oportunidade para:

• Verifique se nenhuma funcionalidade está faltando no inventário.
• Verifique se a arquitetura de destino corresponde às suas expectativas.
• Ajuste as prioridades da tarefa ou adicione restrições antes do início da implementação.

A revisão cuidadosa neste estágio ajuda a evitar o retrabalho dispendido durante as fases de implementação e validação.

Falhas de compilação e inicialização

Se o aplicativo transformado falhar ao compilar ou iniciar, use a seguinte abordagem:

1. Verifique o artefato do relatório do testador (por exemplo, t21-tester-report.md) para obter saída de build e rastreamentos de pilha.
2. Pesquise o tipo de exceção ou a mensagem de erro no artefato para identificar a causa raiz.
3. Se o agente criou iterações de correção (por exemplo, t21.1, t21.3), examine esses artefatos para ver quais alterações foram tentadas.

As causas raiz comuns incluem colisões de nomenclatura entre classes herdadas e classes recém-geradas, configurações de perfil do Spring incorretas e dependências ausentes ou conflitantes em pom.xml. Por exemplo, se controladores herdados e modernos compartilharem o mesmo nome de classe, o Spring lançará um ConflictingBeanDefinitionException na inicialização.

Erros em runtime

Se o aplicativo for iniciado, mas as chamadas à API retornarem erros (como 500 ou 400 respostas), use a seguinte abordagem:

1. Verifique o artefato do relatório do testador para identificar quais endpoints falharam e as mensagens de erro associadas.
2. Revise o artefato de achados de segurança (por exemplo, t20-security-findings.md) para problemas de configuração.
3. Inspecione as classes de entidade geradas e o código do controlador em busca de incompatibilidades entre o esquema de banco de dados e os mapeamentos ORM.

As causas raiz comuns incluem conflitos com palavras-chave reservadas de banco de dados em anotações @Column, incompatibilidades entre tipos de campos de DTO e tipos de campos de entidade, e ausência de anotações de validação em objetos de solicitação.

Falhas e iterações do portão de qualidade

O agente impõe várias portas de qualidade durante o processo de nova arquitetura. Quando uma porta falha, o agente cria automaticamente tarefas de correção e tenta novamente a validação. As falhas comuns de portão incluem:

• Revisão de arquitetura: O agente verifica se a implementação corresponde aos contratos de API, estruturas de DTO e mapeamentos de ponto de extremidade projetados. As falhas normalmente envolvem pontos de extremidade ausentes, campos renomeados ou anotações de validação ausentes. Revise o relatório do arquiteto (por exemplo, t19-architect-review.md) para obter descobertas específicas.
• Revisão de conformidade: O agente verifica se a implementação atende a todos os princípios definidos na constituição inicial. Uma falha comum é a falta de testes de ponta a ponta no nível do navegador quando a constituição exige eles. Revise o artefato de revisão do líder da equipe (por exemplo, t22-teamlead-review.md) para identificar quais princípios não foram atendidos.
• Aprovação da paridade de recursos: o agente verifica se todos os requisitos catalogados são implementados. Uma aprovação parcial significa que recursos específicos estão incompletos, por exemplo, com falta de validação cruzada de campos, como garantir que fromDate esteja antes de toDate. Examine o artefato de aprovação do PM (por exemplo, t23-pm-signoff.md) para a divisão de requisitos por requisito.

Se o agente atingir seu limite de iteração sem resolver todos os problemas, examine os arquivos de artefato mais recentes para entender as lacunas restantes e aplicar correções manuais.

Requisitos de validação em tempo de execução

O agente executa etapas opcionais de validação de runtime que dependem de ferramentas externas. Se uma ferramenta não estiver disponível, a etapa correspondente será ignorada:

• Python não instalado: a etapa do gráfico de conhecimento é ignorada. O agente ainda pode executar a nova arquitetura, mas pode ter menos contexto sobre sua estrutura de projeto. Instale Python 3.7 ou posterior e verifique se python3 está disponível em seu PATH.
• Node.js não instalado: os testes de ponta a ponta do Playwright no nível do navegador são ignorados. O agente ainda executa testes de integração por meio do Maven. Instale Node.js 18 ou posterior para habilitar o teste do navegador.
• Docker não disponível: a validação de runtime (iniciando o aplicativo em um contêiner e verificando se ele atende solicitações) é ignorada. Em vez disso, o agente depende de testes de unidade e integração. Instale e inicie o Docker Desktop para habilitar esta etapa.

Limitações

Tenha em mente as seguintes limitações:

• Projetos complexos com estruturas herdadas profundamente acopladas podem exigir várias iterações.
• Você deve examinar o código gerado cuidadosamente antes de confirmar alterações.

Fornecer comentários

Se você tiver algum comentário sobre o recurso de re-arquitetura, crie um problema no repositório github-copilot-appmod ou use o formulário de feedback de modernização do GitHub Copilot.

Consulte também

Visão geral da modernização para Java com o GitHub Copilot