# Guia de Referência: Visitor (Comportamental) Este guia orienta a aplicação do padrão **Visitor** em projetos de software. **Objetivo:** Adicionar novas operações a uma estrutura estável de tipos sem colocar cada operação dentro das classes dos elementos. O padrão deve ser usado somente quando as forças do problema o justificarem. --- ## 1. Problema que resolve Uma hierarquia de elementos muda pouco, mas novas operações sobre todos os tipos aparecem com frequência. ### Sinais no código/arquitetura - Adicionar uma operação exige editar todas as classes com métodos não relacionados à responsabilidade principal. - A estrutura de tipos é estável. - A operação precisa comportamento específico por tipo concreto. ## 2. Quando usar - Compiladores/AST. - Árvores de documentos. - Exportadores/validadores sobre estrutura estável. ## 3. Quando NÃO usar - Quando novos tipos de elementos são adicionados frequentemente. - Quando double dispatch e a complexidade do Visitor não se justificam. - Quando uma operação simples pode ser função/pattern matching idiomático da linguagem. ## 4. Estrutura e participantes - Visitor: método de visita por tipo de elemento. - ConcreteVisitor: uma operação transversal. - Element: aceita visitor. - ConcreteElement: direciona para a visita correta. - ObjectStructure: percorre elementos. ## 5. Procedimento de implementação 1. Confirme que a hierarquia é mais estável que as operações. 2. Defina `accept(visitor)`. 3. Defina uma visita por tipo concreto. 4. Mova a operação para ConcreteVisitor. 5. Use Iterator/Composite para percorrer a estrutura quando necessário. ## 6. Exemplo mental Uma AST mantém nós estáveis; `TypeCheckVisitor`, `PrettyPrintVisitor` e `MetricsVisitor` adicionam operações sem inflar cada nó. ## 7. Benefícios esperados - Novas operações são fáceis de adicionar. - Agrupa lógica transversal por operação. ## 8. Custos e trade-offs - Novo tipo de elemento exige alterar todos visitors. - Pode quebrar encapsulamento ao exigir acesso a dados do elemento. ## 9. Encaixe com Clean Architecture e SOLID Use em estruturas internas estáveis. Evite usar Visitor como desculpa para expor detalhes de entidades de domínio que deveriam preservar invariantes. **Regras para a IA:** - Dependa de abstrações quando a variação justificar uma fronteira. - Não faça o domínio importar SDKs, frameworks, banco de dados ou UI. - Mantenha cada participante com responsabilidade coesa. - Prefira composição quando ela reduzir acoplamento; não crie hierarquias artificiais. - Registre a decisão arquitetural quando o padrão afetar muitos módulos. ## 10. Caminho de refatoração Útil quando classes de elementos acumulam muitas operações transversais não relacionadas à sua responsabilidade principal. Ao refatorar um sistema existente: 1. Proteja o comportamento atual com testes. 2. Faça passos pequenos e reversíveis. 3. Introduza primeiro a abstração/contrato. 4. Migre um fluxo por vez. 5. Remova código antigo apenas após equivalência comportamental comprovada. ## 11. Estratégia de testes Teste cada visitor sobre todos os tipos relevantes e cenários de estrutura composta. Checklist mínimo: - [ ] caminho feliz - [ ] entradas/estados de limite - [ ] erros e falhas de dependências - [ ] comportamento de cada implementação concreta - [ ] teste de contrato quando houver múltiplas implementações - [ ] teste de integração apenas onde a fronteira externa for relevante ## 12. Padrões relacionados - Composite - Iterator - Interpreter ## 13. Perguntas de diagnóstico para a IA 1. Qual aspecto do sistema realmente varia? 2. Essa variação já está causando duplicação, condicionais ou acoplamento? 3. Uma função/composição simples resolveria com menos abstrações? 4. O padrão reduz o custo de uma mudança concreta que já é provável? 5. Qual é o custo de introduzir novas classes, indireção e configuração? 6. Como a decisão será testada e observada em produção? ## 14. Prompt pronto ```text Você é o arquiteto do projeto. Avalie se o padrão **Visitor** é adequado para o problema abaixo. Contexto: [DESCREVA o sistema, stack/arquitetura, estado atual e o problema observado] Objetivo: [DESCREVA o resultado esperado ao avaliar ou aplicar este padrão] Restrições: [DESCREVA prazo, legado, performance, testes, compatibilidade e o que não pode mudar] Antes de codificar: 1. Identifique as forças que justificam ou rejeitam Visitor. 2. Compare pelo menos uma alternativa mais simples e um padrão relacionado (Composite, Iterator, Interpreter). 3. Se o padrão for justificado, mostre participantes, dependências e fluxo. 4. Preserve Clean Architecture/SOLID: regras centrais não dependem de infraestrutura. 5. Implemente incrementalmente, com testes. 6. Ao final, liste trade-offs e sinais de overengineering. Não aplique o padrão apenas porque foi solicitado; rejeite-o se não houver variação/complexidade que o justifique. ``` ### Como preencher os campos - **Contexto:** descreva o tipo de sistema, stack/versões, arquitetura atual, onde a mudança acontece e o comportamento relevante já existente. - **Objetivo:** descreva o resultado observável que deve existir ao final, não apenas a tecnologia que você quer usar. - **Restrições:** informe o que não pode mudar, compatibilidade, prazo, segurança, acessibilidade, performance, legado, dependências e limites de escopo. ### Exemplo preenchido ```text Contexto: Estrutura de documentos é estável, mas novas operações como exportar, validar e calcular estatísticas são adicionadas frequentemente. Objetivo: Adicionar operações sobre a estrutura sem modificar cada classe de elemento. Restrições: Só usar quando a estrutura de elementos é relativamente estável; adicionar novos tipos de elemento fica mais caro. ``` ## 15. Critério de aceite A aplicação de **Visitor** só está concluída quando: - [ ] o problema que motivou o padrão está explicitamente documentado; - [ ] o código cliente depende do contrato correto, não de detalhes acidentais; - [ ] adicionar a variação-alvo exige menos mudanças que antes; - [ ] testes protegem a extensão/refatoração; - [ ] não houve vazamento de infraestrutura para o núcleo; - [ ] a solução ficou mais compreensível para manutenção, não apenas “mais orientada a padrões”. ## 16. Base Conceitual e Relações - Catálogo Refactoring.Guru em português — escopo de 22 padrões. - *Design Patterns: Elements of Reusable Object-Oriented Software* (Gamma, Helm, Johnson e Vlissides) — intenção, aplicabilidade, participantes, consequências e relações entre padrões. - Guias de Clean Architecture, princípios de design, refatoração e código limpo deste pacote.