Macoratti   CQS e CQRS: Entenda a diferença na prática
Macoratti    Este artigo apresenta as diferenças entre CQS (Command Query Separation) e CQRS (Command Query Responsibility Segregation), utilizando exemplos em C# de um sistema de gerenciamento de pedidos. (Gerado com ajuda da IA, ajustado e revisado por Macoratti)

É bastante comum encontrar os termos CQS (Command Query Separation) e CQRS (Command Query Responsibility Segregation) em discussões sobre arquitetura de software, Domain-Driven Design (DDD) e desenvolvimento de aplicações corporativas.

 

Embora estejam relacionados e compartilhem uma ideia fundamental - separar operações de leitura e escrita -, esses conceitos possuem objetivos e níveis de aplicação diferentes.

Essa proximidade conceitual pode gerar alguma confusão, principalmente quando começamos a estudar CQRS e encontramos implementações que utilizam Commands, Queries e Handlers, mas não apresentam uma separação efetiva entre os modelos de leitura e escrita.

Neste artigo, vamos compreender a diferença entre CQS e CQRS utilizando um exemplo prático de um sistema de gerenciamento de pedidos desenvolvido em C#.

A ideia é partir de uma implementação simples, identificar o princípio aplicado e, em seguida, evoluir a arquitetura para entender onde CQRS realmente faz diferença.

1. CQS (Command Query Separation): separando leitura e escrita

O princípio CQS foi popularizado por Bertrand Meyer e estabelece uma regra bastante simples:

Uma operação deve executar uma ação que modifica o estado do sistema ou retornar informações sobre esse estado, mas não deve fazer as duas coisas simultaneamente.

Em outras palavras, devemos distinguir dois tipos de operações:

• Command: representa uma solicitação para executar uma ação que pode modificar o estado do sistema.
• Query: representa uma solicitação para consultar informações sem modificar o estado do sistema.

Vamos imaginar um sistema de gerenciamento de pedidos que possui uma entidade Pedido:

public class Pedido
{
    public Guid Id { get; private set; }
    public string Cliente { get; private set; }
    public decimal ValorTotal { get; private set; }
    public PedidoStatus Status { get; private set; }

    public void Aprovar()
    {
        Status = PedidoStatus.Aprovado;
    }
}

Precisamos implementar duas funcionalidades:

• Consultar os dados de um pedido.
• Aprovar um pedido.

Uma implementação inicial poderia ser:

public class PedidoService
{
    public Pedido? ObterPedido(Guid id)
    {
        // Consulta o pedido
    }

    public void AprovarPedido(Guid id)
    {
        // Altera o status do pedido
    }
}

Observe que temos duas operações com responsabilidades distintas.

O método ObterPedido() recupera informações e não deve modificar o estado do pedido.

Já AprovarPedido() executa uma ação que modifica o estado do pedido, mas não precisa retornar os dados desse pedido.

Essa separação caracteriza a aplicação do princípio CQS.

É importante destacar que CQS não exige classes diferentes, bancos de dados diferentes ou modelos distintos. Trata-se de um princípio aplicado ao comportamento das operações.

Podemos ter métodos de leitura e escrita na mesma classe e continuar respeitando CQS, desde que suas responsabilidades estejam separadas.

1.1. Visualizando o princípio CQS

Podemos representar o princípio da seguinte maneira:

Command - Escrita

• Recebe uma solicitação.
• Executa uma ação.
• Pode modificar o estado do sistema.
• Não retorna dados como resultado da operação.

Exemplo: AprovarPedido(Guid pedidoId);

Query - Leitura

• Recebe uma solicitação.
• Recupera informações.
• Não modifica o estado do sistema.
• Retorna os dados solicitados.

Exemplo: Pedido? ObterPedido(Guid pedidoId);

A ideia central é evitar que uma mesma operação misture responsabilidades de leitura e escrita.

2. CQRS: indo além da separação das operações

Agora imagine que nosso sistema de gerenciamento de pedidos cresceu.

Inicialmente, tínhamos apenas funcionalidades para cadastrar, consultar e aprovar pedidos. Com o crescimento da aplicação, surgiram novas necessidades:

• Uma tela de gerenciamento de pedidos.
• Um painel gerencial com indicadores de vendas.
• Relatórios de pedidos por cliente.
• Consultas que precisam combinar informações de pedidos, clientes, produtos e pagamentos.
• Consultas que precisam apresentar milhares de registros com rapidez.

Nesse cenário, começamos a perceber que as necessidades de leitura são bastante diferentes das necessidades de escrita.

Quando precisamos aprovar um pedido, por exemplo, devemos carregar o agregado Pedido, verificar suas regras de negócio, executar seu comportamento e persistir as alterações.

Por outro lado, quando precisamos gerar um relatório de vendas, não precisamos carregar agregados nem executar comportamentos de domínio. Precisamos recuperar e apresentar os dados de maneira eficiente.

Utilizar exatamente o mesmo modelo para atender a essas duas necessidades pode gerar complexidade desnecessária.

É nesse contexto que CQRS se torna interessante.

CQRS significa Command Query Responsibility Segregation e propõe separar as responsabilidades de leitura e escrita, permitindo que cada lado tenha seu próprio modelo, otimizado para sua finalidade.

Temos, portanto, dois lados:

• Write Model: responsável pelas operações de escrita e pela proteção das regras de negócio.
• Read Model: responsável pelas operações de leitura e pela apresentação eficiente das informações.

O modelo de escrita é orientado ao comportamento e às regras do domínio. O modelo de leitura é orientado à recuperação e à apresentação dos dados.

3. Entendendo CQRS visualmente

Imagine agora que o sistema de pedidos possui uma arquitetura organizada em dois lados.

Lado da escrita - Write Model

Quando precisamos aprovar um pedido:

• Recebemos um AprovarPedidoCommand.
• O handler recupera o agregado Pedido.
• O domínio executa as validações necessárias.
• O pedido tem seu estado alterado.
• As alterações são persistidas.

O objetivo é proteger as regras de negócio e garantir a consistência do domínio.

Lado da leitura - Read Model

Quando precisamos consultar um pedido:

• Recebemos um ObterPedidoQuery.
• O handler executa uma consulta otimizada.
• Os dados necessários são recuperados.
• Um DTO é retornado para a aplicação.

O objetivo é recuperar e apresentar informações com eficiência.

Esses dois lados podem utilizar os mesmos dados armazenados, mas não precisam utilizar as mesmas classes, abstrações ou estratégias de acesso.

4. Implementando CQRS com C#

Vamos observar como essa separação pode ser implementada em uma aplicação .NET.

4.1. Implementando o lado da escrita

Primeiro, definimos o Command que representa a solicitação de aprovação de um pedido:

public record AprovarPedidoCommand(Guid PedidoId);

Em seguida, implementamos seu handler:

public class AprovarPedidoHandler(IPedidoRepository repository)
{
    public async Task HandleAsync(AprovarPedidoCommand command)
    {
        var pedido = await repository
            .ObterPorIdAsync(command.PedidoId);

        if (pedido is null)
            throw new Exception("Pedido não encontrado");

        pedido.Aprovar();

        await repository.AtualizarAsync(pedido);
    }
}

Observe alguns aspectos importantes:

• O handler recebe um Command.
• O pedido é recuperado por meio de um repositório.
• O comportamento Aprovar() é executado no próprio agregado.
• As alterações são persistidas.

Estamos utilizando o modelo de domínio para realizar a operação de escrita, preservando o encapsulamento e as regras de negócio.

4.2. Implementando o lado da leitura

Agora precisamos consultar um pedido. Podemos começar definindo uma Query:

public record ObterPedidoQuery(Guid PedidoId);

Para representar os dados retornados, criamos um DTO:

public record PedidoDto(
    Guid Id,
    string Cliente,
    decimal ValorTotal,
    string Status);

Observe que esse DTO não precisa reproduzir toda a estrutura do agregado Pedido. Ele contém somente os dados necessários para a consulta.

Agora implementamos o handler:

public class ObterPedidoHandler(IDbConnection connection)
{
    public async Task<PedidoDto?> HandleAsync(ObterPedidoQuery query)
    {
        const string sql = """
            SELECT
                p.Id,
                c.Nome AS Cliente,
                p.ValorTotal,
                p.Status
            FROM Pedidos p
            INNER JOIN Clientes c
                ON c.Id = p.ClienteId
            WHERE p.Id = @PedidoId
            """;

        return await connection.QuerySingleOrDefaultAsync<PedidoDto>(
                sql,
                new
                {
                    query.PedidoId
                });
    }
}

Nesse exemplo, utilizamos Dapper para executar uma consulta SQL diretamente no banco de dados.

Observe a diferença em relação ao lado da escrita:

• Não precisamos carregar o agregado Pedido.
• Não precisamos utilizar o repositório de domínio.
• Não precisamos executar comportamentos do domínio.
• Recuperamos diretamente os dados necessários para construir o DTO.

Isso permite que o modelo de leitura seja otimizado de acordo com as necessidades das consultas.

5. É necessário utilizar bancos de dados diferentes?

Não!

Esse é um dos equívocos mais comuns quando começamos a estudar CQRS.

A separação entre os modelos de leitura e escrita não exige necessariamente bancos de dados diferentes.

Podemos implementar CQRS utilizando um único banco de dados relacional, mantendo:

• O modelo de domínio para as operações de escrita.
• Consultas SQL otimizadas para as operações de leitura.
• DTOs específicos para representar os resultados das consultas.

Essa abordagem é conhecida como CQRS com banco de dados compartilhado.

Em cenários mais complexos, podemos evoluir para bancos de dados distintos, cada um otimizado para uma finalidade.

Por exemplo:

• SQL Server para armazenar os dados transacionais.
• Uma estrutura de leitura otimizada para relatórios e consultas.
• Um mecanismo de sincronização para manter os modelos atualizados.

Nesse caso, podemos inclusive trabalhar com consistência eventual, pois as atualizações realizadas no modelo de escrita podem levar algum tempo para aparecer no modelo de leitura.

Essa arquitetura traz vantagens, mas também introduz complexidade adicional.

Por isso, a utilização de bancos separados deve ser uma decisão baseada nas necessidades reais da aplicação, e não uma exigência para adotar CQRS.

6. CQS e CQRS: qual é a diferença afinal?

Depois de observar os exemplos, podemos resumir as diferenças:

CaracterísticaCQSCQRS
ObjetivoSeparar operações de leitura e escritaSeparar responsabilidades e modelos de leitura e escrita
Nível de aplicaçãoPrincípio de projetoPadrão arquitetural
Classes distintasNão exigeNormalmente utiliza componentes distintos
Modelos distintosNão exigePermite modelos específicos para leitura e escrita
Bancos distintosNão exigeOpcional
ComplexidadeBaixaPode ser maior
A distinção fundamental está no alcance de cada conceito.

CQS estabelece que uma operação deve consultar informações ou modificar o estado do sistema, mas não deve fazer as duas coisas simultaneamente.

CQRS utiliza essa separação como ponto de partida e propõe uma organização arquitetural em que os modelos de leitura e escrita podem evoluir independentemente.

7. Utilizar Command, Query e Handler significa implementar CQRS?

Não necessariamente.

É comum encontrarmos implementações que utilizam classes como:

• AprovarPedidoCommand
• ObterPedidoQuery
• AprovarPedidoHandler
• ObterPedidoHandler

Essa organização já estabelece uma separação explícita entre as solicitações de leitura e escrita.

Entretanto, criar Commands, Queries e Handlers não significa automaticamente que temos dois modelos independentes de leitura e escrita.

Se ambos os lados utilizam o mesmo modelo de dados e a mesma estrutura de acesso, podemos estar diante de uma implementação simplificada de CQRS, com separação lógica das responsabilidades.

A arquitetura pode evoluir gradualmente, introduzindo modelos de leitura específicos, projeções, mecanismos de sincronização e até bancos de dados distintos, quando houver necessidade.

O mais importante é entender que CQRS não deve ser adotado apenas porque está na moda ou porque parece uma arquitetura mais sofisticada. Ele deve resolver problemas concretos da aplicação.

8. Conclusão

CQS e CQRS estão relacionados, mas não representam a mesma coisa.

CQS é um princípio simples e importante: separar operações que modificam o estado daquelas que apenas consultam informações.

CQRS amplia essa ideia e propõe separar as responsabilidades e os modelos utilizados para escrita e leitura, permitindo que cada lado seja desenvolvido e otimizado de acordo com suas necessidades.

Para aplicações menores, aplicar CQS pode ser suficiente.

Para sistemas maiores, com necessidades diferentes de processamento, consultas complexas e requisitos específicos de desempenho, CQRS pode oferecer benefícios importantes.

Em resumo: CQS separa o comportamento das operações. CQRS separa as responsabilidades e os modelos de leitura e escrita.

Compreender essa diferença é fundamental para tomar decisões arquiteturais mais conscientes e evitar a introdução de complexidade desnecessária em nossas aplicações .NET.

E estamos conversados.

"Jesus respondeu: Na verdade, na verdade te digo que aquele que não nascer da água e do Espírito, não pode entrar no reino de Deus."
João 3:5

                                     Macoratti


José Carlos Macoratti