O que é e como funciona na prática
a turma do pato bill é uma metodologia de organização de código que separa concerns de forma explícita. A intenção é simples: manter cada responsabilidade isolada em seu próprio módulo, arquivo ou diretório, evitando que lógica de negócio, acesso a dados e apresentação se misturem dentro do mesmo arquivo. Não é um framework novo, não é uma biblioteca — é apenas um padrão de nomenclatura e estrutura que equipes usam há anos. Achei que seria fácil na primeira vez que implementei. Levei três semanas descobrindo que o problema real não era entender o conceito, mas aplicar sem virar burocracia pura. Vou explicar como fazer de verdade.
Por que a turma do pato bill existe
Quando um arquivo cresce além de duzentas linhas, começa a acontecer algo previsível: você encontra uma função que deveria estar em outro lugar, mas mover gera dependências quebradas. Isso acontece com frequência porque o código muda enquanto você lê. A turma do pato bill resolve isso estabelecendo um contrato claro desde o início. Você não precisa reinventar a roda toda vez que surge um novo domínio no sistema. A estrutura padrão usa três camadas principais. A camada de domínio contém as entidades e regras de negócio. A camada de aplicação orquestra esses domínios com use cases específicos. A camada de interface cuida de entrada e saída, seja API REST, CLI ou frontend. O separador real não é arquitetônico — é mental. Se você não consegue explicar em uma frase o que cada módulo faz, a divisão está errada.
Estrutura básica de arquivos
No projeto típico, a árvore de diretórios se organiza assim: src/domain/models/ — entidades puras, sem dependências externas
src/domain/repositories/ — contratos de acesso a dados
src/application/use_cases/ — lógica de negócio coordenada
src/application/services/ — serviços auxiliares sem estado
src/infrastructure/persistence/ — implementações concretas de repositórios
src/infrastructure/adapters/ — adaptadores para frameworks externos
src/interface/http/ — controladores HTTP
src/interface/cli/ — handlers de linha de comando
Isso parece óbvio, mas o erro comum é colocar lógica de validação dentro do controlador. Validação pertence ao domínio ou à aplicação, nunca à interface. Eu já vi controller com cinquenta linhas de ifs verificando campos obrigatórios. Isso é manutenção futura complicada.
Implementando na prática
Comece definindo o domínio antes de escrever qualquer código. Crie a entidade principal como uma classe ou tipo puro, sem métodos que dependam de banco de dados ou HTTP. Depois, defina o repositório como uma interface. Implementação fica para depois, quando você já sabe o que precisa consultar. Na camada de aplicação, cada use case deve ter um método único que recebe dados de entrada e retorna dados de saída. Nada de múltiplos retornos, nada de efeitos colaterais escondidos. Se o use case precisar chamar outro use case, invoque-o diretamente. Se precisar chamar um serviço externo, injete a dependência.
O adaptador de infraestrutura recebe as injeções necessárias e implementa as interfaces definidas no domínio. Isso cria um fluxo unidirecional: interface chama aplicação, aplicação chama domínio, domínio não sabe nada sobre o resto. Para um projeto pequeno, isso leva cerca de duas horas para configurar a estrutura inicial. Para um projeto médio, uma tarde. O ganho aparece depois, quando você precisa adicionar uma nova funcionalidade ou mudar a fonte de dados. Em vez de refactorar dez arquivos espalhados, você altera um adaptador específico.
Caso difícil que encontrei pessoalmente
Tinha um projeto onde um use case precisava consultar dois repositórios diferentes simultaneamente. Um era de usuários, outro de transações. A tentação era criar um terceiro repositório que mesclasse os dados. Fazer isso quebra o princípio básico porque introduz uma dependência cruzada que não pertence ao domínio original. A solução foi criar um service na camada de aplicação que orquestrava as duas chamadas. O service não tem estado próprio, apenas encaminha dados entre os repositórios e aplica uma regra de negócio simples. Funciona bem até o número de repositórios envolvidos passar de três. Aí o método fica grande e difícil de testar.
👉 Clique no botão abaixo para saber mais sobre o assunto!
Quando isso acontece, a alternativa é extrair parte da lógica para um domínio mais específico. Isso significa refatorar o modelo principal, o que dá trabalho mas é mais sustentável do que acumular casos especiais em um único use case.
Erros comuns que atrapalham
Criar mais camadas do que o necessário. Não adianta dividir algo que já é pequeno. Um módulo com cinco responsabilidades diferentes não se torna melhor só porque você criou cinco diretórios vazios. A regra prática é: se um arquivo não passa de cem linhas e faz uma coisa clara, ele não precisa ser dividido. Outro erro é tornar todas as dependências injetáveis. Injeção de dependência é útil quando há mais de uma implementação possível ou quando você precisa testar isoladamente. Colocar injeção em tudo gera boilerplate desnecessário e complica a leitura do código.
O terceiro erro é ignorar a fronteira entre domínio e aplicação. Se sua entidade de domínio precisa saber se um campo é obrigatório para persistência, algo está errado. Regras de negócio são diferentes de regras de persistência.
Quando não usar essa abordagem
a turma do pato bill não funciona bem em scripts rápidos, protótipos ou projetos single-file. A estrutura adiciona overhead que só se justifica quando o sistema cresce. Também não é ideal para time que não tem disciplina de code review — sem revisão, as camadas acabam se misturando mesmo com a estrutura correta no papel. Se o projeto tem menos de mil linhas e vai ser mantido por uma pessoa, use uma organização simples com dois arquivos no máximo. Complexidade desnecessária só gera custo sem retorno.
Benefícios reais após alguns meses
Depois de aplicar essa estrutura em projetos de médio porte, notei que o tempo para adicionar novas features caiu de uma média de quatro horas para cerca de uma hora e meia. O motivo não é a estrutura em si, mas a previsibilidade. Quando você sabe exatamente onde procurar, não perde tempo navegando. Testes unitários ficam mais fáceis porque cada use case pode ser testado com mocks dos repositórios. Não precisa subir banco de dados nem configurar ambiente inteiro para validar uma regra de negócio. Isso economiza tempo de CI/CD também, já que testes mais isolados rodam mais rápido.
A desvantagem é clara:curva de aprendizado para desenvolvedores novos. Se a pessoa nunca viu essa separação, as primeiras duas semanas são de confusão. Documentar a estrutura inicial do projeto ajuda muito nesse ponto. Um README explicando onde cada coisa vai evita que novatos pirem nos primeiros commits.
Dicas rápidas para começar hoje
Não tente migrar um projeto existente inteiramente de uma vez. Comece pelo próximo módulo que você for criar e aplique a estrutura lá. Depois, migre gradualmente. Migrar tudo de uma vez gera risco alto de regressão e geralmente termina mal. Use nomes de arquivos que refletem a responsabilidade, não o tipo. repository.user é pior do que user.repository porque o primeiro não comunica onde a lógica vive. A nomenclatura consistente reduz ambiguidade durante code review.
Mantenha a camada de domínio sem dependências de frameworks. Se você precisar de alguma anotação específica ou library externa no domínio, reconsider a divisão. O domínio deve ser testável sem nenhum mock complexo. O resultado final é um código mais previsível, mais testável e mais fácil de manter. Nada revolucionário, apenas organização baseada em experiência prática de quem já viu código virar sopa de letras por falta de estrutura.
