CURSO NOVO NO AR: MICROSSERVIÇOS



ASP.NET Core, CQRS e Mediator

AspNet Core, CQRS e Mediator, um trio que combina muito bem e pode elevar a organização das suas aplicações a um outro nível.

O que é o CQRS

CQRS é a sigla para Command and Queries Responsability Segregation, ou traduzido para o português, Separação de Responsabilidades em Consultas e Comandos.

Podemos interpretar as consultas como a parte de leitura da nossa aplicação e comandos como a parte de escrita, para facilitar nosso entendimento aqui.

Pensando desta forma, quando sabemos o que é CQRS, parece até óbvio, afinal em nossas quase nunca são balanceadas, ou tem muita leitura, ou tem muita escrita.

Particularmente, vejo que na maioria dos casos temos mais leitura do que escrita, como um exemplo de um eCommerce, onde navegamos por horas (Leitura apenas) e só fechamos o pedido uma vez (Escrita).

Agora que sabemos a parte fácil, vamos partir para implementação.

Iniciando a API

Para este exemplo vou construir tudo dentro da API mesmo, apenas em pastas separadas, mas tenha em mente, que em projetos maiores esta divisão seria realizada em projetos, como mostramos no curso 7196.

Desta forma, navegue para uma pasta segura e execute o comando abaixo para criar uma nova API.

dotnet new webapi -o Shop

Em seguida, abra a aplicação com o Visual Studio Code para iniciarmos o desenvolvimento.

Entidades

Normalmente, quando começamos a modelagem de domínios ricos, começamos pelas entidades e objetos de valor como explico nos cursos 1975 - Modelando Domínios Ricos e 7182 - Refatorando para Testes de Unidade.

Você pode usar entidades anêmicas e a abordagem Data Driven como mostro no curso 7194 - Criando APIs Data Driven também, mas para este exemplo, vamos focar em entidades mais ricas.

Na verdade, vamos ser bem pragmáticos e "simular" que temos uma entidade rica, com propriedades privadas, objetos de valor e testes, mas no caso teremos apenas o código abaixo (Domain/Entities/Customer.cs).

using System;

namespace Shop.Domain.Entities
{
    public class Customer
    {
        public Customer(string name, string email)
        {
            Id = Guid.NewGuid();
            Name = name;
            Email = email;
        }

        public Guid Id { get; private set; }
        public string Name { get; private set; }
        public string Email { get; private set; }
    }
}

O quem importa é saber que funciona para ambos modelos e entender a implementação do CQRS básico aqui.

Comandos (Request)

Se você acompanha meus cursos, sempre que falamos de algum padrão eu prefiro não usar Frameworks adicionais, assim aprendemos como as coisas funcionam de fato.

Para o CQRS é a mesma coisa, vamos iniciar criando o básico, e depois você pode melhorar este código, criar a sua implementação. Então não vou focar em reaproveitamento de código e coisas do tipo.

Sim, eu sei que podemos ter uma classe base para comandos, como fazemos no curso 7196 por exemplo, mas aqui é apenas uma demonstração, este código não deve ir para produção.

Desta forma, vamos criar nosso comando para criar um novo cliente. Como você pode notar, um comando é uma ação de escrita que será executada em nossa aplicação.

Esta ação (Comando) contém apenas as informações necessárias para criar um cliente, no caso, nome e e-mail apenas, tendo em mente que o ID é gerado de forma automática.

using System;

namespace Shop.Domain.Commands.Requests
{
    public class CreateCustomerRequest
    {
        public string Name { get; set; }
        public string Email { get; set; }
    }
}

Um outro exemplo seria um pedido, onde para criá-lo, precisamos apenas da lista de produtos do carrinho e do usuário que está realizando o pedido.

Todas as outras informações como a data do pedido, número, valor, estado, são gerados pela aplicação. Afinal, você não quer deixar o Frontend mandar o valor total do pedido não é mesmo?

Comandos (Response)

Na sessão acima fizemos a requisição para criação de um novo cliente, mas e agora? Vamos supor que tenha dado tudo certo, o que devemos retornar para tela?

Melhor, vamos imaginar que queremos retornar o nome, E-mail, ID e a data da requisição, como podemos fazer?

Não podemos retornar a entidade Customer que criamos pois ela não tem a data, da mesma forma que não podemos retornar o CreateCustomerRequest pois ele não tem o ID nem a data.

Embora em parte dos cenários podemos enviar um objeto padrão de retorno como eu mostro no curso 1974 na parte de padronização de APIs, em alguns casos queremos uma resposta customizada.

Desta forma, temos também o retorno dos comandos, que para facilitar, coloquei na pasta Domain/Commands/Responses, como CreateCustomerResponse.cs.

using System;

namespace Shop.Domain.Commands.Responses
{
    public class CreateCustomerResponse
    {
        public Guid Id { get; set; }
        public string Name { get; set; }
        public string Email { get; set; }
        public DateTime Date { get; set; }
    }
}

Pronto, agora temos um comando de entrada (Request) e um comando de retorno (Response), que compõe uma ação de criar um novo cliente.

Handlers

Com nossos comandos criados, precisamos agora pensar no fluxo de execução da ação, e este ponto aqui varia bastante.

No curso 7182 - Refatorando para Testes de Unidade por exemplo, nós pegamos um fluxo de pedido que estava todo acoplado e refatoramos ele para uso com CQRS e muitos testes de unidade.

Então nesta fase, depende muito da quantidade de regras que você tem, talvez seja até interessante quebrar em mais fluxos sua ação, para facilitar o reuso do código.

Voltando ao nosso cenário, vamos imaginar que temos os seguintes passos na hora de cadastrar um cliente:

  • Verificar se o E-mail já está cadastrado
  • Incluir o cliente no banco
  • Enviar um E-mail de boas vindas

É um fluxo simples, mas não deixa de ser um fluxo, inclusive é interessante testar estes fluxos como mostramos no curso 7182 - Refatorando para Testes de Unidade.

O que acontece quando recebemos um comando (Uma ação) é que precisamos de alguém para fazer algo com este comando, para manipular estas informações que recebemos.

Isto quem faz são os Handlers que traduzindo para o português seriam os manipuladores. Eles basicamente recebem um comando, executam um fluxo e retornam uma resposta.

Vamos começar criando uma interface para o nosso manipulador, chamada de ICreateCustomerHandler.cs, na pasta Domain/Handlers, com o seguinte código.

using Shop.Domain.Commands.Requests;
using Shop.Domain.Commands.Responses;

namespace Shop.Domain.Handlers
{
    public interface ICreateCustomerHandler
    {
        CreateCustomerResponse Handle(CreateCustomerRequest command);
    }
}

Precisamos desta interface para gerenciar dependências posteriormente, e a implementação do nosso CreateCustomerHandler.cs que também fica na pasta Domain/Handlers segue abaixo.

using System;
using Shop.Domain.Commands.Requests;
using Shop.Domain.Commands.Responses;
using Shop.Domain.Entities;
using Shop.Domain.Repositories;
using Shop.Domain.Services;

namespace Shop.Domain.Handlers
{
    public class CreateCustomerHandler
    {
        ICustomerRepository _repository;
        IEmailService _emailService;

        public CreateCustomerHandler(ICustomerRepository repository, IEmailService emailService)
        {
            _repository = repository;
            _emailService = emailService;
        }

        public CreateCustomerResponse Handle(CreateCustomerRequest command)
        {
            // Aplicar Fail Fast Validations

            // Cria a entidade
            var customer = new Customer(command.Name, command.Email);

            // Persiste a entidade no banco
            _repository.Save(customer);

            // Envia E-mail de boas-vindas
            _emailService.Send(customer.Name, customer.Email);

            // Retorna a resposta
            return new CreateCustomerResponse
            {
                Id = customer.Id,
                Name = customer.Name,
                Email = customer.Email,
                Date = DateTime.Now
            };
        }
    }
}

Basicamente, o que temos é um método chamado Handle que recebe um request (CreateCustomerRequest) e retorna uma resposta (CreateCustomerResponse).

Este Handler também faz uso do repositório para persistir a entidade de cliente, criada no fluxo e também do serviço de envio de E-mail.

Note que temos apenas as interfaces aqui, seguindo a boa prática de depender sempre de abstrações de nunca de implementações. Isto permitirá o Mock destes itens posteriormente para testes de unidade também.

Resolvendo as Dependências

Durante o processo de criação do Handler, geramos dependências que precisam ser resolvidas. Se você é novo no mundo de DI, veja este artigo antes.

Vamos então para nosso Startup.cs, no método ConfigureServices e adicionar o trecho para gerenciar estas dependências que temos.

public void ConfigureServices(IServiceCollection services)
        {
            services.AddControllers();
            services.AddTransient<ICreateCustomerHandler, CreateCustomerHandler>();
        }

Neste momento, já podemos chamar nosso Handler nos controlador, passando o CreateCustomerRequest como entrada e esperando o CreateCustomerResponse como resposta.

using Microsoft.AspNetCore.Mvc;
using Shop.Domain.Commands.Requests;
using Shop.Domain.Handlers;

namespace Shop.Controllers
{
    [ApiController]
    [Route("customers")]
    public class CustomerController : ControllerBase
    {
        [HttpPost]
        [Route("")]
        public IActionResult Create(
                   [FromServices]ICreateCustomerHandler handler,
                   [FromBody]CreateCustomerRequest command
               )
        {
            var response = handler.Handle(command);
            return Ok(response);
        }
    }
}

Queries

As consultas não são diferentes dos comandos, podemos ter uma requisição como mostrada abaixo.

using System;

namespace Shop.Domain.Queries.Requests
{
    public class FindCustomerByIdRequest
    {
        public Guid Id { get; set; }
    }
}

E uma resposta como mostrado abaixo.

using System;

namespace Shop.Domain.Queries.Responses
{
    public class FindCustomerByIdResponse
    {
        public Guid Id { get; set; }
        public string Name { get; set; }
        public string Email { get; set; }
    }
}

Novamente precisamos de um Handler para manipular esta requisição, e começamos pela interface.

using Shop.Domain.Queries.Requests;
using Shop.Domain.Queries.Responses;

namespace Shop.Domain.Handlers
{
    public interface IFindCustomerByIdHandler
    {
        FindCustomerByIdResponse Handle(FindCustomerByIdRequest command);
    }
}

Em seguida implementamos o manipulador.

using Shop.Domain.Queries.Requests;
using Shop.Domain.Queries.Responses;
using Shop.Domain.Repositories;

namespace Shop.Domain.Handlers
{
    public class FindCustomerByIdHandler : IFindCustomerByIdHandler
    {
        ICustomerRepository _repository;

        public FindCustomerByIdHandler(ICustomerRepository repository)
        {
            _repository = repository;
        }
        public FindCustomerByIdResponse Handle(FindCustomerByIdRequest command)
        {
            // TODO: Lógica de leitura se houver

            // Retorna o resultado
            return _repository.GetCustomerById(command.Id);
        }
    }
}

Note que o repositório já retorna nosso Response, e não uma entidade. Além disso, se não houver lógica nenhuma de leitura, eu não vejo problema nenhum em chamar o repositório diretamente no controlador.

Vamos então resolver as dependências do novo Handler no Startup.cs e adicionar a chamada ao controlador.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddTransient<ICreateCustomerHandler, CreateCustomerHandler>();
    services.AddTransient<IFindCustomerByIdHandler, FindCustomerByIdHandler>();
}

Desta forma podemos chamar o manipulador no controlador, assim como fizemos com o método POST.

using Microsoft.AspNetCore.Mvc;
using Shop.Domain.Commands.Requests;
using Shop.Domain.Handlers;
using Shop.Domain.Queries.Requests;

namespace Shop.Controllers
{
    [ApiController]
    [Route("customers")]
    public class CustomerController : ControllerBase
    {
        [HttpGet]
        [Route("")]
        public IActionResult GetById(
            [FromServices]IFindCustomerByIdHandler handler,
            [FromQuery]FindCustomerByIdRequest command
        )
        {
            var result = handler.Handle(command);
            return Ok(result);
        }

        [HttpPost]
        [Route("")]
        public IActionResult Create(
                   [FromServices]ICreateCustomerHandler handler,
                   [FromBody]CreateCustomerRequest command
               )
        {
            var response = handler.Handle(command);
            return Ok(response);
        }
    }
}

Note que agora, por ser um método GET, nosso comando virá do FromQuery e não FromBody como fizemos anteriormente.

Pronto, finalizamos o exemplo com o básico do CQRS, sem nenhum Framework adicional nem nada, mas neste ponto entram algumas preocupações.

A medida que a aplicação cresce, como fica o Startup.cs? Como ficam as dependências, registrando uma a uma?

Além disso, para gerenciar dependências precisamos das interfaces, ou seja, para cada Handler temos uma e por aí vai.

Sempre que escrevermos aplicações mais detalhadas como esta, teremos mais arquivos, mais códigos, mas isto não é ruim, é organização.

Porém, podemos melhorar alguns pontos aqui, utilizando um padrão chamado Mediator.

O que é o Mediator?

A tradução de Mediator para o português é mediador, justamente o que o padrão faz. Ele intermédia as comunicações da nossa abstraindo isto pra gente.

Em suma o que vamos fazer é simplesmente receber um comando e dizer para o Mediator se virar, e ele se encarregará de encontrar o Handler responsável e executá-lo.

Precisamos do Mediator?

Não necessariamente! Como vimos no exemplo acima, fizemos o processo completo e não usamos o Mediator. Em diversos cursos, como o 7198, também usamos CQRS sem a necessidade do Mediator.

Outra coisa que precisamos ter em mente, é que abstração das dependências causa a quebra do Explicit Dependencies Principle, que prega o uso explícito de dependências.

Ocultando elas, podemos ter problemas em runtime e fica mais difícil capturar e descobrir erros.

Entenda, não estou dizendo que não devemos usar o padrão, mas sim que ele não está atrelado ao uso de CQRS.

Instalando o MediatR

O pacote que implementa o padrão Mediator no .NET é o MediatR, e vamos instalar tanto seu pacote quanto o pacote para gerenciar dependências.

dotnet add package MediatR
dotnet add package MediatR.Extensions.Microsoft.DependencyInjection

Isto é tudo que precisamos para iniciar com Mediator em nossa aplicação.

Refatorando as requisições

Para que nossas dependências sejam resolvidas pelo MediatR, precisamos primeiramente que nossas requisições implementem a interface IRequest, como mostrado abaixo.

using MediatR;
using Shop.Domain.Commands.Responses;

namespace Shop.Domain.Commands.Requests
{
    public class CreateCustomerRequest : IRequest<CreateCustomerResponse>
    {
        public string Name { get; set; }
        public string Email { get; set; }
    }
}

O mesmo vale para nossa consulta.

using System;
using MediatR;
using Shop.Domain.Queries.Responses;

namespace Shop.Domain.Queries.Requests
{
    public class FindCustomerByIdRequest : IRequest<FindCustomerByIdResponse>
    {
        public Guid Id { get; set; }
    }
}

Refatorando os manipuladores

Neste momento, não precisamos mais das interfaces para os Handlers que haviamos criado anteriormente, ao invés disso o MediatR se encarregará de buscar um Handler que possa manipular um comando que enviarmos a ele.

Ao invés disso, nosso Handler agora implementará a interface IRequestHandler<Request, Response> como no código abaixo.

using System;
using System.Threading;
using System.Threading.Tasks;
using MediatR;
using Shop.Domain.Commands.Requests;
using Shop.Domain.Commands.Responses;
using Shop.Domain.Entities;
using Shop.Domain.Repositories;
using Shop.Domain.Services;

namespace Shop.Domain.Handlers
{
    public class CreateCustomerHandler : IRequestHandler<CreateCustomerRequest, CreateCustomerResponse>
    {
        ICustomerRepository _repository;
        IEmailService _emailService;

        public CreateCustomerHandler(ICustomerRepository repository, IEmailService emailService)
        {
            _repository = repository;
            _emailService = emailService;
        }

        public Task<CreateCustomerResponse> Handle(CreateCustomerRequest request, CancellationToken cancellationToken)
        {
            // Aplicar Fail Fast Validations

            // Cria a entidade
            var customer = new Customer(request.Name, request.Email);

            // Persiste a entidade no banco
            _repository.Save(customer);

            // Envia E-mail de boas-vindas
            _emailService.Send(customer.Name, customer.Email);

            // Retorna a resposta
            var result = new CreateCustomerResponse
            {
                Id = customer.Id,
                Name = customer.Name,
                Email = customer.Email,
                Date = DateTime.Now
            };
            return Task.FromResult(result);
        }
    }
}

Note que a assinatura do método Handle mudou, seguindo os padrões de implementação da interface que implementamos. O mesmo vale para o manipulador da nossa consulta.

using System.Threading;
using System.Threading.Tasks;
using MediatR;
using Shop.Domain.Queries.Requests;
using Shop.Domain.Queries.Responses;
using Shop.Domain.Repositories;

namespace Shop.Domain.Handlers
{
    public class FindCustomerByIdHandler : IRequestHandler<FindCustomerByIdRequest, FindCustomerByIdResponse>
    {
        ICustomerRepository _repository;

        public FindCustomerByIdHandler(ICustomerRepository repository)
        {
            _repository = repository;
        }

        public Task<FindCustomerByIdResponse> Handle(FindCustomerByIdRequest request, CancellationToken cancellationToken)
        {
            // TODO: Lógica de leitura se houver

            // Retorna o resultado
            var result = _repository.GetCustomerById(request.Id);
            return Task.FromResult(result);
        }
    }
}

Refatorando as dependências

Agora voltamos ao Startup.cs e podemos remover as resoluções de dependências anteriores, deixando apenas o MediatR cuidando disso.

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
    services.AddMediatR(Assembly.GetExecutingAssembly());
}

Desta forma, o MediatR se encarrega de receber um comando e verificar qual manipulador pode ser responsável por gerenciá-lo.

Refatorando o controlador

Agora nos controladores, podemos simplesmente chamar uma instância do MediatR e seu método Send para enviar um comando sem nos preocuparmos com nada.

[HttpPost]
[Route("")]
public IActionResult Create(
            [FromServices]IMediator mediator,
            [FromBody]CreateCustomerRequest command
        )
{
    var response = mediator.Send(command);
    return Ok(response);
}

O mesmo vale para nossa consulta.

[HttpGet]
[Route("")]
public IActionResult GetById(
    [FromServices]IMediator mediator,
    [FromQuery]FindCustomerByIdRequest command
)
{
    var result = mediator.Send(command);
    return Ok(result);
}

Neste modelo fica mais fácil criar um controlador base que gerencia as requisições e padroniza nossa API.

Conclusão

Não precisamos necessariamente utilizar o padrão Mediator junto ao CQRS, os prós em seu uso são a abstração das dependências e possíveis facilidades no código.

Seus contras são os possíveis problemas ocasionados pelo não direcionamento das dependências, podendo muitas vezes serem causados em Runtime.

Populares

ASP.NET 5 – Autenticação e Autorização com Bearer e JWT

Este artigo atualmente utiliza a versão 5.0.0-rc.1 do ASP.NET/.NET, o que significa que ainda não...


Clean Code - Guia e Exemplos

Saiba como manter seu código limpo (Clean Code) seguindo algumas práticas sugeridas pelo Robert C...


Git e GitHub - Instalação, Configuração e Primeiros Passos

Git é um sistema de controle de versões distribuídas, enquanto GitHub é uma plataforma que tem o ...


Visual Studio Code - Instalação e Customização

O Visual Studio Code é um editor de código criado pela Microsoft e que tem uma grande adoção pela...


Angular: Rotas, Guardas e Navegação

O Angular nos fornece um esquema de rotas e navegação completo, simples e fácil de utilizar.


Compartilhe este artigo



Conheça o autor

Me dedico ao desenvolvimento de software desde 2003, sendo minha maior especialidade o Desenvolvimento Web. Durante esta jornada pude trabalhar presencialmente aqui no Brasil e Estados Unidos, atender remotamente times da ?ndia, Inglaterra e Holanda, receber 8x Microsoft MVP e realizar diversas consultorias em empresas e projetos de todos os tamanhos.





1.877

Aulas disponíveis

272

horas de conteúdo

30.197

Alunos matriculados

22.465

Certificados emitidos





Comece de graça agora mesmo!

Temos mais de 16 cursos totalmente de graça e todos com certificado de conclusão.

Começar


Prefere algo mais Premium?

Conheça nossos planos



Premium mensal

Cobrado mensalmente via
cartão de crédito


ESGOTADO

  • Acesso à todo conteúdo
  • Emissão de Certificado
  • 55 cursos disponíveis
  • 4 carreiras disponíveis
  • 161 temas de tecnologia
  • Conteúdo novo todo mês
  • Cobrado mensalmente

Me Avise

Política de privacidade

Premium semestral

Compra única, parcelada em até
12x no cartão de crédito


12x R$

33

,33

=R$ 399,90
  • 6 meses de acesso
  • Acesso à todo conteúdo
  • Emissão de Certificado
  • Tira Dúvidas Online
  • 55 cursos disponíveis
  • 4 carreiras disponíveis
  • 161 temas de tecnologia
  • Conteúdo novo todo mês
  • Encontros Premium

Começar agora

Política de privacidade

Premium anual

Compra única, parcelada em até
12x no cartão de crédito


12x R$

64

,99

=R$ 779,90
  • 1 ano de acesso
  • Acesso à todo conteúdo
  • Emissão de Certificado
  • Tira Dúvidas Online
  • 55 cursos disponíveis
  • 4 carreiras disponíveis
  • 161 temas de tecnologia
  • Conteúdo novo todo mês
  • Encontros Premium

Começar agora

Política de privacidade



Precisa de ajuda?

Dúvidas frequentes



  • Posso começar de graça?

    Sim! Basta criar sua conta gratuita no balta.io e começar seus estudos. Nós contamos com diversos cursos TOTALMENTE gratuitos e com certificado de conclusão.

  • Vou ter que pagar algo?

    Nós temos cursos gratuitos e pagos, porém você não precisa informar nenhum dado de pagamento para começar seus estudos gratuitamente conosco. Os cursos gratuitos são completos e com certificado de conclusão, você não paga nada por eles.

    Porém, caso queira algo mais Premium, você terá acesso à diversos benefícios que vão te ajudar ainda mais em sua carreira.

  • Por onde devo começar?

    Siga SEMPRE as nossas Carreiras, elas vão te orientar em todos os sentidos. Os cursos já estão organizados em categorias e carreiras para facilitar seu aprendizado.
    Nossa sugestão para aprendizado é começar pelo Backend e seguindo para Frontend e Mobile.

    • Backend
    • Frontend
    • Mobile

  • Os cursos ensinam tudo que preciso?

    Nenhum curso no mundo vai te ensinar tudo, desculpa ser sincero! Os cursos são uma base, eles fornecem por volta de 30% do que você precisa aprender, o resto é com você, com dedicação e MUITA prática.

  • O que eu devo estudar?

    Java ou .NET? Angular ou React? Xamarin ou Flutter? A resposta é simples e direta: "Você já sabe o básico?"

    Se você ainda não sabe BEM o básico, ou seja, os fundamentos, OOP, SOLID, Clean Code, está perdendo tempo estudando Frameworks ou até coisas mais avançadas como Docker. Foque nos seus objetivos primeiro.
    Agora se você está indeciso sobre qual Framework estudar, a boa notícia é que o mercado neste momento está bem aquecido e você tem várias oportunidade. Desta forma o que levaríamos em conta para tomar esta decisão seria:

    • Já sei o básico
    • O Framework/Tecnologia tem mercado onde eu estou (região)
    • O Framework/Tecnologia é utilizado em uma empresa onde quero atual
    • O Framework/Tecnologia resolve meu problema
    • Eu gosto de utilizar o Framework/Tecnologia

  • Estou pronto para estudar no balta.io?

    Com certeza! O primeiro passo é começar e você pode fazer isto agora mesmo!

    Começar de graça

Ainda tem dúvidas?





Assine nosso Newsletter

Receba em primeira mão todas as nossas novidades.

Cadastrar


balta.io