1. Introdução: o que é Clean Architecture?

Clean Architecture, ou arquitetura limpa, é uma forma de organizar um sistema para que as regras importantes do negócio não fiquem presas a detalhes voláteis, como um framework web, um banco de dados ou um serviço externo. A ideia é manter o núcleo do sistema compreensível e protegido, mesmo quando a tecnologia ao redor muda.

O modelo foi popularizado por Robert C. Martin, conhecido como Uncle Bob, em artigos e no livro Clean Architecture: A Craftsman's Guide to Software Structure and Design, publicado em 2017. Ele não surgiu isolado: sintetiza décadas de ideias de engenharia de software, como arquitetura hexagonal de Alistair Cockburn, Onion Architecture de Jeffrey Palermo, princípios SOLID e separação entre política e mecanismo. Clean Architecture não é um framework nem uma receita de diretórios. É um conjunto de limites e regras para orientar decisões.

O contexto histórico ajuda a entender seu propósito. Aplicações começaram pequenas, com poucas telas e um banco simples, e cresceram para integrar equipes, dispositivos, provedores de pagamento, filas, serviços em nuvem e requisitos regulatórios. A tecnologia tornou mais fácil conectar componentes, mas também tornou fácil espalhar dependências por todo o código. Um detalhe aparentemente local — por exemplo, usar diretamente uma biblioteca de persistência dentro de uma regra de negócio — pode transformar uma troca de tecnologia em uma reescrita extensa.

A arquitetura limpa procura reduzir esse custo. Ela coloca as políticas de negócio no centro e direciona dependências de código para dentro. Assim, uma aplicação pode trocar a interface HTTP por uma tarefa em lote, substituir um banco relacional por outro ou executar um caso de uso em teste sem iniciar um servidor. O objetivo não é impedir mudanças, mas limitar o número de decisões que uma mudança afeta.

Uma analogia útil é a de um edifício com instalações substituíveis. O negócio é a estrutura que determina o uso do prédio; encanamento e fiação são essenciais, mas não deveriam decidir a finalidade de cada sala. Do mesmo modo, banco de dados e framework são importantes, porém servem às regras da aplicação. Essa separação é especialmente valiosa quando o sistema tem regras duradouras, integrações numerosas ou uma vida útil longa.

Isso não significa que toda aplicação precise de quatro projetos e dezenas de interfaces. A arquitetura deve tornar a mudança mais segura, não criar cerimônia. Uma página estática ou um CRUD descartável pode não justificar a estrutura completa. Para comparar a arquitetura em camadas com uma organização de solução .NET, veja também como organizar projetos .NET sem criar dependências acidentais.

2. Por que arquiteturas tradicionais geram problemas

“Tradicional” não designa um único padrão. O problema aparece quando a estrutura do código faz a regra de negócio depender diretamente de detalhes que deveriam ser substituíveis. Um projeto pode estar dividido em pastas chamadas Models, Services e Repositories e continuar fortemente acoplado. Nomes de diretórios não definem arquitetura; a direção real das dependências é que define.

Acoplamento e dependência de frameworks

Imagine um serviço de cadastro que recebe um HttpContext, consulta diretamente um ORM e publica mensagens em um cliente específico de nuvem. A regra “um e-mail não pode ser cadastrado duas vezes” passa a conhecer HTTP, banco e mensageria. Se o endpoint mudar, o provedor de banco for substituído ou o caso de uso precisar rodar numa importação, essas dependências entram no caminho.

Frameworks são ferramentas poderosas, mas seus tipos, convenções e ciclos de vida mudam. Quando o domínio herda de uma classe do framework ou usa diretamente seus atributos, a troca pode exigir alterações no núcleo. A consequência não é apenas migrar dependências: é revisar comportamento que deveria ser independente da interface e da persistência.

Testes difíceis e regras espalhadas

Se para testar uma regra é preciso levantar um servidor, criar um banco real e configurar credenciais, o ciclo de feedback fica lento. Desenvolvedores tendem então a testar menos ou a escrever testes frágeis, que verificam detalhes de implementação em vez de comportamento. O problema não é que toda integração precise ser simulada; é que uma regra pura de negócio não deveria exigir uma infraestrutura inteira para ser exercitada.

Regras também se dispersam quando validações aparecem em controllers, consultas SQL, procedures, formulários e rotinas agendadas. Cada entrada passa a implementar uma versão parcial da política. Com o tempo, uma rota permite algo que outra bloqueia, ou uma alteração corrige apenas um dos caminhos. Uma arquitetura útil reúne as decisões no lugar em que podem ser entendidas, nomeadas e testadas.

Camadas tradicionais podem funcionar bem enquanto os limites são respeitados. O sinal de alerta não é a existência de um controller ou ORM: é a regra central precisar conhecê-los. Clean Architecture tenta tornar essa separação explícita e verificável.

3. Princípios que fundamentam a Clean Architecture

Clean Architecture combina princípios de projeto conhecidos. Nenhum deles, sozinho, determina a arquitetura. Em conjunto, ajudam a criar componentes com responsabilidades claras e dependências controladas. O ponto é usar princípios para tomar decisões concretas, não decorar siglas.

SOLID aplicado com intenção

Single Responsibility incentiva componentes a terem um motivo coeso para mudar. Um caso de uso decide o fluxo de uma intenção do usuário; um adaptador traduz HTTP; um repositório persiste dados. Isso não significa uma classe por linha ou método, mas evitar concentrar razões de mudança independentes num único componente.

Open/Closed favorece estender comportamento por composição quando requisitos realmente variam. Liskov Substitution lembra que uma implementação deve respeitar as garantias do contrato que implementa. Interface Segregation evita interfaces genéricas que obrigam consumidores a depender de operações irrelevantes. Dependency Inversion orienta políticas de alto nível a depender de abstrações estáveis, não de detalhes concretos. Esses princípios se complementam, mas não exigem interfaces para cada classe.

Para uma explicação independente com exemplos, consulte o guia complementar de princípios SOLID na prática.

Separation of Concerns, encapsulamento e coesão

Separation of Concerns separa aspectos diferentes: regra de negócio, transporte, persistência e apresentação. Essa separação reduz a quantidade de contexto necessária para entender uma mudança. O encapsulamento protege invariantes: em vez de permitir que qualquer componente altere o estado de um pedido, a entidade expõe operações que validam transições permitidas.

Alta coesão significa que as partes de um componente colaboram para uma responsabilidade comum. Baixo acoplamento significa que ele depende de poucos detalhes externos. Esses objetivos não são absolutos: um sistema útil tem colaboração entre componentes. A meta é fazer com que a colaboração aconteça por contratos pequenos e explícitos, e que mudanças locais permaneçam locais.

Um exemplo: se uma política de desconto é implementada como uma função do domínio, ela pode ser exercitada sem abrir uma conexão. O adaptador web continua responsável por interpretar a requisição, mas não decide se o desconto é válido. Cada preocupação encontra um lugar, e o teste pode focar exatamente no comportamento relevante.

4. A Regra das Dependências (Dependency Rule)

A Dependency Rule é o eixo da Clean Architecture: dependências do código-fonte devem apontar para dentro, em direção a políticas mais estáveis e de maior valor para o negócio. O domínio não importa classes da aplicação; a aplicação não importa controller, ORM ou SDK de nuvem. Detalhes externos podem conhecer contratos internos para implementá-los, mas o núcleo não conhece os detalhes.

Pense nos círculos como níveis de política, não como etapas obrigatórias de execução. Mais perto do centro estão as regras de negócio mais gerais. Mais longe estão as decisões específicas de entrega e tecnologia. “Para dentro” é uma direção de dependência entre módulos e tipos; não significa que a requisição sempre percorra os círculos geometricamente.

O que pode depender de quê?

  • Entidades podem ser usadas por casos de uso.
  • Casos de uso podem depender de entidades e de contratos próprios, definidos para realizar a intenção de negócio.
  • Adaptadores de interface podem conhecer casos de uso e converter formatos externos para modelos internos e de volta.
  • Frameworks e drivers podem implementar contratos internos e fazer a composição concreta da aplicação.
  • O núcleo não deve importar tipos de ASP.NET, EF Core, SDKs de nuvem, bibliotecas de UI ou detalhes de serialização.

Quando um caso de uso precisa armazenar uma conta, ele pode depender de IUsuarioRepository, declarado na camada de aplicação ou no domínio conforme o papel semântico do contrato. O adaptador de persistência implementa essa interface usando SQL ou um ORM. Em tempo de execução, a aplicação chama a implementação concreta; em tempo de compilação, a política conhece apenas a abstração. Essa distinção entre fluxo de execução e dependência de código é crucial.

Erros comuns ao aplicar a regra

Um erro é colocar interfaces em um projeto chamado Shared que acaba conhecendo todos os frameworks. Outro é declarar abstrações no módulo externo e obrigar o núcleo a importar um pacote de infraestrutura para acessá-las. Também é comum chamar de “inversão” o simples fato de usar injeção de dependência: DI ajuda a conectar objetos, mas a direção das referências de código ainda precisa ser correta.

A regra não exige que cada dependência seja uma interface. Um tipo concreto, estável e de domínio pode ser mais simples e claro. A abstração é valiosa quando protege uma política de um detalhe variável ou quando expressa uma fronteira que precisa ser substituída em testes ou produção. Criar uma interface sem consumidor alternativo nem limite semântico pode só aumentar indirection.

5. As quatro camadas da Clean Architecture

O diagrama clássico descreve quatro círculos. Projetos reais podem agrupar ou renomear esses círculos, mas devem preservar as responsabilidades e a Dependency Rule. A camada é uma fronteira lógica; não precisa corresponder exatamente a um assembly, projeto ou diretório.

5.1 Entities: regras centrais do domínio

Responsabilidade: representar conceitos e invariantes duradouras do negócio. Em um sistema de pedidos, entidades podem ser Pedido, ItemPedido ou Cliente. Em um contexto rico, objetos de valor como Dinheiro e Email expressam conceitos com igualdade e validação próprias.

O que deve existir: comportamento do domínio, invariantes e decisões que continuam verdadeiras independentemente da aplicação que as utiliza. O que não deve existir: atributos de ORM, anotações HTTP, serialização, chamadas de rede ou acesso ao relógio global. Uma entidade que calcula se pode ser confirmada pode receber dados necessários explicitamente; não precisa consultar o banco por conta própria.

Uma regra como “uma conta suspensa não pode iniciar uma transferência” pertence ao modelo de negócio, não ao controller. Entidades não precisam sempre ter muitos métodos: o formato depende do domínio. O objetivo é não deixar invariantes críticas espalhadas nem permitir alterações inválidas por qualquer consumidor.

5.2 Use Cases: orquestração das intenções da aplicação

Responsabilidade: coordenar uma ação significativa, como cadastrar usuário, aprovar pedido ou emitir fatura. Um caso de uso define entradas, executa o fluxo, chama o domínio e as portas externas necessárias, e produz um resultado compreensível para o chamador.

O que deve existir: regras específicas do fluxo da aplicação, interfaces de entrada/saída quando fazem sentido, transação lógica e coordenação de políticas. O que não deve existir: parsing de HTTP, SQL específico, lógica de apresentação ou dependência direta de classes de framework. O caso de uso pode decidir que, após validar um usuário, deve pedir uma gravação e emitir um evento por uma porta.

O caso de uso não substitui o domínio: a entidade garante invariantes próprias; a aplicação coordena a sequência. Se o mesmo cálculo de preço aparecer em dois fluxos, vale investigar se é uma regra de domínio, em vez de copiar a lógica entre casos de uso.

5.3 Interface Adapters: tradução entre formatos

Responsabilidade: converter dados entre o mundo externo e os modelos úteis ao caso de uso. Controllers, presenters, view models, mapeadores e alguns repositórios pertencem conceitualmente a esta fronteira.

O que deve existir: tradução de DTO HTTP para entrada de caso de uso, apresentação da resposta, conversão de registros de persistência e implementações que adaptem uma porta interna à tecnologia externa. O que não deve existir: regra central do negócio nem decisão de infraestrutura acoplada ao caso de uso.

O adaptador impede que o formato de uma API se torne o formato interno do domínio. Uma alteração de JSON pode então ficar no controller e em seu DTO, sem mudar a entidade. Esse limite também reduz o risco de expor propriedades internas acidentalmente.

5.4 Frameworks & Drivers: detalhes substituíveis

Responsabilidade: fornecer mecanismos concretos: ASP.NET Core, EF Core, banco, sistema de arquivos, broker de mensagens, SDK de e-mail e interface gráfica. São detalhes importantes, mas normalmente não deveriam definir as políticas.

O que deve existir: inicialização, configuração, wiring de DI, implementações concretas e integração com ferramentas externas. O que não deve existir: a decisão final sobre uma regra de negócio que deveria viver no centro. Um ORM pode mapear a entidade, mas não deve se tornar o único lugar onde uma política essencial é expressa.

As fronteiras não proíbem o uso de um framework. Elas permitem usá-lo sem espalhar seus tipos pelo núcleo. Em projetos pequenos, a camada externa pode ser enxuta; em sistemas corporativos, pode conter vários adaptadores para diferentes provedores.

6. Fluxo completo: cadastro de usuário

Considere uma requisição POST /usuarios com nome e e-mail. O caminho da chamada e o caminho das dependências são ideias diferentes: a requisição entra pelos detalhes externos e chega ao caso de uso; as referências no código continuam apontando para abstrações internas.

  1. Entrada HTTP: ASP.NET Core recebe o JSON, autentica a requisição se necessário e seleciona o endpoint.
  2. Controller: valida formato básico do transporte e converte o DTO HTTP em um comando, sem decidir políticas de unicidade ou elegibilidade.
  3. Use case: CadastrarUsuario recebe o comando, normaliza valores conforme as regras acordadas e consulta uma porta de repositório.
  4. Domínio: a entidade Usuario é criada validando invariantes próprias, como um endereço normalizado e um nome obrigatório.
  5. Persistência: a implementação concreta da porta verifica a unicidade no banco e salva a entidade, conforme a garantia adotada pelo sistema.
  6. Resposta: o caso de uso devolve um resultado; o controller o converte para HTTP, por exemplo, 201 Created, 409 Conflict ou um erro de validação.

É importante notar que validar e-mail duplicado apenas em memória não evita uma corrida entre duas requisições simultâneas. A aplicação pode fazer uma consulta prévia para uma mensagem melhor, mas a restrição única do banco deve proteger a consistência concorrente. O adaptador traduz a violação para um resultado conhecido pela aplicação; o núcleo não precisa conhecer a exceção específica do provedor.

Cada camada tem uma pergunta distinta: o controller pergunta “como esta requisição é representada?”; o caso de uso pergunta “qual ação deve acontecer?”; o domínio pergunta “que estados são válidos?”; o adaptador de persistência pergunta “como gravar isso neste banco?”. Essa divisão permite testar cada decisão no nível adequado.

7. Exemplo prático simplificado em C#

O exemplo abaixo mostra as relações essenciais para cadastrar um usuário. Ele é intencionalmente pequeno: omite detalhes como autenticação, transações, logging e mapeamento do ORM para destacar os limites. Em um sistema de produção, a regra de unicidade deve também ser protegida por uma restrição no banco.

Entidade de domínio

public sealed class Usuario
{
    public Guid Id { get; }
    public string Nome { get; }
    public string Email { get; }

    private Usuario(Guid id, string nome, string email)
    {
        Id = id;
        Nome = nome;
        Email = email;
    }

    public static Usuario Criar(string nome, string email)
    {
        if (string.IsNullOrWhiteSpace(nome))
            throw new ArgumentException("Nome é obrigatório.", nameof(nome));

        if (string.IsNullOrWhiteSpace(email) || !email.Contains('@'))
            throw new ArgumentException("E-mail inválido.", nameof(email));

        return new Usuario(
            Guid.NewGuid(),
            nome.Trim(),
            email.Trim().ToLowerInvariant());
    }
}

A validação aqui é ilustrativa, não uma implementação completa do padrão de e-mail. O ponto arquitetural é que o objeto controla a criação de um estado válido e não herda de uma classe do ORM. Em um domínio maior, erros de validação poderiam ser representados por um tipo de resultado em vez de exceções.

Por que a entidade controla sua criação?

Se qualquer consumidor puder instanciar um usuário com campos vazios, cada fluxo terá de lembrar de validar o mesmo conjunto de regras. Uma fábrica de domínio oferece um ponto claro para proteger invariantes locais. Ela não deve, porém, consultar serviços externos: unicidade de e-mail envolve persistência e concorrência, por isso é coordenada pela aplicação e garantida também pelo banco.

Porta de repositório e caso de uso

public interface IUsuarioRepository
{
    Task<bool> ExisteComEmailAsync(
        string email,
        CancellationToken cancellationToken);

    Task AdicionarAsync(
        Usuario usuario,
        CancellationToken cancellationToken);
}

public sealed record CadastrarUsuarioCommand(string Nome, string Email);
public sealed record CadastrarUsuarioResult(Guid Id);

public sealed class CadastrarUsuario
{
    private readonly IUsuarioRepository _usuarios;

    public CadastrarUsuario(IUsuarioRepository usuarios)
    {
        _usuarios = usuarios;
    }

    public async Task<CadastrarUsuarioResult> ExecuteAsync(
        CadastrarUsuarioCommand command,
        CancellationToken cancellationToken)
    {
        var emailNormalizado = command.Email.Trim().ToLowerInvariant();

        if (await _usuarios.ExisteComEmailAsync(
                emailNormalizado, cancellationToken))
            throw new InvalidOperationException("E-mail já cadastrado.");

        var usuario = Usuario.Criar(command.Nome, emailNormalizado);
        await _usuarios.AdicionarAsync(usuario, cancellationToken);

        return new CadastrarUsuarioResult(usuario.Id);
    }
}

O contrato descreve o que a política precisa, não como consultar o banco. O caso de uso coordena a intenção. Um sistema mais maduro provavelmente usaria um erro de domínio ou resultado explícito para o conflito, e trataria a colisão concorrente no adaptador. O formato apresentado serve para mostrar a direção das dependências, não para prescrever uma única API.

Implementação de persistência e controller

public sealed class EfUsuarioRepository : IUsuarioRepository
{
    private readonly AppDbContext _db;

    public EfUsuarioRepository(AppDbContext db) => _db = db;

    public Task<bool> ExisteComEmailAsync(
        string email,
        CancellationToken cancellationToken) =>
        _db.Usuarios.AnyAsync(
            usuario => usuario.Email == email,
            cancellationToken);

    public async Task AdicionarAsync(
        Usuario usuario,
        CancellationToken cancellationToken)
    {
        _db.Usuarios.Add(usuario);
        await _db.SaveChangesAsync(cancellationToken);
    }
}
[ApiController]
[Route("usuarios")]
public sealed class UsuariosController : ControllerBase
{
    private readonly CadastrarUsuario _cadastrar;

    public UsuariosController(CadastrarUsuario cadastrar) =>
        _cadastrar = cadastrar;

    [HttpPost]
    public async Task<IActionResult> Post(
        CadastrarUsuarioRequest request,
        CancellationToken cancellationToken)
    {
        var result = await _cadastrar.ExecuteAsync(
            new CadastrarUsuarioCommand(request.Nome, request.Email),
            cancellationToken);

        return Created($"/usuarios/{result.Id}", result);
    }
}

public sealed record CadastrarUsuarioRequest(string Nome, string Email);

EfUsuarioRepository está na borda: conhece Entity Framework e implementa a interface que o caso de uso consome. O controller converte a entrada HTTP, mas não acessa o contexto de dados. Na inicialização, a injeção de dependência conecta IUsuarioRepository à implementação concreta. Essa configuração é um detalhe externo e pode ser trocada sem alterar a regra do caso de uso.

Testes unitários podem fornecer um repositório em memória e verificar o comportamento do caso de uso. Testes de integração devem, separadamente, verificar o mapeamento e as restrições do banco real. A arquitetura não elimina testes de ponta a ponta; ela torna possível usar cada tipo de teste para a pergunta que responde melhor.

8. Benefícios da Clean Architecture

Testabilidade e feedback mais rápido

Casos de uso e entidades que não dependem de servidor ou banco podem ser testados em processos rápidos. Isso favorece testes focados no comportamento: usuário duplicado é recusado? Uma conta bloqueada não consegue concluir a operação? Não é preciso simular toda a nuvem para responder a essas perguntas. A integração concreta continua importante e é testada na borda.

Separar teste unitário de integração

Um teste unitário pode usar uma implementação simples da porta para validar a decisão da aplicação; um teste de integração verifica se a implementação SQL respeita o contrato real. Essa distinção evita dois extremos: depender de um banco para testar toda regra ou acreditar que um mock prova que a consulta e a configuração de produção funcionam.

Manutenção, mudança e evolução

Uma fronteira explícita ajuda a localizar a mudança. Se a API passar de REST a uma fila, o mecanismo de entrada muda, mas a intenção do caso de uso pode permanecer. Se o provedor de e-mail mudar, a política de cadastro não deve precisar conhecer o SDK novo. A vantagem é reduzir o raio de impacto, não tornar toda migração gratuita.

Escalabilidade, reuso e independência tecnológica

Uma aplicação pode oferecer a mesma capacidade por mais de uma interface: API, tarefa agendada ou interface administrativa. O caso de uso pode ser reutilizado quando a intenção e as regras são realmente as mesmas. Como a arquitetura evita que tecnologia externa contamine o núcleo, torna-se mais viável avaliar opções tecnológicas com base em requisitos, sem reescrever regras de negócio para cada escolha.

Essa independência é relativa, não absoluta. Um sistema que depende de recursos específicos do banco ainda precisa representá-los de algum modo. O ganho está em tornar o acoplamento deliberado e localizado. Para equipes, isso também cria vocabulário compartilhado: adaptador, porta, caso de uso, entidade e fronteira têm significados discutíveis e revisáveis, em vez de dependerem de convenções implícitas.

9. Desvantagens e desafios

Curva de aprendizado e complexidade inicial

No início, a separação pode parecer mais lenta. A equipe precisa compreender por que o controller não chama diretamente o ORM, onde declarar uma porta e qual camada deve possuir determinado contrato. Se cada operação simples passa por muitos arquivos sem uma razão clara, a arquitetura virou custo de navegação em vez de proteção.

Overengineering e abstrações prematuras

Não é necessário criar uma interface para cada classe, um repositório genérico para cada tabela, um mapper próprio para cada DTO ou um mediador só para evitar uma chamada direta. Abstrações são úteis quando nomeiam uma fronteira, isolam uma decisão variável ou tornam uma política testável. Sem esse motivo, podem esconder o fluxo e multiplicar pontos de alteração.

Uma solução pequena, com regras simples e horizonte curto, pode funcionar melhor com menos camadas. Um protótipo descartável, uma página estática ou um CRUD interno sem lógica relevante não precisa imitar a arquitetura de um sistema financeiro. O custo de manutenção futuro deve justificar o investimento presente.

Quando adotar e como introduzir

Clean Architecture tende a ser valiosa quando o domínio é complexo, as regras mudam com frequência, há múltiplos canais de entrada ou integrações importantes, e o produto precisa viver por anos. Ela também ajuda quando alterações de infraestrutura hoje provocam regressões em regras centrais. Se o sistema ainda não tem essas pressões, comece com limites simples e reavalie conforme o conhecimento aumenta.

Em um sistema existente, evite uma reescrita arquitetural total como primeiro passo. Escolha um fluxo que muda com frequência, extraia o caso de uso e suas portas, mantenha o comportamento, e use testes para tornar a fronteira verificável. A arquitetura evolui melhor quando acompanha mudanças reais do produto.

10. Clean Architecture e DDD

Domain-Driven Design e Clean Architecture respondem a perguntas relacionadas, mas diferentes. DDD, associado ao trabalho de Eric Evans, oferece práticas para entender e modelar domínios complexos. Clean Architecture organiza dependências e separa políticas de detalhes. DDD ajuda a descobrir e expressar o que o negócio significa; arquitetura limpa ajuda a proteger essas regras das tecnologias que as executam.

Entre as ideias de DDD estão linguagem ubíqua, contextos delimitados, entidades, objetos de valor, agregados, serviços de domínio e eventos de domínio. Um contexto delimitado reconhece que uma palavra pode ter significados distintos em partes diferentes da organização. “Cliente” em faturamento pode não ser o mesmo conceito de “cliente” em suporte. Tentar forçar um modelo global costuma criar abstrações ambíguas.

As entidades da Clean Architecture e as entidades de DDD não são necessariamente sinônimos perfeitos. Clean Architecture usa “entities” para as regras de negócio mais centrais; DDD define padrões táticos com semântica mais específica. Uma classe anêmica com um identificador não se torna um bom modelo de domínio apenas porque está em um projeto chamado Domain.

Uma combinação prática pode ter agregados e objetos de valor no núcleo do domínio, casos de uso na camada de aplicação e adaptadores para banco e mensagens na borda. A aplicação carrega o agregado, solicita uma mudança válida e persiste o resultado. O agregado protege invariantes transacionais; o caso de uso coordena o fluxo que atravessa fronteiras.

DDD tático não é obrigatório em toda parte. Uma tela de configuração simples pode ser modelada sem agregados elaborados. Use linguagem ubíqua e contextos delimitados mesmo em sistemas menores quando ajudam a esclarecer conceitos; aplique os padrões mais sofisticados onde há complexidade de negócio real. Leia também o guia complementar de DDD: linguagem ubíqua, agregados e contextos delimitados.

11. Clean Architecture em aplicações modernas

APIs REST e microsserviços

Em uma API REST, controllers e serialização ficam nos adaptadores; os casos de uso não precisam conhecer códigos HTTP. Um erro de negócio pode ser transformado em 409 Conflict por um presenter ou middleware. Em microsserviços, cada serviço pode ter seu modelo e suas fronteiras. Separação interna não substitui desenho de limites entre serviços: dividir um monólito em serviços pequenos sem coesão pode apenas distribuir o acoplamento pela rede.

Frontend e aplicações mobile

O mesmo raciocínio vale para interfaces. Uma ação de usuário pode ser representada por uma intenção da aplicação; adaptadores traduzem dados de API, armazenamento local e componentes visuais. Uma tela não deveria ser a única guardiã de uma regra que também precisa valer em sincronização offline. Porém, arquitetura de frontend tem necessidades próprias, como estado de interface e navegação; não se deve copiar mecanicamente a estrutura de um backend.

Sistemas corporativos, tarefas e integrações

Em aplicações corporativas, um caso de uso pode ser iniciado por HTTP, por uma mensagem de fila ou por uma tarefa agendada. Cada entrada adapta seu formato à mesma política quando a intenção é idêntica. Saídas também podem ser adaptadores: banco, publicação de eventos, provedor de pagamentos ou serviço de identidade. Contratos internos evitam que o SDK de cada fornecedor vaze por todos os módulos.

A arquitetura não define automaticamente consistência distribuída, estratégia de retry, idempotência ou observabilidade. Esses são problemas adicionais. Em fluxos assíncronos, modele explicitamente o que ocorre quando uma chamada externa falha depois de o banco ter sido atualizado. Uma porta clara facilita trocar o mecanismo, mas não elimina a necessidade de desenhar a semântica da operação.

12. Principais erros que desenvolvedores cometem

Entidades anêmicas e domínio apenas nominal

Entidades que expõem setters para tudo e deixam todos os cálculos em serviços externos podem enfraquecer o encapsulamento. Isso nem sempre é errado — alguns modelos são naturalmente simples —, mas merece atenção quando invariantes críticas dependem de consumidores lembrarem de chamar a validação certa. Mover cada método para uma entidade também não resolve automaticamente: o comportamento deve pertencer ao conceito correto.

Controllers com regras de negócio

Controllers deveriam traduzir protocolo, não se tornar o lugar de decisões de elegibilidade, cobrança ou estado de pedido. Quando regras vivem ali, tarefas em lote e outros endpoints tendem a duplicá-las. Um controller enxuto não precisa ser vazio: pode cuidar de autenticação declarativa, binding, códigos HTTP e detalhes de transporte.

Inversão incorreta e abstrações em lugares errados

Criar uma interface não garante boa inversão. Se a interface apenas espelha cada método do ORM, usa tipos proprietários da infraestrutura ou está no módulo externo e obriga o núcleo a referenciá-lo, o limite continua frágil. Defina contratos a partir da necessidade do consumidor interno. O adaptador externo implementa essa necessidade.

Camadas demais, nomes confusos e cópia de modelos

Um fluxo pode acabar com DTO, command, request, model, entity, view model e response praticamente idênticos, todos mapeados sem uma fronteira real. Modelos separados são importantes quando têm razões diferentes para mudar, não como ritual. Também evite tratar “camada” como projeto obrigatório: às vezes um módulo bem organizado e dependências claras são suficientes.

Outro erro é presumir que repositório significa uma classe genérica Repository<T> para cada agregado. O contrato deve expressar operações que o caso de uso precisa. A abstração de persistência não deve esconder consultas complexas a ponto de piorar desempenho ou compreensão; mantenha a fronteira, mas deixe os detalhes de consulta no adaptador.

13. Boas práticas recomendadas

Dependency Injection e composição na borda

Use injeção de dependência para fornecer implementações aos consumidores, e mantenha o registro de serviços no ponto de composição externo. Prefira construtores explícitos para dependências obrigatórias. Evite que o domínio use um service locator global: isso esconde dependências e dificulta entender o que uma regra precisa.

Repository Pattern, portas e DTOs

Use um repositório quando ele representa uma coleção ou uma porta útil para carregar e persistir conceitos do domínio. Não o introduza automaticamente para cada tabela. DTOs são úteis para proteger contratos externos e impedir que a forma interna de uma entidade seja publicada como API. Eles também permitem que a API evolua sem forçar mudanças no domínio.

Testes em níveis adequados

Testes unitários devem cobrir invariantes e decisões sem infraestrutura. Testes de integração verificam adaptadores concretos, como persistência e mensageria. Testes ponta a ponta cobrem alguns fluxos críticos na composição real. Uma pirâmide equilibrada reduz feedback lento sem criar falsa confiança em mocks que apenas repetem a implementação.

Domain Events e consistência

Um evento de domínio registra algo que aconteceu e tem significado para o negócio, como PedidoConfirmado. Ele não é simplesmente um nome elegante para qualquer mensagem técnica. Eventos podem desacoplar reações, mas exigem decisões sobre momento de publicação, duplicidade e falhas. Em sistemas que gravam estado e publicam eventos, o padrão outbox é uma opção para coordenar esses efeitos sem depender de uma transação distribuída frágil.

Pequenos limites, documentação viva e observabilidade

Nomeie casos de uso pela intenção, mantenha contratos pequenos, documente decisões arquiteturais relevantes e revise limites quando o domínio mudar. Registre logs, métricas e rastreamento nos pontos de integração, sem acoplar o domínio a um fornecedor de observabilidade. A melhor arquitetura é aquela que a equipe consegue explicar, operar e alterar com segurança.

14. Conclusão: quando vale a pena adotar?

Clean Architecture é uma estratégia para proteger regras de negócio e reduzir o alcance de mudanças. Sua ideia central é simples: políticas importantes não devem depender de mecanismos externos. As quatro camadas — Entities, Use Cases, Interface Adapters e Frameworks & Drivers — dão vocabulário a essa separação, enquanto a Dependency Rule define para onde as referências de código devem apontar.

Vale considerar a arquitetura quando o sistema tem vida longa, regras relevantes, integrações variadas ou mudanças frequentes. Não é uma medalha de qualidade nem uma obrigação para qualquer programa. Aplique o mínimo de estrutura que mantenha o fluxo claro; adicione uma abstração quando ela proteger uma fronteira real; remova camadas que só repetem dados sem acrescentar significado.

Roteiro de aprendizado

  1. Comece identificando regras de negócio e detalhes técnicos em um fluxo real.
  2. Estude SOLID com exemplos e observe especialmente Dependency Inversion e Interface Segregation.
  3. Pratique casos de uso que recebem dados simples e dependem de portas explícitas.
  4. Aprenda DDD para modelar domínios complexos com linguagem compartilhada.
  5. Adicione testes unitários e de integração que verifiquem comportamentos e fronteiras distintas.
  6. Revise a arquitetura com base nas mudanças reais, não em diagramas idealizados.

Se a equipe consegue explicar por que cada dependência existe, localizar uma regra e mudar um adaptador sem reescrever o núcleo, a arquitetura está cumprindo seu papel. Para aprofundar a organização de uma solução C#, siga para organização de projetos .NET; para conectar decisões de arquitetura a conceitos de domínio, continue em DDD na prática.