Rearquitetar projetos usando a modernização do GitHub Copilot

Este artigo descreve como usar a funcionalidade de re-arquitetura na modernização do GitHub Copilot para reescrever projetos de frameworks legados para arquiteturas modernas, como de Struts para Spring MVC.

Descrição geral

A funcionalidade de re-arquitetura permite-lhe transformar um projeto inteiro de uma framework legada para uma arquitetura moderna, utilizando um fluxo de trabalho multi-agente alimentado por IA. Em vez de migração manual, ficheiro a ficheiro, descreva a transformação desejada em linguagem natural, e os agentes de modernização tratam da análise, planeamento e geração de código.

Cenários comuns de re-arquitetura incluem:

• Struts para Spring MVC
• Struts para Spring Boot
• JSP para Thymeleaf
• EJB para Spring Boot
• Aplicações WebSphere para Spring Boot
• Aplicações legadas baseadas em servlets para arquiteturas modernas baseadas em Spring
• Aplicações de ambiente de trabalho Windows Forms (WinForms) para aplicações web Angular
• Aplicações de front-end ASP.NET MVC para aplicações Web em Angular

Pré-requisitos

• Visual Studio Code com a extensão GitHub Copilot Modernization instalada.
• Uma subscrição do GitHub Copilot. Para mais informações, consulte planos do Copilot.
• (Opcional) Python 3.7 ou posteriores para construir um grafo de conhecimento, que dá ao agente uma compreensão mais clara da estrutura do seu projeto durante o processo de reescrita. Se o Python não estiver disponível, a etapa do grafo de conhecimento é ignorada.
• (Opcional) Node.js 18 anos ou mais para realizar testes de Playwright como parte da validação em tempo de execução. Se Node.js não estiver disponível, a etapa do teste de Dramaturgo é ignorada.
• (Opcional) Docker Desktop para validação em tempo de execução. Se o Docker não estiver disponível, a etapa de validação em tempo de execução é ignorada.

Usar o agente de rearquitetura

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

Use os seguintes passos para rearquitetar um projeto:

1. Abra o seu projeto no Visual Studio Code.

2. Abra o painel GitHub Copilot Chat.

3. Selecione o agente Modernizar da lista de agentes.

4. Descreve a transformação que queres realizar. Por exemplo:

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

O agente coordena uma equipa multi-agente que executa os seguintes passos:

1. Análise - Examina a base de código existente, identificando padrões de framework, dependências e limites de módulos.
2. Planeamento - 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.

Forneça mais contexto

Pode melhorar os resultados da transformação fornecendo contexto adicional no seu prompt:

• Especifique versões do framework de destino, por exemplo, "Use Spring Boot 3.2 e Java 21."
• Links de documentação de referência ou guias de migração.
• Descreva padrões ou convenções específicas da organização.
• Indique quais os módulos ou pacotes a 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.

Resolver problemas comuns

Durante o processo de re-arquitetura, o agente gera artefactos no .github/modernize/ diretório do seu projeto. Use estes artefactos para diagnosticar problemas quando surgem.

Revisão de artefactos gerados

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

• board.md - O quadro de tarefas que acompanha cada fase e o seu estado. Verifique este ficheiro para ver quais as tarefas que passaram, falharam ou exigiram iterações.
• artifacts/ - Relatórios detalhados de cada tarefa. Os ficheiros seguem uma convenção de nomenclatura, tais como t21-tester-report.md para o relatório de teste inicial, ou t21.2-tester-report.md para uma iteração de nova tentativa.
• learn.md - Uma base de conhecimento cumulativa de descobertas, descobertas de bugs e técnicas registadas por cada função durante a execução da tarefa. Consulte este ficheiro para obter informações sobre os problemas que o agente enfrentou e como os resolveu.
• team/ - Cartas específicas por função que definem as responsabilidades de cada agente.

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

Revise a análise e o plano

Antes de o agente começar a escrever código, ele produz artefatos de análise e planeamento que deve rever. Estes artefactos dão-lhe uma visão sobre o que o agente percebeu sobre o seu projeto e o que pretende construir.

Os artefactos de análise incluem:

• Resumo da arquitetura: Uma visão geral da stack tecnológica existente, estrutura do projeto, modelo de dados e pontos de integração. Consulte este resumo para verificar se o agente identificou corretamente os componentes-chave do seu projeto. Procure ficheiros como artifacts/t2-architect-architecture-summary.md, artifacts/t2-architect-tech-stack.md, e artifacts/t2-architect-data-model.md.
• Inventário de funcionalidades: Um catálogo de todas as funcionalidades da aplicação original, cada uma atribuída a um ID de requisito (por exemplo, REQ-001). Verifique se esta lista é completa e precisa. Procure artifacts/t3-pm-spec.md.
• Design da arquitetura alvo: Os contratos de API propostos, estrutura de módulos e escolhas tecnológicas para a nova aplicação. Procure ficheiros como artifacts/t5-architect-api-contracts.md e artifacts/t5-architect-integration.md.

Os artefatos de planeamento incluem:

• Plano de implementação: Uma lista ordenada de tarefas com dependências, agrupadas em fases. Cada tarefa corresponde a um ou mais requisitos do inventário de funcionalidades. Procure artifacts/t7-teamlead-plan.md.
• Estratégia de testes: A abordagem planeada para testes unitários, testes de integração e testes de ponta a ponta. Procure artifacts/t7-teamlead-testing-strategy.md.

O agente faz uma pausa após gerar estes artefactos e espera pela tua confirmação. Aproveite esta oportunidade para:

• Verifique se não faltam funcionalidades no inventário.
• Verifique se a arquitetura alvo corresponde às suas expectativas.
• Ajusta as prioridades das tarefas ou adiciona restrições antes de começar a implementação.

Uma revisão cuidadosa nesta fase ajuda a evitar retrabalhos dispendiosos durante as fases de implementação e validação.

Falhas de construção e arranque

Se a aplicação transformada falhar em compilar ou iniciar, use a seguinte abordagem:

1. Verifique o artefato do relatório do tester (por exemplo, t21-tester-report.md) para resultados de build e traces de pilha.
2. Procure o tipo de exceção ou a mensagem de erro no artefacto para identificar a causa raiz.
3. Se o agente criou iterações de correção (por exemplo, t21.1, t21.3), reveja esses artefactos para ver que alterações foram tentadas.

As causas raiz comuns incluem colisões de nomeação entre classes legadas e recém-geradas, configurações incorretas do perfil do Spring e dependências em falta ou conflituosas em pom.xml. Por exemplo, se controladores antigos e modernos partilharem o mesmo nome de classe, o Spring lança um ConflictingBeanDefinitionException ao arranque.

Erros de tempo de execução

Se a aplicação iniciar mas as chamadas de API devolverem erros (como 500 ou 400 respostas), use a seguinte abordagem:

1. Verifique o artefacto de relatório do teste para identificar quais endpoints falharam e as mensagens de erro associadas.
2. Revise o artefacto de descobertas de segurança (por exemplo, t20-security-findings.md) para problemas de configuração.
3. Inspecionar as classes de entidade geradas e o código controlador para encontrar incompatibilidades entre o esquema da base de dados e os mapeamentos ORM.

As causas raiz comuns incluem conflitos em anotações @Column devido a palavras-chave reservadas na base de dados, incompatibilidades entre tipos de campos DTO e tipos de campos da entidade, e ausência de anotações de validação em objetos de pedido.

Falhas e iterações da porta de qualidade

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

• Revisão de arquitetura: O agente verifica se a implementação corresponde aos contratos de API projetados, estruturas DTO e mapeamentos de endpoints. Normalmente, as falhas envolvem a falta de endpoints, campos renomeados ou anotações de validação em falta. Analise o artefato do relatório do arquiteto (por exemplo, t19-architect-review.md) para descobertas específicas.
• Revisão de conformidade: O agente verifica se a implementação cumpre todos os princípios definidos na constituição inicial. Uma falha comum é faltar a testes de ponta a ponta ao nível do navegador quando a constituição os exige. Revise o artefacto de revisão do líder de equipa (por exemplo, t22-teamlead-review.md) para identificar quais os princípios que não foram cumpridos.
• Aprovação da paridade de funcionalidades: O agente verifica se todos os requisitos catalogados estão implementados. Uma aprovação parcial significa que características específicas estão incompletas, por exemplo, falta de validação cruzada de campos, como garantir que fromDate está antes de toDate. Revise o artefacto de aprovação do PM (por exemplo, t23-pm-signoff.md) para a análise detalhada de cada requisito.

Se o agente atingir o limite de iteração sem resolver todos os problemas, reveja os ficheiros de artefactos mais recentes para compreender as lacunas restantes e aplique correções manuais.

Pré-requisitos para validação em tempo de execução

O agente executa passos opcionais de validação em tempo de execução que dependem de ferramentas externas. Se uma ferramenta não estiver disponível, o passo correspondente é ignorado:

• Python não instalado: A etapa do grafo de conhecimento é ignorada. O agente ainda pode realizar a reorganização da arquitetura, mas pode ter um contexto reduzido sobre a estrutura do seu projeto. Instale Python 3.7 ou posterior e certifique-se de que python3 está disponível no seu PATH.
• Node.js não instalado: Os testes de ponta a ponta ao nível do navegador Playwright são saltados. O agente ainda executa testes de integração através da Maven. Instale Node.js 18 ou mais tarde para ativar o teste do navegador.
• Docker não disponível: A validação em tempo de execução (iniciar a aplicação num contentor e verificar se serve pedidos) é ignorada. O agente, em vez disso, baseia-se em testes unitários e de integração. Instale e inicie o Docker Desktop para ativar este passo.

Limitações

Tenha em mente as seguintes limitações:

• Projetos complexos com frameworks legados profundamente acoplados podem exigir múltiplas iterações.
• Deves rever cuidadosamente o código gerado antes de comprometeres as alterações.

Fornecer comentários

Se tiveres algum feedback sobre a funcionalidade de re-arquitetura, cria um problema no repositório github-copilot-appmod ou usa o formulário de feedback de modernização GitHub Copilot.

Consulte também

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