Guia de Referência: Iterator (Comportamental)

Este guia orienta a aplicação do padrão Iterator em projetos de software. Objetivo: Percorrer elementos de uma coleção sem expor sua representação interna. O padrão deve ser usado somente quando as forças do problema o justificarem.

subdirectory_arrow_right1. Problema que resolve

Clientes precisam navegar estruturas diferentes sem conhecer arrays, árvores, grafos ou detalhes de armazenamento.

subdirectory_arrow_rightSinais no código/arquitetura

• Traversal está duplicado em vários clientes.
• A coleção tem múltiplas estratégias de percurso.
• Expor a estrutura interna quebra encapsulamento.

subdirectory_arrow_right2. Quando usar

• Coleções customizadas.
• Árvores/grafos com DFS/BFS.
• Paginação/streaming abstraído como sequência.

subdirectory_arrow_right3. Quando NÃO usar

• Quando a linguagem já oferece iteradores adequados e não há comportamento especial.
• Quando materializar a coleção é simples e suficiente.

subdirectory_arrow_right4. Estrutura e participantes

• Iterator: hasNext/next ou protocolo da linguagem.
• ConcreteIterator: mantém estado do percurso.
• Aggregate: fornece iteradores.
• Client: consome a sequência sem conhecer estrutura.

subdirectory_arrow_right5. Procedimento de implementação

1. Defina a unidade de elemento exposta.
2. Mantenha cursor/estado no iterador.
3. Ofereça um iterador por estratégia de percurso quando necessário.
4. Trate modificação concorrente conforme contrato.
5. Prefira protocolos nativos da linguagem.

lightbulb6. Exemplo mental

OrgChart oferece depthFirst() e breadthFirst() como iteradores; o cliente apenas itera empregados.

subdirectory_arrow_right7. Benefícios esperados

• Encapsula traversal.
• Permite múltiplos percursos simultâneos.
• Simplifica clientes.

subdirectory_arrow_right8. Custos e trade-offs

• Pode ser desnecessário para coleções simples.
• Iteradores stateful exigem cuidado com concorrência/mutação.

subdirectory_arrow_right9. Encaixe com Clean Architecture e SOLID

O domínio pode expor coleções por abstrações de leitura/iteráveis sem revelar persistência. Não use Iterator para esconder consultas N+1 custosas.

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

Extraia quando loops de navegação complexa se repetem e conhecem internals da coleção.

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 ordem, fim da sequência, coleção vazia, múltiplos iteradores e regras de mutação.

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
• Visitor
• Memento

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 **Iterator** é 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 Iterator.
2. Compare pelo menos uma alternativa mais simples e um padrão relacionado (Composite, Visitor, Memento).
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: Coleção de árvore precisa ser percorrida sem expor sua estrutura interna.
Objetivo: Fornecer diferentes percursos mantendo o cliente desacoplado da representação.
Restrições: Definir comportamento em mutação concorrente; não reinventar iterador nativo sem necessidade.

subdirectory_arrow_right15. Critério de aceite

A aplicação de Iterator 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.