Para Arquitetura Hexagonal
Analise um repositório existente em profundidade e projete um plano de refatoração atômico e faseado para migrá-lo para Arquitetura Hexagonal (Ports and Adapters) sem quebrar nenhum contrato externo ou comportamento observável.
Responda no mesmo idioma da solicitação do usuário. Opere estritamente em Modo Plano: inspecione o código primeiro e entregue o plano completo antes de modificar qualquer arquivo.
Quando Usar
- O usuário pede para migrar ou refatorar um projeto existente para Arquitetura Hexagonal ou Ports and Adapters.
- O usuário deseja desacoplar a lógica de negócio de frameworks web, ORMs, bancos de dados, brokers de mensagens ou SDKs externos.
- O usuário pede um plano de refatoração arquitetural seguro e incremental com zero quebras.
Princípios Fundamentais
- Zero Quebras (Regra de Ouro): Preserve todos os contratos externos existentes. Rotas, métodos HTTP, códigos de status, esquemas de payload de requisição/resposta, cabeçalhos, formatos de erro, flags de CLI ou formatos de mensagem de fila devem permanecer idênticos.
- Caracterização Antes da Refatoração: Nunca mova ou exclua lógica de produção até que testes automatizados de contrato/caracterização cubram endpoints ou pontos de entrada existentes.
- Regra de Dependência Estrita: As dependências do código-fonte devem sempre apontar para dentro, em direção ao
domain. A camada de domínio não deve ter nenhum import de frameworks web, drivers de banco de dados, ORMs, bibliotecas de serialização ou SDKs externos. - Adaptação Idiomática da Stack: Adapte caminhos de diretório, convenções de nomenclatura, construções de tipagem e executores de teste ao idioma e ecossistema detectados no projeto (por exemplo, TypeScript/Node, Python, Go, Java/Kotlin, C#, Rust).
Fluxo de Trabalho
Passo 1: Descoberta do Código
Escaneie o repositório antes de propor qualquer árvore de pastas ou etapas de migração:
- Stack e Ferramentas: Inspecione manifestos de dependência, configurações de compilador/linter e executores de teste para identificar o idioma, framework, biblioteca de validação, ORM/query builder e abordagem de DI.
- Pontos de Entrada e Contratos: Inventarie todos os pontos de entrada acionadores (rotas HTTP, resolvers GraphQL, serviços gRPC, consumidores de mensagens, jobs cron), seus esquemas de validação, middlewares/interceptadores e manipuladores globais de erro.
- Dependências Externas: Inventarie todos os efeitos colaterais acionados (bancos de dados, caches, clientes HTTP/RPC, filas, armazenamento de arquivos, configuração de ambiente, loggers).
- Fluxo de Execução Atual: Rastreie como os dados fluem atualmente do ponto de entrada até a persistência/chamada externa e de volta, observando onde as regras de negócio estão misturadas com detalhes de transporte ou persistência.
Passo 2: Projetar o Layout Hexagonal Alvo
Mapeie as três camadas concêntricas para a raiz de origem idiomática do projeto (por exemplo, src/ em TypeScript/Rust, internal/ em Go, src/main/<lang>/ em JVM, ou o diretório principal do pacote em Python):
domain/(Núcleo de Negócio Puro - zero dependências de framework ou I/O):entities/evalue-objects/: Modelos de domínio encapsulando regras de negócio, invariantes e autovalidação.ports/in/: Interfaces de porta de entrada definindo contratos de caso de uso.ports/out/: Interfaces de porta de saída definindo contratos de repositório, serviço externo, publicador de eventos eLoggerPort.errors/: Exceções semânticas de domínio (por exemplo,ResourceNotFoundError,DomainValidationError,ConflictError).
application/(Orquestração de Casos de Uso):use-cases/: Implementações deports/incoordenando entidades de domínio eports/out.dtos/: Estruturas de dados imutáveis de entrada e saída desacopladas de payloads de transporte e entidades de persistência.
infrastructure/(Detalhes Técnicos e Adaptadores):adapters/in/: Adaptadores de entrada (controladores/manipuladores HTTP, manipuladores de consumidores), esquemas de validação de transporte, mapeadores (TransportInput -> InputDTOeOutputDTO -> TransportOutput) e um mapeador global de erro que traduzdomain/errorspara as respostas de erro exatas do legado.adapters/out/: Implementações concretas deports/out(repositórios de banco de dados, clientes HTTP, brokers) com mapeadores de persistência/externo para que modelos de ORM ou tipos de SDK nunca vazem paradomain/.config/: Carregamento estrito e validação de inicialização de variáveis de ambiente e configurações de runtime.di/(Raiz de Composição): Conexão explícita de adaptadores acionados, casos de uso e adaptadores acionadores via injeção de construtor, evitando singletons ocultos ou localizadores de serviço.
- Separação de Bootstrap: Separe a construção da aplicação (
buildApp/ função de fábrica para teste de integração isolado) da inicialização do servidor/processo (main/listen).
Passo 3: Aplicar Padrões de Engenharia no Plano
Garanta que cada fase do plano aplique:
- Tipagem Forte e Imutabilidade: Proíba escapes não tipados (como
anyou mapas não tipados brutos onde estruturas tipadas se aplicam) e favoreça DTOs imutáveis e Value Objects (readonly, dataclasses congeladas, records, tipos de valor). - SOLID e Injeção de Construtor: Mantenha classes e funções pequenas com responsabilidades únicas; injete interfaces via construtores.
- Observabilidade Sem Acoplamento: Preserve o log estruturado e o contexto de correlação de requisição enquanto mantém
domain/eapplication/desacoplados de bibliotecas de log específicas viaLoggerPort. - Testes Piramidais:
- Testes unitários para
domain/(invariantes puras) eapplication/(mockingports/out). - Testes de integração/contrato verificando adaptadores de entrada reais contra a fiação da aplicação usando o cliente de teste em memória nativo da stack (por exemplo,
fastify.inject, Supertest, FastAPITestClient, SpringMockMvc, ou Gohttptest).
- Testes unitários para
Formato de Saída (Modo Plano)
Entregue a resposta estruturada nestas seções exatas:
- Diagnóstico da Arquitetura Atual: Inventário conciso da stack detectada, pontos de entrada/endpoints, dependências externas e principais pontos de acoplamento.
- Árvore de Diretórios Alvo: Estrutura de pastas proposta completa usando os nomes reais de módulos e funcionalidades encontrados no repositório.
- Plano de Execução por Fases: Cinco fases atômicas e verificáveis:
- Fase 1 - Testes de Caracterização e Scaffolding Base: Crie testes de contrato travando o comportamento atual, crie pastas alvo, carregador de configuração e Raiz de Composição (
di/). - Fase 2 - Extração do Domínio: Extraia entidades, objetos de valor, erros de domínio e interfaces
ports/in+ports/outcom testes unitários. - Fase 3 - Casos de Uso da Aplicação e Adaptadores Acionados: Implemente casos de uso, DTOs, repositórios/clientes
adapters/oute mapeadores de persistência. - Fase 4 - Adaptadores de Entrada e Tradução de Erro: Refatore controladores/manipuladores para delegar a casos de uso via mapeadores, conecte a tradução global de erro e ligue
di/. - Fase 5 - Limpeza do Legado e Verificação Final: Remova arquivos obsoletos, execute a suíte de testes completa, linter e verificador de tipos, e verifique zero desvio de contrato.
- Fase 1 - Testes de Caracterização e Scaffolding Base: Crie testes de contrato travando o comportamento atual, crie pastas alvo, carregador de configuração e Raiz de Composição (
- Pontos de Verificação de Validação: Comando explícito ou verificação ao final de cada fase provando que nada quebrou antes de avançar para a próxima fase.
Armadilhas
- Não edite código prematuramente: A menos que o usuário peça explicitamente para começar a executar a Fase 1 imediatamente, produza apenas o plano primeiro para que eles possam revisar os limites dos módulos.
- Evite abstração excessiva em CRUD trivial: Ainda separe
domain,applicationeinfrastructureclaramente, mas mantenha casos de uso de passagem concisos em vez de inventar complexidade de domínio artificial. - Corresponda a peculiaridades do legado: Se um endpoint existente retornar um código de status não padrão ou nome de campo de erro, documente-o na Fase 1 e preserve-o no mapeador de erro
infrastructurepara que clientes existentes não quebrem.