Microservicio de Clientes

Este tutorial te guiará, paso a paso, en la construcción de un microservicio REST utilizando los diferentes componentes que provee CodeDesignPlus. En este ejemplo, crearemos un microservicio de Cliente que responderá a peticiones REST, y servirá como la base para los siguientes artículos de la serie.

Responsabilidades del Microservicio

El microservicio de Clientes tendrá las siguientes responsabilidades principales:

• Registrar nuevos clientes: Permitir a los usuarios crear una cuenta en nuestra plataforma.
• Actualizar información de clientes: Permitir a los usuarios modificar sus datos personales y de contacto.
• Consultar información de clientes: Permitir a otros microservicios acceder a la información de los clientes, de forma segura.

¿Qué Aprenderás?

1. Cómo generar un microservicio de Clientes utilizando el generador codedesignplus:microservice
2. Cómo modificar el microservicio de Clientes para adaptarlo a tus necesidades específicas.
   • Conceptos de DDD (Domain-Driven Design), CQRS (Command Query Responsibility Segregation) y Ports and Adapters.
   • Diagramas UML para representar los componentes del microservicio.
   • Codificación de agregados, entidades, value objects, eventos de dominio, comandos, queries y controladores.

Diagramas UML

Para visualizar mejor la estructura del microservicio de Clientes, vamos a crear algunos diagramas UML que representen los principales componentes del microservicio.

Agregados, Entidades y Value Objects

Los agregados, entidades y value objects son los componentes principales de la capa de dominio de nuestro microservicio. En el caso del microservicio de Clientes, el agregado principal es el Client, que contiene la información del cliente, como su nombre, apellido, email y dirección. También tenemos value objects como Address, que representa la dirección del cliente.

Eventos de Dominio

Los eventos de dominio son una parte fundamental de la arquitectura basada en eventos. En el caso del microservicio de Clientes, podemos definir eventos como ClientCreatedDomainEvent, ClientUpdatedDomainEvent y ClientDeletedDomainEvent, que se lanzarán cuando se registre, actualice o elimine un cliente, respectivamente.

Comandos

Los comandos son las acciones que pueden realizar los usuarios en nuestro microservicio. En el caso del microservicio de Clientes, podemos definir comandos como CreateClientCommand, UpdateClientCommand y DeleteClientCommand, que permiten a los usuarios registrar, actualizar y eliminar clientes, respectivamente.

Queries

Las queries son las consultas que pueden realizar otros microservicios para obtener información del microservicio de Clientes. En el caso del microservicio de Clientes, podemos definir queries como GetClientByIdQuery y GetAllClientQuery, que permiten a otros microservicios obtener información de un cliente específico o de todos los clientes, respectivamente.

Creando el Microservicio

El microservicio de Clientes es un buen ejemplo de microservicio CRUD. Por lo tanto, usaremos el generador codedesignplus:microservice con la opción --is-crud.

Para crear el microservicio de Clientes, usaremos el siguiente comando:

Bash

yo codedesignplus:microservice microservice \
    --organization "Acme" \
    --microservice "Clients" \
    --description "Microservicio para gestionar los clientes de la tienda online." \
    --contact-name "Jane Doe" \
    --contact-email "jane.doe@example.com" \
    --vault store-acme \
    --is-crud \
    --aggregate "Client"

Powershell

yo codedesignplus:microservice microservice `
    --organization "Acme" `
    --microservice "Clients" `
    --description "Microservicio para gestionar los clientes de la tienda online." `
    --contact-name "Jane Doe" `
    --contact-email "jane.doe@example.com" `
    --vault store-acme `
    --is-crud `
    --aggregate "Client"

Note

Para mas información sobre los parámetros del comando, puedes consultar la documentación del generador.

Para ejecutar el comando, abre tu terminal y copia y pega el comando anterior. Asegúrate de que estás en el directorio raíz donde deseas crear el microservicio de Clientes. El generador creará una nueva carpeta con el nombre del microservicio y generará la estructura base del microservicio dentro de esa carpeta.

Note

Durante la ejecución del comando, se te pedirá algunas confirmaciones para sobre escribir algunos archivos. Puedes responder Y para confirmar.

Una vez que el comando termine de ejecutarse, el generador habrá creado la estructura base de nuestro microservicio de Clientes. Esto incluye la estructura de carpetas, los archivos de configuración iniciales, los modelos y las interfaces.

Note

Ejecute el comando dotnet build en la raíz del proyecto para asegurarse de que el microservicio se compila correctamente. Pueden aparecer algunos warnings, pero no deberían impedir la compilación del microservicio. Estos warnings serán corregidos en los siguientes pasos.

Modificando el Microservicio

Ahora que hemos generado el microservicio de Clientes, podemos comenzar a modificarlo para adaptarlo a nuestras necesidades específicas.

Value Objects

Los value objects son objetos inmutables que representan un concepto o entidad específica en nuestro dominio. En la carpeta src/domain/ValueObjects modificaremos la clase Address para definir las propiedades de la dirección del cliente, como Country, State, City y AddressValue.

Para crear nuestro value object Address, seguiremos los siguientes pasos:

1. Ejecutamos el siguiente comando para crear el value object Address

   yo codedesignplus:microservice valueObject --valueObjects "Address"

   

2. Modificamos la clase Address para definir las propiedades de la dirección del cliente, como Country, State, City y AddressValue.

   

3. Hacemos uso de los Guard Clauses para validar las propiedades de la dirección del cliente.

   

4. Creamos los códigos de error para cada propiedad de la dirección del cliente en la clase Errors.

   

   Note

   Los codigos de error estan definidos en la clase Errors siguiendo el estandar de errores implementado. Para mas información sobre los errores implementados puedes consultar:

   • Los niveles de validación.
   • La clase CodeDesignPlusException.

Eventos de Dominio

Los eventos de dominio son una parte fundamental de la arquitectura basada en eventos. En el microservicio de Clientes, definiremos los eventos ClientCreatedDomainEvent, ClientUpdatedDomainEvent y ClientDeletedDomainEvent que se lanzarán cuando se registre, actualice o elimine un cliente, respectivamente.

En este punto, los eventos de dominio ya han sido creados por el generador CodeDesignPlus.Net.Generator. Sin embargo, necesitamos modificar las clases ClientCreatedDomainEvent, ClientUpdatedDomainEvent y ClientDeletedDomainEvent para definir las propiedades de los eventos.

Note

Si necesita crear un nuevo evento de dominio, puede hacerlo ejecutando el siguiente comando:

yo codedesignplus:microservice domainEvent --domainEvents "<domain_event_names>"

Para más información sobre cómo crear eventos de dominio, puedes consultar la documentación.

Client Created

El evento ClientCreatedDomainEvent se lanza cuando se crea un nuevo cliente en el sistema. Este es creado internamente en el agregado Client cuando se invoca el método Create.

Client Updated

El evento ClientUpdatedDomainEvent se lanza cuando se actualiza la información de un cliente en el sistema. Este es creado internamente en el agregado Client cuando se invoca el método Update.

Client Deleted

El evento ClientDeletedDomainEvent se lanza cuando se elimina un cliente del sistema. Este es creado internamente en el agregado Client cuando se invoca el método Delete.

Aggregate

El agregado Client es el componente principal del microservicio de Clientes. Contiene la lógica de negocio y las reglas de validación relacionadas (invariantes). En esta etapa, modificaremos el agregado Client para definir las propiedades debido a que ya ha sido creado por el generador CodeDesignPlus.Net.Generator.

Note

Si necesitas crear un nuevo agregado, puedes hacerlo ejecutando el siguiente comando:

yo codedesignplus:microservice aggregate --aggregate "<aggregate_name>"

Para más información sobre cómo crear agregados, puedes consultar la documentación.

1. Creamos las propiedades del agregado Client con los valores por defecto.

   

2. Creamos el constructor privado del agregado Client para evitar la creación de instancias sin los valores requeridos y asociamos el evento de dominio ClientCreatedDomainEvent a la instancia del agregado.

   

3. Usamos name constructor pattern para crear una nueva instancia del agregado Client y usamos guard clauses para validar las propiedades del cliente.

   

4. Creamos los métodos Update y Delete en el agregado Client para actualizar y eliminar la información del cliente, respectivamente.

   

Note

• Los aggregates son los responsables de la tercera capa de validación. Para mas información sobre los niveles de validación puedes consultar la documentación.

• El name constructor pattern es un patrón de diseño que consiste en utilizar métodos estáticos con nombres descriptivos para crear instancias de una clase. Esto permite mejorar la legibilidad del código y facilitar la creación de instancias con valores predeterminados.

• Los guard clauses son una técnica de programación defensiva que se utiliza para validar los parámetros de entrada de un método o función. Si los parámetros no cumplen con ciertas condiciones, se lanza una excepción o se devuelve un valor predeterminado.

• Los codigos de error para cada propiedad del cliente se deben crear en la clase Errors siguiendo el estandar de errores implementado en la clase CodeDesignPlusException.

• Para más información sobre los errores implementados puedes consultar los niveles de validación.

• Si necesitas crear un nuevo agregado, puedes hacerlo ejecutando el siguiente comando:

  yo codedesignplus:microservice aggregate --aggregate "<aggregate_name>"

  Para más información sobre cómo crear agregados, puedes consultar la documentación.

Repositorio

El SDK de CodeDesignPlus proporciona una clase base RepositoryBase que implementa los métodos CRUD básicos para interactuar con la base de datos. En esta etapa, no modificaremos la interfaz IClientRepository ni su implementación ClientRepository, ya que hereadamos de la clase RepositoryBase.

Si el RepositoryBase no cumple con tus necesidades, puedes modificar la interfaz IClientRepository y su implementación ClientRepository para agregar los métodos necesarios.

Caution

• La clase RepositoryBase genera excepciones cuando no es enviado el Tenant. Esto con la finalidad de asegurar que la información a consultar sea del Tenant correspondiente al que se esta autenticando.
• Si el RepositoryBase no cumple con tus necesidades, puedes definir nuevos métodos en la interfaz IClientRepository y su implementación en ClientRepository. Sin embargo, si son métodos de consulta, no olvides pasar el Tenant como parámetro.

Note

• Si necesitas crear un nuevo repositorio, puedes hacerlo ejecutando el siguiente comando:

  yo codedesignplus:microservice repository --repository "<repository_name>"

  Para más información sobre cómo crear repositorios, puedes consultar la documentación.

• Para conocer más sobre los métodos disponibles en la clase RepositoryBase puedes consultar la documentación.

Comandos

Los comandos representan las acciones que los usuarios pueden ejecutar en nuestro microservicio. Por ello, comenzaremos modificando los commands y, posteriormente, ajustaremos los handlers asociados a cada uno. En esta etapa, recibiremos la información del comando, la validaremos y luego invocaremos el método correspondiente en el agregado Client. Finalmente, generaremos y lanzaremos los eventos de dominio correspondientes, los cuales serán creados internamente dentro del agregado.

Create Client

1. El comando CreateClientCommand representa la acción de crear un nuevo cliente en el sistema. Contiene las propiedades necesarias para crear un nuevo cliente, como Name, LastName, Email y Address.

   

2. El handler CreateClientCommandHandler recibe el comando CreateClientCommand, valida la información del cliente y luego invoca el método Create en el agregado Client. Finalmente, genera y lanza el evento de dominio ClientCreatedDomainEvent.

   

Update Client

1. El comando UpdateClientCommand representa la acción de actualizar la información de un cliente en el sistema. Contiene las propiedades necesarias para actualizar un cliente, como Id, Name, LastName, Email y Address.

   

2. El handler UpdateClientCommandHandler recibe el comando UpdateClientCommand, valida la información del cliente y luego invoca el método Update en el agregado Client. Finalmente, genera y lanza el evento de dominio ClientUpdatedDomainEvent.

   

Delete Client

1. El comando DeleteClientCommand representa la acción de eliminar un cliente del sistema. Contiene la propiedad Id que identifica al cliente que se desea eliminar.

   

2. El handler DeleteClientCommandHandler recibe el comando DeleteClientCommand, valida la información del cliente y luego invoca el método Delete en el agregado Client. Finalmente, genera y lanza el evento de dominio ClientDeletedDomainEvent.

   

Note

• Los comandos son invocados por los Controllers para Rest, los Services para gRPC o los Consumers para los eventos.

• Los handlers son los responsables de la segunda capa de validación. Para mas información sobre los niveles de validación puedes consultar la documentación.

• Los commands tienen internamente un validator que son los responsables de la primera capa de validación. Para mas información sobre los niveles de validación puedes consultar la documentación.

• Si necesitas crear un nuevo comando, puedes hacerlo ejecutando el siguiente comando:

  yo codedesignplus:microservice command --aggregate "<aggregate_name>" --repository "<repository_name>" --commands "<command_name>"

  Para más información sobre cómo crear comandos, puedes consultar la documentación.

Queries

Las queries representan las consultas que otros microservicios pueden realizar para obtener información del microservicio de Clientes. En esta etapa, crearemos las queries GetAllClientQuery y GetClientByIdQuery para obtener información de un cliente específico o de todos los clientes, respectivamente.

GetAllClientQuery

1. La query GetAllClientQuery representa la acción de obtener información de todos los clientes en el sistema.

   

2. El handler GetAllClientQueryHandler recibe la query GetAllClientQuery y luego invoca el método FindAll en el repositorio ClientRepository para obtener la información de todos los clientes.

   

GetClientByIdQuery

1. La query GetClientByIdQuery representa la acción de obtener información de un cliente específico en el sistema.

   

2. El handler GetClientByIdQueryHandler recibe la query GetClientByIdQuery, valida si el registro existe en la cache. Si no existe, invoca el método FindAsync en el repositorio ClientRepository para obtener la información del cliente.

   

Note

• Las queries son invocadas por los Controllers para Rest, los Services para gRPC o los Consumers para los eventos.

• Si necesitas crear una nueva query, puedes hacerlo ejecutando el siguiente comando:

  yo codedesignplus:microservice query --aggregate "<aggregate_name>" --repository "<repository_name>" --queries "<query_name>"

  Para más información sobre cómo crear queries, puedes consultar la documentación.

Controladores

Los controladores son responsables de recibir las peticiones HTTP e invocar los comandos o los queries correspondientes. En esta etapa, el controlador ClientController fue creado por el generador CodeDesignPlus.Net.Generator y se encarga de recibir las peticiones HTTP para crear, actualizar, eliminar y consultar información de los clientes.

Es importante documentar el controlador con C# XML Comments para que la documentación del API sea generada automáticamente.

Note

• Los Data Transfer Object (DTO) como CreateClientDto y UpdateClientDto son generados automáticamente por el generador CodeDesignPlus.Net.Generator y se utilizan para transferir datos entre el controlador y los comandos. Para más información sobre el generador, puedes consultar la documentación.
• La documentación del API es generada automáticamente a partir de los C# XML Comments en los controladores.

Configuración Mapster

Mapster es una librería de mapeo de objetos que nos permite mapear fácilmente los objetos como nuestros commands, queries, aggregate, entities, value object a los DTOs y viceversa. En esta etapa, configuraremos Mapster para mapear los objetos en nuestra capa de aplicación.

Procedemos a configurar las siguientes clases de mapeo:

• CreateClientDto a CreateClientCommand
• UpdateClientDto a UpdateClientCommand
• ClientAggregate a ClientDto

Compilación

Para asegurarnos de que nuestro microservicio de Clientes se compila correctamente, ejecutaremos el comando dotnet build en la raíz del proyecto. El resultado de la compilación se mostrará en la consola y se generará una carpeta bin con los archivos binarios necesarios para ejecutar el microservicio.

Conclusiones

En este tutorial, hemos aprendido cómo generar un microservicio de Clientes utilizando el generador codedesignplus:microservice y cómo modificarlo para adaptarlo a nuestras necesidades específicas. Hemos creado agregados, entidades, value objects, eventos de dominio, comandos, queries y controladores, y hemos configurado Mapster para mapear los objetos en nuestra capa de aplicación.