Padrões de Arquitetura

Domine padrões de arquitetura de backend comprovados, incluindo Arquitetura Limpa, Arquitetura Hexagonal e Design Orientado a Domínio, para construir sistemas de fácil manutenção, testáveis e escaláveis.

Dado: um limite de serviço ou módulo para arquitetar. Produz: estrutura em camadas com regras claras de dependência, definições de interface e limites de teste.

Quando Usar Esta Habilidade

• Projetar novos serviços de backend ou microsserviços do zero
• Refatorar aplicações monolíticas onde a lógica de negócios está entrelaçada com modelos ORM ou preocupações HTTP
• Estabelecer contextos delimitados antes de dividir um sistema em serviços
• Depurar ciclos de dependência onde o código de infraestrutura vaza para a camada de domínio
• Criar bases de código testáveis onde testes de casos de uso não exigem um banco de dados em execução
• Implementar padrões táticos de design orientado a domínio (agregados, objetos de valor, eventos de domínio)

Conceitos Principais

1. Arquitetura Limpa (Uncle Bob)

Camadas (fluxo de dependência para dentro):

• Entidades: Modelos centrais de negócios, sem importações de framework
• Casos de Uso: Regras de negócios da aplicação, orquestram entidades
• Adaptadores de Interface: Controladores, apresentadores, gateways — traduzem entre casos de uso e formatos externos
• Frameworks e Drivers: UI, banco de dados, serviços externos — todos no anel mais externo

Princípios Chave:

• As dependências apontam apenas para dentro; as camadas internas não sabem nada sobre as camadas externas
• A lógica de negócios é independente de frameworks, bancos de dados e mecanismos de entrega
• Cada limite de camada é cruzado por meio de uma interface abstrata
• Testável sem UI, banco de dados ou serviços externos

2. Arquitetura Hexagonal (Portas e Adaptadores)

Componentes:

• Núcleo de Domínio: A lógica de negócios reside aqui, livre de frameworks
• Portas: Interfaces abstratas que definem como o núcleo interage com o mundo exterior (direcionando e direcionado)
• Adaptadores: Implementações concretas de portas (adaptador PostgreSQL, adaptador Stripe, adaptador REST)

Benefícios:

• Trocar implementações sem tocar no núcleo (por exemplo, substituir PostgreSQL por DynamoDB)
• Usar adaptadores em memória em testes — sem necessidade de Docker
• Decisões de tecnologia adiadas para as bordas

3. Design Orientado a Domínio (DDD)

Padrões Estratégicos:

• Contextos Delimitados: Isole um modelo coerente para um subdomínio; evite compartilhar um único modelo em todo o sistema
• Mapeamento de Contexto: Defina como os contextos se relacionam (Camada Anticorrupção, Kernel Compartilhado, Serviço Host Aberto)
• Linguagem Ubíqua: Cada termo no código corresponde ao termo usado pelos especialistas de domínio

Padrões Táticos:

• Entidades: Objetos com identidade estável que mudam ao longo do tempo
• Objetos de Valor: Objetos imutáveis identificados por seus atributos (Email, Dinheiro, Endereço)
• Agregados: Limites de consistência; apenas a raiz é acessível de fora
• Repositórios: Persistem e reconstituem agregados; abstraem o mecanismo de armazenamento
• Eventos de Domínio: Capturam coisas que aconteceram dentro do domínio; usados para coordenação entre agregados

Padrões detalhados e exemplos práticos

A documentação detalhada dos padrões está em references/details.md. Leia esse arquivo quando o nível de navegação acima for insuficiente.

Testes — Adaptadores em Memória

A marca registrada da Arquitetura Limpa aplicada corretamente é que cada caso de uso pode ser exercitado em um teste unitário simples, sem banco de dados real, sem Docker e sem rede:

# tests/unit/test_create_user.py
import asyncio
from typing import Dict, Optional
from domain.entities.user import User
from domain.interfaces.user_repository import IUserRepository
from use_cases.create_user import CreateUserUseCase, CreateUserRequest


class InMemoryUserRepository(IUserRepository):
    def __init__(self):
        self._store: Dict[str, User] = {}

    async def find_by_id(self, user_id: str) -> Optional[User]:
        return self._store.get(user_id)

    async def find_by_email(self, email: str) -> Optional[User]:
        return next((u for u in self._store.values() if u.email == email), None)

    async def save(self, user: User) -> User:
        self._store[user.id] = user
        return user

    async def delete(self, user_id: str) -> bool:
        return self._store.pop(user_id, None) is not None


async def test_create_user_succeeds():
    repo = InMemoryUserRepository()
    use_case = CreateUserUseCase(user_repository=repo)

    response = await use_case.execute(CreateUserRequest(email="alice@example.com", name="Alice"))

    assert response.success

…