Změna architektury projektů pomocí modernizace GitHub Copilot

Tento článek popisuje, jak pomocí funkce pře-architekturování v rámci modernizace GitHub Copilot přepsat projekty z legacy frameworků na moderní architektury, jako například ze Struts na Spring MVC.

Přehled

Funkce opětovné architektury umožňuje transformovat celý projekt ze starší architektury na moderní architekturu pomocí pracovního postupu s více agenty využívajícím AI. Místo ruční migrace souborů po souborech popište požadovanou transformaci v přirozeném jazyce a agenti modernizace zpracovávají analýzu, plánování a generování kódu.

Mezi běžné scénáře opětovné architektury patří:

• Přechod ze Struts na Spring MVC
• Ze Struts na Spring Boot
• JSP na Thymeleaf
• EJB na Spring Boot
• Aplikace WebSphere do Spring Bootu
• Starší verze aplikací založených na servletu na moderní architektury založené na Springu
• Převod desktopových aplikací model Windows Forms (WinForms) na webové aplikace Angular
• ASP.NET MVC front-endové aplikace do webových aplikací Angular

Předpoklady

• Visual Studio Code s nainstalovaným rozšířením GitHub Copilot.
• Předplatné GitHub Copilot. Další informace najdete v tématu Copilot plans.
• (Volitelné) Python 3.7 nebo novější pro vytvoření znalostního grafu, který dává agentovi jasnější porozumění struktury vašeho projektu během procesu přepisování. Pokud Python není k dispozici, krok grafu znalostí se přeskočí.
• (Volitelné) Node.js 18 nebo novější pro spouštění testů Playwright v rámci ověřování modulu runtime. Pokud Node.js není k dispozici, testovací krok Playwright se přeskočí.
• (Volitelné) Docker Desktop pro ověření běhového prostředí. Pokud Docker není dostupný, krok ověření modulu runtime se přeskočí.

Použijte agenta pro opětovnou architekturu

Použijte modernizačního agenta na panelu Copilot Chat GitHubu.

Pomocí následujících kroků znovu vytvořte návrh projektu:

1. Otevřete projekt v Visual Studio Code.

2. Otevřete panel GitHub Copilot Chat.

3. V seznamu agentů vyberte agenta modernize.

4. Popište transformaci, kterou chcete provést. Například:

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

Agent koordinuje tým s více agenty, který provádí následující kroky:

1. Analýza – prozkoumá existující základ kódu, identifikuje vzory architektury, závislosti a hranice modulů.
2. Plánování – Generuje strukturovaný plán implementace s seřazenými úkoly a sledovatelnost požadavků.
3. Provádění – použije transformace kódu za plánem s ověřovacími kontrolami v každém kroku.

Poskytnutí dalšího kontextu

Výsledky transformace můžete vylepšit poskytnutím dalšího kontextu ve výzvě:

• Zadejte verze cílové architektury, například "Use Spring Boot 3.2 and Java 21" (Použít Spring Boot 3.2 a Java 21).
• Odkazy na referenční dokumentaci nebo průvodce migrací
• Popis vzorů nebo konvencí specifických pro organizaci
• Určete, kterým modulům nebo balíčkům dát prioritu.

Například:

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.

Řešení běžných potíží

Během procesu opětovné architektury agent generuje artefakty v .github/modernize/ adresáři projektu. Pomocí těchto artefaktů můžete diagnostikovat problémy, když k nim dojde.

Kontrola vygenerovaných artefaktů

Adresář .github/modernize/rearchitecture obsahuje následující klíčové prostředky:

• board.md - Panel úkolů, který sleduje každou fázi a její stav. Zkontrolujte tento soubor a zjistěte, které úlohy proběhly, selhaly nebo které iterace vyžadovaly.
• artifacts/ - Podrobné zprávy z každého úkolu. Soubory se řídí konvencí pojmenování, například t21-tester-report.md pro počáteční testovací zprávu nebo t21.2-tester-report.md pro nový pokus.
• learn.md – Kumulativní znalostní báze zjišťování, zjištění chyb a technik protokolovaných jednotlivými rolemi během provádění úkolu. V tomto souboru najdete přehled o problémech, ke kterým agent narazil a jak je vyřešil.
• team/ - Charty specifické pro jednotlivé role, které definují povinnosti jednotlivých agentů.

Když selže brána kvality, agent vytvoří iterace artefaktů (například t21.1, t21.2), které dokumentují pokusy o opravu. Vyhledejte tyto čísloované iterace, abyste pochopili, jak byl zjištěn a vyřešen problém.

Kontrola analýzy a plánu

Než agent začne psát kód, vytvoří výstupy z analýzy a plánování, které byste měli zkontrolovat. Tyto artefakty vám poskytnou přehled o tom, co agent pochopil o vašem projektu a o tom, co má v úmyslu sestavit.

Mezi artefakty analýzy patří:

• Shrnutí architektury: Přehled stávajícího technického zásobníku, struktury projektu, datového modelu a integračních bodů Zkontrolujte tento souhrn a ověřte, že agent správně identifikoval klíčové komponenty projektu. Vyhledejte soubory, například artifacts/t2-architect-architecture-summary.md, artifacts/t2-architect-tech-stack.mda artifacts/t2-architect-data-model.md.
• Inventář funkcí: Katalog všech funkcí v původní aplikaci, z nichž každý má přiřazené ID požadavku (například REQ-001). Ověřte, že je tento seznam úplný a přesný. Vyhledejte artifacts/t3-pm-spec.md.
• Návrh cílové architektury: Navrhované kontrakty rozhraní API, struktura modulů a technologické volby pro novou aplikaci. Vyhledejte soubory, například artifacts/t5-architect-api-contracts.md a artifacts/t5-architect-integration.md.

Mezi artefakty plánování patří:

• Plán implementace: Uspořádaný seznam úkolů se závislostmi seskupenými do fází. Každý úkol se mapuje zpět na jeden nebo více požadavků z inventáře funkcí. Vyhledejte artifacts/t7-teamlead-plan.md.
• Strategie testování: Plánovaný přístup k testům jednotek, integračním testům a kompletním testům. Vyhledejte artifacts/t7-teamlead-testing-strategy.md.

Agent se po vygenerování těchto artefaktů pozastaví a počká na potvrzení. Tuto příležitost použijte k:

• Ověřte, že v inventáři chybí žádné funkce.
• Zkontrolujte, jestli cílová architektura odpovídá vašim očekáváním.
• Upravte priority úkolů nebo přidejte omezení před zahájením implementace.

Pečlivá kontrola v této fázi pomáhá vyhnout se nákladnému přepracování během fází implementace a ověřování.

Selhání při vytváření a spuštění

Pokud se transformovaná aplikace nepodaří zkompilovat nebo spustit, použijte následující přístup:

1. Zkontrolujte artefakt reportu testeru (například t21-tester-report.md) s výstupem sestavení a trasováním zásobníku.
2. Vyhledejte typ výjimky nebo chybovou zprávu v artefaktu, abyste identifikovali původní příčinu.
3. Pokud agent vytvořil iterace oprav (například t21.1, t21.3), zkontrolujte tyto artefakty, abyste viděli, jaké změny byly pokuseny.

Mezi běžné původní příčiny patří kolize názvů mezi staršími a nově vygenerovanými třídami, nesprávnou konfigurací profilu Spring a chybějícími nebo konfliktními závislostmi v pom.xml. Pokud například starší a moderní kontrolery sdílejí stejný název třídy, Spring vyvolá ConflictingBeanDefinitionException při spuštění chybu.

Chyby za běhu programu

Pokud se aplikace spustí, ale volání rozhraní API vrátí chyby (například 500 nebo 400 odpovědí), použijte následující přístup:

1. Zkontrolujte testerový výstup sestavy, u kterého selhaly koncové body a které obsahuje související chybové zprávy.
2. V případě problémů s konfigurací zkontrolujte artefakt zjištění zabezpečení (například t20-security-findings.md).
3. Zkontrolujte vygenerované třídy entit a kód kontroleru pro neshody mezi schématem databáze a mapováním ORM.

Mezi běžné původní příčiny patří konflikty vyhrazených klíčových slov databáze v @Column poznámkách, neshody mezi typy polí DTO a typy polí entity a chybějící ověřovací poznámky k objektům požadavku.

Selhání kontrolní brány kvality a iterace

Agent vynucuje několik bran kvality během procesu přepracování architektury. Když brána selže, agent automaticky vytvoří úlohy opravy a opakuje ověření. Mezi běžné chyby brány patří:

• Kontrola architektury: Agent kontroluje, že implementace odpovídá navrženým kontraktům rozhraní API, strukturám DTO a mapování koncových bodů. Selhání obvykle zahrnují chybějící koncové body, přejmenovaná pole nebo chybějící ověřovací poznámky. Prohlédněte si artefakt sestavy architekta (například t19-architect-review.md) pro konkrétní zjištění.
• Kontrola shody: Agent ověří, že implementace splňuje všechny principy definované v počáteční ústavě. Běžným problémem je absence end-to-end testů na úrovni prohlížeče, když to vyžadují specifikace. Zkontrolujte artefakt kontroly vedoucího týmu, například t22-teamlead-review.md, a zjistěte, které principy nebyly splněny.
• Schválení shody funkcí: Agent ověřuje, že jsou implementované všechny katalogizované požadavky. Částečné schválení znamená, že určité funkce nejsou úplné, například chybí cross-field obdobná kontrola, jako je například zajištění, že fromDate je před toDate. Zkontrolujte artefakt schválení PM (například t23-pm-signoff.md) pro podrobný rozpis podle jednotlivých požadavků.

Pokud agent dosáhne limitu iterace bez řešení všech problémů, projděte si nejnovější soubory artefaktů, abyste porozuměli zbývajícím mezerám a použili ruční opravy.

Předpoklady pro validaci za běhu

Agent provádí volitelné kroky ověření modulu runtime, které závisí na externích nástrojích. Pokud nástroj není k dispozici, odpovídající krok se přeskočí:

• Python nenainstalováno: Krok znalostního grafu se přeskočí. Agent nebo nástroj může stále provádět úpravu architektury, ale může mít méně informací o struktuře vašeho projektu. Nainstalujte Python 3.7 nebo novější a ujistěte se, že je python3 k dispozici ve vašem PATH.
• Node.js není nainstalován: Testy end-to-end na úrovni prohlížeče Playwright jsou přeskočeny. Agent stále spouští integrační testy prostřednictvím Mavenu. Pokud chcete povolit testování prohlížeče, nainstalujte Node.js 18 nebo novější.
• Docker není k dispozici: Ověření modulu runtime (spuštění aplikace v kontejneru a ověření, že obsluhuje požadavky) se přeskočí. Agent místo toho spoléhá na testy jednotek a integrace. Pokud chcete tento krok povolit, nainstalujte a spusťte Docker Desktop.

Omezení

Mějte na paměti následující omezení:

• Složité projekty s hluboce propojenými staršími architekturami můžou vyžadovat více iterací.
• Před potvrzením změn byste měli pečlivě zkontrolovat vygenerovaný kód.

Poskytnout zpětnou vazbu

Pokud máte zpětnou vazbu k funkci přepracování architektury, vytvořte issue v úložišti github-copilot-appmod nebo použijte formulář zpětné vazby modernizace GitHub Copilot.

Viz také

Přehled modernizace GitHub Copilot pro jazyk Java