Microservice (Custom)

Command: yo codedesignplus:microservice microservice

Este comando se utiliza para crear la estructura base de un nuevo microservicio con un enfoque en la lógica de negocio compleja y eventos. A diferencia de un microservicio CRUD, este tipo es más flexible y se adapta a escenarios donde el flujo de trabajo es más importante que las operaciones básicas de persistencia de datos.

Prerrequisitos

Instalar Node.js y npm instalados.
Instalar Yeoman (npm install -g yo).
Instalar el generador codedesignplus:microservice.

Conceptos Clave

Microservicio Custom: Es una unidad de software autónoma y pequeña que realiza una función específica, con un enfoque en la lógica de negocio y eventos en lugar de las operaciones CRUD estándar.
Lógica de Negocio: El conjunto de reglas y procesos que definen cómo opera el negocio. Los microservicios Custom se centran en la implementación de esta lógica.
Eventos de Dominio: Representaciones de algo que ha ocurrido en el dominio del negocio. Los microservicios Custom a menudo generan y responden a estos eventos.
Arquetipo: El arquetipo base CodeDesignPlus.Net.Microservice para la creación de microservicios en .NET, proporcionando una estructura de proyecto bien definida y buenas prácticas.
Diseño Basado en Dominio (DDD): Los principios de DDD son fundamentales para la estructura y organización de la lógica de negocio en los microservicios Custom.

Sintaxis del Comando

El comando yo codedesignplus:microservice microservice tiene la siguiente sintaxis:

Bash
PowerShell

yo codedesignplus:microservice microservice \
    --organization "<organization_name>" \
    --microservice "<microservice_name>" \
    --description  "<microservice_description>" \
    --contact-name "<contact_name>" \
    --contact-email "<contact_email>" \
    --vault "<vault_name>" \
    --aggregate "<aggregate_name>" \
    --enable-grpc \
    --enable-async-worker \
    --consumer-name "<consumer_name>" \
    --consumer-aggregate "<consumer_aggregate>" \
    --consumer-action "<consumer_action>" \
    --domain-events "<domain_events>" \
    --entities "<entities>" \
    --commands "<commands>" \
    --queries "<queries>"

yo codedesignplus:microservice microservice `
    --organization "<organization_name>" `
    --microservice "<microservice_name>" `
    --description "<microservice_description>" `
    --contact-name "<contact_name>" `
    --contact-email "<contact_email>" `
    --vault "<vault_name>" `
    --aggregate "<aggregate_name>" `
    --enable-grpc `
    --enable-async-worker `
    --consumer-name "<consumer_name>" `
    --consumer-aggregate "<consumer_aggregate>" `
    --consumer-action "<consumer_action>" `
    --domain-events "<domain_events>" `
    --entities "<entities>" `
    --commands "<commands>" `
    --queries "<queries>"

`--organization`

Tipo: string
Obligatorio: Sí
Descripción: El nombre de la organización. Se utiliza para la organización del código y la gestión de los namespaces.

`--microservice`

Tipo: string
Obligatorio: Sí
Descripción: El nombre del microservicio que se va a crear.

`--description`

Tipo: string
Obligatorio: Sí
Descripción: Una descripción detallada del microservicio que proporciona un contexto claro sobre su propósito.

`--contact-name`

Tipo: string
Obligatorio: Sí
Descripción: Nombre de la persona de contacto responsable del microservicio.

`--contact-email`

Tipo: string
Obligatorio: Sí
Descripción: Email de contacto de la persona responsable.

`--vault`

Tipo: string
Obligatorio: Sí
Descripción: El nombre del vault para la gestión de secretos y configuraciones.

`--aggregate`

Tipo: string
Obligatorio: Sí
Descripción: El nombre del agregado raíz del microservicio, esencial para la organización del dominio.

`--enable-grpc`

Tipo: boolean
Obligatorio: No
Descripción: Habilita la API gRPC para el microservicio, que ofrece un protocolo de comunicación de alto rendimiento.

`--enable-async-worker`

Tipo: boolean
Obligatorio: No
Descripción: Habilita un worker asíncrono para el manejo de eventos y tareas en segundo plano, mejorando la escalabilidad.

`--consumer-name`

Tipo: string
Obligatorio: Si cuando --enable-async-worker es true
Descripción: El nombre del evento que este microservicio consumirá.

`--consumer-aggregate`

Tipo: string
Obligatorio: Si cuando --enable-async-worker es true
Descripción: El agregado asociado al evento que se consumirá.

`--consumer-action`

Tipo: string
Obligatorio: Si cuando --enable-async-worker es true
Descripción: La acción que se realizará en respuesta al evento consumido.

`--domain-events`

Tipo: string
Obligatorio: No
Descripción: Una lista de eventos de dominio separados por comas que el microservicio puede publicar.

`--entities`

Tipo: string
Obligatorio: No
Descripción: Una lista de entidades separadas por comas que el microservicio gestiona.

`--commands`

Tipo: string
Obligatorio: No
Descripción: Una lista de comandos separados por comas que el microservicio puede ejecutar.

`--queries`

Tipo: string
Obligatorio: No
Descripción: Una lista de queries separadas por comas que el microservicio puede ejecutar.

Ejemplos de Uso

Este ejemplo crea un microservicio Custom llamado inventory para gestionar el inventario de productos en la plataforma de la organización acme.

Bash
PowerShell

yo codedesignplus:microservice microservice \
    --organization "Acme" \
    --microservice inventory \
    --description "Microservicio para gestionar el inventario de productos." \
    --contact-name "John Smith" \
    --contact-email "john.smith@example.com" \
    --vault "vault-acme" \
    --aggregate "Product" \
    --enable-grpc \
    --enable-async-worker \
    --consumer-name "OrderCreated" \
    --consumer-aggregate "Order" \
    --consumer-action "update-stock" \
    --domain-events "ProductCreated,ProductUpdated,ProductRemoved" \
    --entities "Product,Category" \
    --commands "CreateProduct,UpdateProduct,RemoveProduct" \
    --queries "FindProductById,FindProductsByCategory"

yo codedesignplus:microservice microservice `
    --organization "Acme" `
    --microservice inventory `
    --description "Microservicio para gestionar el inventario de productos." `
    --contact-name "John Smith" `
    --contact-email "john.smith@example.com" `
    --vault "vault-acme" `
    --aggregate "Product" `
    --enable-grpc `
    --enable-async-worker `
    --consumer-name "OrderCreated" `
    --consumer-aggregate "Order" `
    --consumer-action "update-stock" `
    --domain-events "ProductCreated,ProductUpdated,ProductRemoved" `
    --entities "Product,Category" `
    --commands "CreateProduct,UpdateProduct,RemoveProduct" `
    --queries "FindProductById,FindProductsByCategory"

Salida del comando en consola

Tras ejecutar el comando, se generará la estructura base del microservicio Custom inventory en la organización acme, con la siguiente salida en consola:

Directorios y Archivos Generados

Si exploramos el microservicio con VS Code, veremos la estructura de directorios y archivos generados:

Explorador de Archivos
Árbol de Archivos

Resultados de la Ejecución

La ejecución de este comando con los parámetros proporcionados generará la estructura base de un microservicio custom en la organización acme con el nombre inventory. El microservicio estará listo para ser personalizado y ampliado según las necesidades del proyecto.

Pero para comprender mejor el impacto de cada una de las opciones, veamos los resultados de la ejecución del comando:

`--organization`

Flag: --organization "acme"

Este parámetro establece el nombre de la organización a nivel de la solución (.sln) y para cada uno de los proyectos (.csproj) generados.
El valor del parametro tambien se refleja en los namespaces de los proyectos generados.
Por ultimo, tambien se ve reflejado en cada uno de los archivos appsettings.json de los proyectos de infraestructura en la propiedad Business.

`--microservice`

Flag: --microservice "inventory"

Este parámetro establece el nombre del microservicio a nivel de la solución (.sln) y para cada uno de los proyectos (.csproj) generados.
El valor del parametro tambien se refleja en los namespaces de los proyectos generados.
Tambien es usado en los archivos appsettings.json de los proyectos de infraestructura en multiples propiedades.
El nombre del microservicio tambien se refleja en el archivo config.sh encargado de la configuración de Vault.

`--description`

Flag: --description "Microservicio para gestionar el inventario de productos."

Este parámetro establece una descripción detallada del microservicio que se refleja en el archivo appsettings.json de los proyectos de infraestructura.

`--contact-name`

Flag: --contact-name "John Smith"

Este parámetro establece el nombre de la persona de contacto responsable del microservicio, que se refleja en el archivo appsettings.json de los proyectos de infraestructura.

`--contact-email`

Flag: --contact-email "john.smith@example.com"

Este parámetro establece el email de contacto de la persona responsable del microservicio, que se refleja en el archivo appsettings.json de los proyectos de infraestructura.

`--vault`

Flag: --vault "vault-acme"

Este parámetro establece el nombre del vault para la gestión de secretos y configuraciones, que se refleja en el archivo config.sh encargado de la configuración de Vault.
El valor del parametro tambien se refleja en los archivos appsettings.json de los proyectos de infraestructura en la propiedad Vault.

`--aggregate`

Flag: --aggregate "product"

Este parámetro establece el nombre del agregado raíz del microservicio, que se refleja en los archivos generados en la capa de dominio.
El valor del parametro tambien es usado para la creación del Data Transfer Object (DTO) de la entidad Product.

`--enable-grpc`

Flag: --enable-grpc

Este flag habilita la API gRPC para el microservicio, generando el servicio con base en el agregado raíz product.

`--enable-async-worker`

Flag: --enable-async-worker

Este flag habilita un worker asíncrono para el manejo de eventos y tareas en segundo plano, mejorando la escalabilidad del microservicio.

`--consumer-name`

Flag: --consumer-name "orderCreated"

Este parámetro establece el nombre del evento que el worker asíncrono consumirá, reflejándose en la creación del consumer correspondiente.
El valor del parametro tambien se refleja en el handler del consumer creado.

`--consumer-aggregate`

Flag: --consumer-aggregate "order"

Este parámetro establece el agregado asociado al evento que se consumirá, reflejándose en el consumer creado.
El valor del parametro tambien se refleja en el handler del consumer creado.
El valor del parametro permite ordenar los casos de uso del consumer.

`--consumer-action`

Flag: --consumer-action "update-stock"

Este parámetro establece la acción que realizará el consumer en respuesta al evento, reflejándose en la lógica del consumer creado.
El valor indica la acción que se realizará cuando se consuma el evento, por este motivo tambien es usado para crear el comando correspondiente en la capa de aplicación.

`--domain-events`

Flag: --domain-events "ProductCreated,ProductUpdated,ProductRemoved"

Este parámetro define los eventos de dominio que pueden ocurrir en el microservicio, generando los archivos correspondientes en la capa de dominio.

`--entities`

Flag: --entities "Product,Category"

Este parámetro define las entidades que gestiona el microservicio, generando la estructura básica para estas entidades en la capa de dominio.

`--commands`

Flag: --commands "CreateProduct,UpdateProduct,RemoveProduct"

Este parámetro define los comandos que el microservicio puede ejecutar, generando las estructuras de comandos y sus handlers correspondientes en la capa de aplicación.

`--queries`

Flag: --queries "FindProductById,FindProductsByCategory"

Este parámetro define las queries que el microservicio puede ejecutar, generando las estructuras de queries y sus handlers correspondientes en la capa de aplicación.

Consideraciones Adicionales

A diferencia de los microservicios CRUD, los microservicios custom permiten una mayor flexibilidad y personalización.
Asegúrate de proporcionar una descripción clara para tu microservicio.
Define bien tu agregado raíz (--aggregate) para organizar adecuadamente tu dominio.
Considera habilitar gRPC y Workers (--enable-grpc) según las necesidades de tu proyecto.
Configura correctamente los eventos de dominio (--domain-events), entidades (--entities), comandos (--commands), y queries (--queries).
Comprender el impacto de cada parámetro te ayudará a personalizar, extender, solucionar problemas y mantener tu microservicio de forma efectiva.

Enlaces Relacionados

Conclusión

El comando yo codedesignplus:microservice microservice proporciona una forma flexible de generar la estructura de un microservicio custom, permitiendo un enfoque en la lógica de negocio compleja y la gestión de eventos. Utiliza las opciones disponibles para adaptar el microservicio a las necesidades específicas de tu proyecto.