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.

subdirectory_arrow_right1. Problema que resolve

Uma hierarquia de elementos muda pouco, mas novas operações sobre todos os tipos aparecem com frequência.

subdirectory_arrow_rightSinais 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.

subdirectory_arrow_right2. Quando usar

• Compiladores/AST.
• Árvores de documentos.
• Exportadores/validadores sobre estrutura estável.

subdirectory_arrow_right3. 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.

subdirectory_arrow_right4. 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.

subdirectory_arrow_right5. 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.

lightbulb6. Exemplo mental

Uma AST mantém nós estáveis; TypeCheckVisitor, PrettyPrintVisitor e MetricsVisitor adicionam operações sem inflar cada nó.

subdirectory_arrow_right7. Benefícios esperados

• Novas operações são fáceis de adicionar.
• Agrupa lógica transversal por operação.

subdirectory_arrow_right8. Custos e trade-offs

• Novo tipo de elemento exige alterar todos visitors.
• Pode quebrar encapsulamento ao exigir acesso a dados do elemento.

subdirectory_arrow_right9. 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.

subdirectory_arrow_right10. 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.

fact_check11. 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

subdirectory_arrow_right12. Padrões relacionados

• Composite
• Iterator
• Interpreter

subdirectory_arrow_right13. 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?

smart_toy14. Prompt pronto

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.

helpComo 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.

lightbulbExemplo preenchido

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.

subdirectory_arrow_right15. 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”.

subdirectory_arrow_right16. 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.