EF Core em Clean Architecture: a abordagem pragmática

Clean Architecture: princípios e camadas

A Clean Architecture organiza a aplicação em quatro camadas concêntricas, cada uma com uma responsabilidade bem definida.

A camada Domain concentra as entidades, os objetos de valor e as regras de negócio centrais. Ela não depende de nenhum framework externo.

A camada Application contém os casos de uso, os commands, as queries e os handlers. Para executar suas operações, ela depende apenas do Domain.

A camada Infrastructure implementa os detalhes externos, como banco de dados, cache, mensageria, identidade e integrações com terceiros.

A camada Presentation é o ponto de entrada da aplicação. Pode ser uma Web API, um serviço gRPC, um app Blazor, um projeto MVC ou qualquer outra interface.

EF Core em Clean Architecture com repositórios

Na configuração clássica de EF Core em Clean Architecture, a camada de Application define contratos de repositório. Em seguida, a Infrastructure implementa essas interfaces.

public interface IShipmentRepository
{
    Task<Shipment?> GetByIdAsync(Guid id, CancellationToken cancellationToken);
    Task<bool> ExistsForOrderAsync(string orderId, CancellationToken cancellationToken);
    Task AddAsync(Shipment shipment, CancellationToken cancellationToken);
}

public interface IUnitOfWork
{
    Task<int> SaveChangesAsync(CancellationToken cancellationToken);
}

A implementação na Infrastructure usa o EF Core internamente.

internal sealed class ShipmentRepository(ShipmentsDbContext context) : IShipmentRepository
{
    public Task<Shipment?> GetByIdAsync(Guid id, CancellationToken cancellationToken)
        => context.Shipments
            .Include(x => x.Items)
            .FirstOrDefaultAsync(x => x.Id == id, cancellationToken);

    public Task<bool> ExistsForOrderAsync(string orderId, CancellationToken cancellationToken)
        => context.Shipments.AnyAsync(x => x.OrderId == orderId, cancellationToken);

    public async Task AddAsync(Shipment shipment, CancellationToken cancellationToken)
        => await context.Shipments.AddAsync(shipment, cancellationToken);
}

Os handlers recebem as abstrações por injeção de dependência e nunca tocam no DbContext.

internal sealed class CreateShipmentHandler(
    IShipmentRepository repository,
    IUnitOfWork unitOfWork,
    ILogger<CreateShipmentHandler> logger)
{
    public async Task<Result<ShipmentResponse>> HandleAsync(
        CreateShipmentCommand command,
        CancellationToken cancellationToken)
    {
        var exists = await repository.ExistsForOrderAsync(command.OrderId, cancellationToken);
        if (exists)
            return ShipmentErrors.AlreadyExists(command.OrderId);

        var shipment = command.MapToShipment();

        await repository.AddAsync(shipment, cancellationToken);
        await unitOfWork.SaveChangesAsync(cancellationToken);

        return shipment.MapToResponse();
    }
}

À primeira vista, tudo parece correto. A Dependency Rule fica preservada, e os testes podem trocar a implementação real por um mock.

Se você quer revisar como esse padrão funciona em detalhes, o artigo sobre Repository Pattern com C# e Entity Framework cobre a implementação clássica.

Os problemas dos repositórios sobre EF Core em Clean Architecture

À medida que o projeto evolui, essa abordagem de EF Core em Clean Architecture começa a mostrar problemas recorrentes.

public interface IShipmentRepository
{
    Task<Shipment?> GetByIdAsync(...);
    Task<List<Shipment>> GetByOrderIdAsync(...);
    Task<List<Shipment>> GetByCarrierAsync(...);
    Task<List<Shipment>> GetActiveAsync(...);
    Task<List<Shipment>> GetByStatusAsync(...);
    Task<List<Shipment>> GetCreatedBetweenAsync(...);
    Task<List<Shipment>> GetWithItemsAsync(...);
    // muitos outros...
}

EF Core em Clean Architecture com DbContext nos casos de uso

A abordagem pragmática de EF Core em Clean Architecture preserva os princípios essenciais da arquitetura. Contudo, ela elimina a camada de repositório onde essa camada não agrega valor real.

A mudança central é simples. A camada de Application passa a depender do pacote Microsoft.EntityFrameworkCore e do DbContext da aplicação.

O Domain continua livre de frameworks. Já a Infrastructure mantém a configuração do DbContext, as migrations, os interceptors e as integrações externas.

O mesmo CreateShipmentHandler fica assim nessa abordagem:

internal sealed class CreateShipmentHandler(
    ShipmentsDbContext context,
    ILogger<CreateShipmentHandler> logger)
{
    public async Task<Result<ShipmentResponse>> HandleAsync(
        CreateShipmentCommand command,
        CancellationToken cancellationToken)
    {
        var exists = await context.Shipments
            .AnyAsync(x => x.OrderId == command.OrderId, cancellationToken);

        if (exists)
        {
            logger.LogInformation("Shipment for order '{OrderId}' already exists", command.OrderId);
            return ShipmentErrors.AlreadyExists(command.OrderId);
        }

        var shipment = command.MapToShipment();

        await context.Shipments.AddAsync(shipment, cancellationToken);
        await context.SaveChangesAsync(cancellationToken);

        logger.LogInformation("Created shipment: {@Shipment}", shipment);

        return shipment.MapToResponse();
    }
}

A quantidade de código no caso de uso permanece a mesma. Por outro lado, a interface do repositório e sua implementação deixam de existir.

public static class InfrastructureServiceCollectionExtensions
{
    public static IServiceCollection AddInfrastructure(
        this IServiceCollection services,
        IConfiguration configuration)
    {
        var connectionString = configuration.GetConnectionString("Shipments")
            ?? throw new InvalidOperationException("Connection string 'Shipments' not found.");

        // registra o contexto como scoped, um por requisição
        services.AddDbContext<ShipmentsDbContext>(options =>
            options.UseNpgsql(connectionString));

        return services;
    }
}

internal sealed class GetShipmentByNumberHandler(ShipmentsDbContext context)
{
    public async Task<Result<ShipmentResponse>> HandleAsync(
        string shipmentNumber,
        CancellationToken cancellationToken)
    {
        var shipment = await context.Shipments
            .Include(x => x.Items)
            .FirstOrDefaultAsync(x => x.Number == shipmentNumber, cancellationToken);

        if (shipment is null)
            return ShipmentErrors.NotFound(shipmentNumber);

        return shipment.MapToResponse();
    }
}

EF Core em Clean Architecture e a troca de banco

Esse é o argumento mais comum a favor do repositório no EF Core em Clean Architecture, e ele merece uma resposta direta.

Na prática, a grande maioria dos projetos nunca troca de banco em produção. Além disso, quando a troca acontece entre bancos relacionais, como de SQL Server para PostgreSQL, o próprio EF Core já faz o papel de abstração por meio dos providers.

Migrar de um banco relacional para um banco de documentos, como MongoDB ou Cosmos DB, exige muito mais. O modelo de dados muda, as regras de consistência mudam e os padrões de consulta também mudam.

Nesse cenário, os casos de uso precisam de reescrita de qualquer forma, com ou sem repositório. Por isso, um repositório criado só para essa hipótese raramente paga o próprio custo.

Testando EF Core em Clean Architecture sem repositórios

Remover repositórios não prejudica a testabilidade do EF Core em Clean Architecture. Na verdade, essa decisão muda a forma de testar, e a mudança tende a ser positiva.

A estratégia de testes recomendada pela Microsoft começa justamente por boa cobertura contra o banco de produção. Segundo a documentação, esses testes são necessários em qualquer caso, então vale começar por eles.

[Fact]
public async Task CreateShipment_AlreadyExists_ReturnsConflict()
{
    await using var factory = new ShipmentsApiFactory();
    using var scope = factory.Services.CreateScope();
    var context = scope.ServiceProvider.GetRequiredService<ShipmentsDbContext>();
    var handler = scope.ServiceProvider.GetRequiredService<CreateShipmentHandler>();

    // prepara um envio já existente para o mesmo pedido
    context.Shipments.Add(ShipmentFactory.New("ORDER-1"));
    await context.SaveChangesAsync();

    var result = await handler.HandleAsync(
        new CreateShipmentCommand(OrderId: "ORDER-1"),
        CancellationToken.None);

    result.IsError.Should().BeTrue();
    result.Errors.Should().ContainSingle(e => e.Type == ErrorType.Conflict);
}

Reuso de queries no EF Core em Clean Architecture

No EF Core em Clean Architecture, queries complexas usadas em vários lugares não precisam de um repositório para evitar duplicação.

A primeira alternativa são extension methods sobre IQueryable<T>, que encapsulam filtros e includes reutilizáveis de forma componível.

public static class ShipmentQueryableExtensions
{
    public static IQueryable<Shipment> WithItems(this IQueryable<Shipment> query)
        => query.Include(x => x.Items);

    public static IQueryable<Shipment> ActiveOnly(this IQueryable<Shipment> query)
        => query.Where(x => x.Status != ShipmentStatus.Cancelled);
}

// Em um handler:
var shipment = await context.Shipments
    .WithItems()
    .ActiveOnly()
    .FirstOrDefaultAsync(x => x.Number == number, ct);

Como as extensões trabalham sobre IQueryable<T>, o EF Core traduz a composição inteira para um único SQL. Se a diferença entre IQueryable e IEnumerable ainda gera dúvida, o artigo sobre IEnumerable vs IQueryable no EF explica o impacto na tradução.

A segunda alternativa é o Specification Pattern, adequado para queries dinâmicas e combináveis. Cada especificação é uma pequena classe que descreve um filtro e uma ordenação.

Os casos de uso combinam essas especificações conforme a necessidade. Assim, as duas alternativas entregam reuso sem acoplar todos os handlers a uma interface monolítica.

Quando o EF Core em Clean Architecture ainda pede repositórios

A abordagem pragmática de EF Core em Clean Architecture não elimina repositórios em todos os cenários. Em algumas situações, eles continuam sendo a escolha correta.

Queries muito complexas e amplamente reutilizadas. Quando uma query percorre vários agregados, envolve joins pesados e aparece em dezenas de features, centralizar essa lógica reduz duplicação.

Convenções do time. Em organizações com diretrizes que exigem repositórios para manter a consistência entre equipes, seguir a convenção pode ser a decisão pragmática.

Preocupações transversais de infraestrutura. Se você precisa decorar o acesso a dados com cache, logging ou auditoria, e os interceptors do EF Core não atendem, um wrapper pode ser a solução mais simples.

Múltiplas fontes de dados. Quando o projeto combina EF Core com uma API externa e um banco legado, um repositório funciona como fachada para unificar essas fontes.

Uso de Dapper. Com Dapper, o repositório continua essencial para isolar o SQL do restante da aplicação.

O artigo sobre Dapper com Unit of Work e Repository Pattern mostra esse cenário.

Testes com dublês. Como vimos, a Microsoft recomenda repositórios quando a estratégia de testes depende de mocks da camada de dados.

Conclusão

A abordagem pragmática de EF Core em Clean Architecture preserva o que realmente importa. O Domain permanece livre de frameworks, os limites entre camadas continuam claros e as regras de negócio ficam protegidas.

Por outro lado, ela elimina a cerimônia desnecessária. Saem as interfaces que duplicam abstrações do EF Core, os arquivos que crescem a cada feature e os testes que criam uma falsa sensação de segurança.

Com o DbContext direto na Application, o EF Core em Clean Architecture tende a gerar menos código, entregas mais rápidas e testes mais confiáveis.

Enfim, a regra de dependência continua valendo onde ela de fato protege o sistema. A diferença é que ela deixa de virar ritual onde não traz benefício concreto.

FAQ

Usar o DbContext na camada de Application viola a Clean Architecture?

Não viola o espírito da Clean Architecture, porque a Dependency Rule existe para proteger o Domain. O EF Core na Application é a escolha do ORM do projeto, e trocá-lo exigiria reescrita com ou sem repositórios.

Como evitar queries duplicadas sem um repositório?

Use extension methods sobre IQueryable<T> ou o Specification Pattern. Os dois são componíveis e reutilizáveis sem interfaces monolíticas.

Testes de integração com Testcontainers não são lentos demais?

Eles são mais lentos que testes com mocks, mas validam a tradução para SQL, os includes e as constraints. A Microsoft recomenda começar por testes contra o banco real.

Ainda posso usar repositórios nessa abordagem?

Sim. A abordagem pragmática não proíbe repositórios, apenas os torna opcionais e os aplica onde geram valor mensurável.

Posso usar o provider InMemory para testar os handlers?

A Microsoft desencoraja esse uso, porque o InMemory não suporta transações nem SQL e se comporta diferente do banco real. Se precisar de um banco falso, prefira o SQLite em memória.

Essa abordagem funciona bem com CQRS?

Sim. As queries usam o DbContext com projeções e joins otimizados, e os commands seguem o mesmo padrão.

A recomendação vale também para Dapper?

Não. Com Dapper, os repositórios continuam recomendados, porque o SQL precisa ficar isolado do restante da aplicação.