generator-codedesignplus v0.3.2-alpha.1

👋 Your Sidekick for CodeDesignPlus.Net Microservices! 🚀

Hey there, developer! 👋 Tired of starting your microservices from scratch? Worry no more! The generator-codedesignplus is here to simplify and standardize the creation of your microservices based on the CodeDesignPlus.Net.Microservice archetype. Imagine having a tool that guides you step by step, generating the structure and key components of your microservice—all ready for you to focus on the business logic! 🤩

What's the Buzz About CodeDesignPlus.Net.Microservice? 🤔

CodeDesignPlus.Net.Microservice is like your "starter kit" for building modern .NET microservices. It's a starting point that promotes separation of responsibilities, maintainability, and scalability. Forget tedious configurations, as it includes a well-defined project structure, default settings, and utility libraries. In short, it's the solid foundation you need to develop robust microservices quickly and efficiently. 😎

A Journey into the World of Domain-Driven Design (DDD) 🗺️

Before you start using the generator, it's important to know some key concepts of DDD:

• Domain: It's the "world" of your software, the area of knowledge it operates on. Think of the domain as your business context with its own rules. For example, in an e-commerce platform, the domain might be "order management" or "product administration."
• Aggregate: A cluster of entities treated as a unit, with a root entity acting as the "entry point." Aggregates are responsible for maintaining consistency within their boundaries. An order with its order lines is a good example.
• Entity: An object with its own identity, persisting over time and having a defined lifecycle. Each entity has a unique identifier. A user with their name, email, and other details is an entity.
• Value Object: An object without its own identity, defined by its attributes. They are immutable and compared by value. An address or a currency are perfect examples.
• Domain Event: A notification of something that has happened in the domain. They are immutable and represent historical facts. Examples include "OrderCreated" or "UserRegistered."
• Repository: A mechanism that "hides" access to persistent data. It provides an interface for your application to interact with the database without worrying about technical details.
• Command: An intention to perform an action that changes the system's state. These are the orders you give, such as "CreateOrder" or "UpdateUser."
• Query: A request to get information from the system without modifying anything. For example, "GetUserById" or "FindProductsByName."

Configuration Flags: Customize Your Microservice! 🛠️

Available Commands: Your Guide in Development! 🚀

1. Creating a Microservice: The Beginning of It All!

yo codedesignplus:microservice microservice

This is the starting point for your new microservice. You can choose between a CRUD or Custom microservice, each with its own magic and design patterns.

CRUD Microservice: Straight to the Point!

A CRUD microservice focuses on managing data: create, read, update, and delete. It's ideal for scenarios where data persistence is the main concern.

yo codedesignplus:microservice microservice \
    --organization acme \
    --microservice users \
    --description "Microservice to manage platform users." \
    --contact-name "Jane Doe" \
    --contact-email "jane.doe@example.com" \
    --vault vault-acme \
    --is-crud \
    --aggregate user \
    --enable-grpc \
    --enable-async-worker \
    --consumer-name userRegistered \
    --consumer-aggregate user \
    --consumer-action send-welcome-email

Note: The REST entrypoint is created by default when creating a microservice.

Custom Microservice: Maximum Flexibility!

A custom microservice is for complex business logic and events, not just CRUD operations. It's perfect if the workflow is more important than data storage.

yo codedesignplus:microservice microservice \
    --organization acme \
    --microservice inventory \
    --description "Microservice to manage product inventory." \
    --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

Note: The flags --organization, --microservice, --description, --contact-name, --contact-email, and --vault are optional after the initial creation, as they are stored in archetype.json.

2. Creating an Aggregate: Organizing Your Domain!

yo codedesignplus:microservice aggregate

Creates a new aggregate in your microservice. Aggregates are key in DDD—they maintain the consistency of your entities!

yo codedesignplus:microservice aggregate \
    --organization acme \
    --microservice users \
    --aggregate UserProfile

3. Creating an Entity: Giving Identity to Your Objects!

yo codedesignplus:microservice entity

Creates one or more entities. These are objects with identity that can change state!

yo codedesignplus:microservice entity \
    --organization acme \
    --microservice inventory \
    --entities Product,Category

4. Creating a Value Object: Objects Without Identity!

yo codedesignplus:microservice valueObject

Creates one or more value objects. They are immutable and defined by their attributes!

yo codedesignplus:microservice valueObject \
    --organization acme \
    --microservice users \
    --valueObjects Email,Address

5. Creating a Domain Event: Communicating What Happens!

yo codedesignplus:microservice domainEvent

Creates one or more domain events. These are representations of something that happened in your domain!

yo codedesignplus:microservice domainEvent \
    --organization acme \
    --microservice orders \
    --aggregate Order \
    --domainEvents OrderCreated,OrderShipped

6. Creating a Repository: Access to Your Data!

yo codedesignplus:microservice repository

Creates a repository for a specific aggregate. It's the interface to access persistent data!

yo codedesignplus:microservice repository \
    --organization acme \
    --microservice products \
    --repository Product

7. Creating a Controller: Managing Requests!

yo codedesignplus:microservice controller

Creates a controller to manage incoming requests (HTTP or gRPC).

yo codedesignplus:microservice controller \
    --organization acme \
    --microservice users \
    --controller UserProfileController

8. Creating a Proto: Defining Your gRPC API!

yo codedesignplus:microservice proto

Creates a .proto file for a gRPC service. It defines the messages and services for communication!

yo codedesignplus:microservice proto \
    --organization acme \
    --microservice products \
    --proto-name ProductService

9. Creating an Event Consumer: Reacting to Changes!

yo codedesignplus:microservice consumer

Creates a consumer that reacts to events published by other microservices.

yo codedesignplus:microservice consumer \
    --organization acme \
    --microservice notifications \
    --consumer-name OrderCreated \
    --consumer-aggregate Order \
    --consumer-action send-order-confirmation

10. Creating a Query: Getting Information Without Changing Anything!

yo codedesignplus:microservice query

Creates one or more queries to get information from the system without modifying its state!

yo codedesignplus:microservice query \
    --organization acme \
    --microservice products \
    --aggregate Product \
    --repository Product \
    --queries FindProductById,FindProductsByName

11. Creating a Command: Changing the System State!

yo codedesignplus:microservice command

Creates one or more commands to perform actions that change the system's state.

yo codedesignplus:microservice command \
    --organization acme \
    --microservice orders \
    --aggregate Order \
    --repository Order \
    --commands CreateOrder,CancelOrder

12. Creating Data Transfer Objects (DTOs): The Traveling Data!

yo codedesignplus:microservice dto

Creates one or more DTOs to transfer data between layers or microservices.

yo codedesignplus:microservice dto \
    --organization acme \
    --microservice orders \
    --aggregate Order \
    --dataTransferObject OrderDto,OrderSummaryDto

13. Creating a gRPC Project: Adding Fast Communication!

yo codedesignplus:microservice grpc

Creates a gRPC project within your microservice if you didn't do it initially!

yo codedesignplus:microservice grpc \
    --organization acme \
    --microservice products

14. Creating an Async Worker Project: Background Tasks!

yo codedesignplus:microservice asyncWorker

Creates an asynchronous worker project within your microservice for tasks that don't need to wait!

yo codedesignplus:microservice asyncWorker \
    --organization acme \
    --microservice notifications

Internal Structure of the Generator and Contributions 🤝

How Does This Generator Work Internally? 🤔

The generator-codedesignplus is built using Yeoman, a tool for creating code generators. Here's a summary of its structure:

1. Entry Point (index.mjs):

   • The "brain" of the generator.
   • Imports the Core, Utils, and DotNet classes from their respective files.
   • Retrieves command-line arguments (template, organization, microservice, etc.).
   • Executes methods to generate files, depending on the resource (aggregate, command, entity, etc.).

2. Core Class (core/core.mjs):

   • Manages arguments, options, and initial questions.
   • Maps generators to resources (aggregate, command, entity, etc.).
   • Displays help in the console.
   • Decides which generator to use, based on the template option.

3. Utils Class (core/utils.mjs):

   • Utility functions for the generator.
   • Reads and writes configuration information (archetype.json).
   • Transforms files (replaces names, namespaces, etc.).
   • Manages namespaces, adds usings, and generates files with generateFiles.

4. DotNet Class (core/dotnet.mjs):

   • Logic to perform operations related to .NET.
   • Removes projects from a microservice (executed when creating the microservice).

5. Specific Generators (core/*.mjs):

   • Generators for components (e.g., aggregate.mjs, command.mjs).
   • Define specific arguments and options.
   • Implement logic to generate files (using templates and Utils).

6. Templates (templates/):

   • Base files for generating code.
   • Placeholders (e.g., CodeDesignPlus.Net.Microservice, Order) are dynamically replaced.
   • The structure reflects a .NET project with the CodeDesignPlus.Net.Microservice archetype.

7. Types (types/):

   • Definitions of classes/interfaces for data type management within the generator.

8. package.json:

   • Project dependencies, development scripts, and package information.
   • Includes yeoman-generator, find-up, etc.

How to Contribute to Development? 🤝

We love collaboration! If you want to contribute, follow these steps:

1. Clone the repository:

   git clone https://github.com/codedesignplus/generator-codedesignplus.git
   cd generator-codedesignplus

2. Install the dependencies:

   npm install

3. Make your changes:

   • Create a separate branch.
   • Modify files in generators, templates, and types.
   • Understand the logic (index.mjs, core/core.mjs, core/utils.mjs).
   • If you add templates, update the generators' logic.

4. Run tests:

   • Run tests with npm test.
   • Create or modify tests as needed.

5. Ensure your code follows project style:

   • Execute npm run lint, npm run format or npm run prettier

6. Create a Pull Request:

   • Upload your changes to your fork.
   • Create a pull request to the main branch.
   • Describe your changes clearly.

Detailed File Structure 📁

Here's a summary of the generator's file structure:

generator-codedesignplus/
├── generators/                   # Generator logic
│   ├── core/                     # Central logic
│   │   ├── aggregate.mjs         # Aggregate generator
│   │   ├── appsettings.mjs        # Appsettings generator
│   │   ├── asyncWorker.mjs      # Async Worker generator
│   │   ├── command.mjs           # Command generator
│   │   ├── consumer.mjs        # Consumer generator
│   │   ├── controller.mjs        # Controller generator
│   │   ├── core.mjs              # Core class
│   │   ├── dataTransferObject.mjs # DTO generator
│   │   ├── domainEvent.mjs       # Domain event generator
│   │   ├── dotnet.mjs            # Utilities for .Net
│   │   ├── entity.mjs            # Entity generator
│   │   ├── errors.mjs             # Errors generator
│   │   ├── grpc.mjs               # gRPC generator
│   │   ├── microservice.mjs       # Microservice generator
│   │   ├── proto.mjs             # .proto file generator
│   │   ├── query.mjs             # Query generator
│   │   ├── repository.mjs        # Repository generator
│   │   ├── utils.mjs             # Utilities class
│   │   ├── valueObject.mjs       # Value object generator
│   │   └── xml.mjs               # XML Utilities
│   ├── index.mjs                # Entry point
│   ├── templates/               # File templates
│   │   ├── aggregate/           # Aggregate templates
│   │   ├── command/             # Command templates
│   │   ├── consumer/             # Consumer templates
│   │   ├── controller/          # Controller templates
│   │   ├── data-transfer-object/ # DTO templates
│   │   ├── domain-event/        # Domain event templates
│   │   ├── entity/              # Entity templates
│   │   ├── errors/              # Errors templates
│   │   ├── grpc/               # gRPC templates
│   │   ├── microservice/        # Microservice templates
│   │   ├── others/              # Other templates
│   │   ├── query/               # Query templates
│   │   ├── repository/          # Repository templates
│   │   └── value-object/        # Value object templates
│   └── types/               # Type definitions
│       ├── aggregate.mjs
│       ├── appsettings.mjs
│       ├── base.mjs
│       ├── command.mjs
│       ├── consumer.mjs
│       ├── controller.mjs
│       ├── dataTransferObject.mjs
│       ├── domainEvents.mjs
│       ├── entity.mjs
│       ├── index.mjs
│       ├── proto.mjs
│       ├── query.mjs
│       ├── repository.mjs
│       └── valueObject.mjs
├── package.json                # Project configuration
└── README.md                   # This file

Usage 🚀

1. Install Yeoman and the generator:

   npm install -g yo
   npm install -g generator-codedesignplus

2. Run the commands:

   Go to the folder where you want to generate the microservice and run one of the yo codedesignplus:microservice commands shown above.

And that's it! We hope this generator is a great help to you on your journey as a microservice developer. If you have any questions, don't hesitate to contact us or create an issue in the repository! 😊