CesarBotas.Database.Abstractions 1.11.0

botas-cqrs

Framework corporativo para .NET 10. CQRS com pipeline de behaviors, Result Pattern, migrations multi-banco, mensageria Kafka e RabbitMQ — tudo com observabilidade nativa.

Documentação

Botas.CQRS

Botas.Database

Mensageria

O que é CQRS?

CQRS (Command Query Responsibility Segregation) é um padrão que separa operações de escrita (Commands) de operações de leitura (Queries). Isso torna o código mais organizado, testável e fácil de manter.

┌─────────────────────────────────────────────────────────┐
│                    Sua Aplicação                        │
│                                                         │
│   Controller / Minimal API                              │
│          │                                              │
│          ▼                                              │
│     IDispatcher  ◄── ponto único de entrada             │
│          │                                              │
│    ┌─────┴──────┐                                       │
│    ▼            ▼                                       │
│  Command      Query                                     │
│  Handler      Handler                                   │
│  (escreve)    (lê)                                      │
└─────────────────────────────────────────────────────────┘

Pacotes

A solução é composta por 5 pacotes NuGet com responsabilidades bem definidas:

Botas.CQRS — pacote principal ⭐ recomendado

Pacote agregador. Inclui tudo: DI, assembly scanning, behaviors e dispatcher.

dotnet add package Botas.CQRS

Use quando: você está construindo uma API ou aplicação e quer tudo funcionando com uma linha de configuração.

builder.Services.AddBotasCQRS(options =>
{
    options.AssembliesToScan.Add(typeof(Program).Assembly);
});

Botas.CQRS.Abstractions — contratos

Apenas interfaces e tipos base. Sem dependências externas.

dotnet add package Botas.CQRS.Abstractions

Use quando: você tem um projeto de domínio ou aplicação que precisa referenciar apenas os contratos, sem carregar a implementação.

Interfaces disponíveis:

Botas.CQRS.Results — Result Pattern

Implementação do Result Pattern para evitar exceções em fluxos de negócio.

dotnet add package Botas.CQRS.Results

Use quando: você quer retornar sucesso ou falha de forma explícita, sem lançar exceções.

// Sucesso
Result<Guid> result = Result<Guid>.Ok(userId);

// Falha
Result<Guid> result = Result<Guid>.Fail(new NotFoundError("User", id.ToString()));

// Pattern matching
return result.Match(
    onSuccess: id => Ok(new { id }),
    onFailure: error => BadRequest(error.Message));

Tipos de erro disponíveis:

Botas.CQRS.Dispatching — dispatcher e pipeline

Implementação do IDispatcher, PipelineExecutor, HandlerResolver e NotificationPublisher.

dotnet add package Botas.CQRS.Dispatching

Use quando: você quer usar o dispatcher sem o bootstrap automático do pacote principal (cenários avançados).

Componentes:

Botas.CQRS.Behaviors — pipeline behaviors

Behaviors prontos para uso no pipeline de requisições.

dotnet add package Botas.CQRS.Behaviors

Use quando: você quer usar os behaviors individualmente ou criar behaviors customizados baseados nos existentes.

Pipeline padrão (ordem de execução, de fora para dentro):

ExceptionBehavior        ← captura exceções não tratadas
  CorrelationBehavior    ← propaga CorrelationId / TraceId
    LoggingBehavior      ← log de início e fim
      PerformanceBehavior ← mede tempo (alerta > 500ms)
        ValidationBehavior ← executa IValidator<T>
          TransactionBehavior ← envolve em transação (se configurado)
            AuditBehavior ← registra usuário + timestamp
              Handler    ← sua lógica de negócio

Início rápido

1. Instalar

dotnet add package Botas.CQRS

2. Configurar

// Program.cs
builder.Services.AddBotasCQRS(options =>
{
    options.AssembliesToScan.Add(typeof(Program).Assembly);
});

3. Criar um Command

// CreateUserCommand.cs
public sealed record CreateUserCommand(string Name, string Email) : ICommand<Result<Guid>>;

// CreateUserCommandHandler.cs
public sealed class CreateUserCommandHandler : ICommandHandler<CreateUserCommand, Result<Guid>>
{
    public async ValueTask<Result<Guid>> Handle(CreateUserCommand command, CancellationToken ct = default)
    {
        var id = Guid.NewGuid();
        // salvar no banco...
        return Result<Guid>.Ok(id);
    }
}

4. Criar uma Query

// GetUserByIdQuery.cs
public sealed record GetUserByIdQuery(Guid UserId) : IQuery<Result<UserDto>>;

// GetUserByIdQueryHandler.cs
public sealed class GetUserByIdQueryHandler : IQueryHandler<GetUserByIdQuery, Result<UserDto>>
{
    public async ValueTask<Result<UserDto>> Handle(GetUserByIdQuery query, CancellationToken ct = default)
    {
        var user = await _repository.GetByIdAsync(query.UserId, ct);
        if (user is null)
            return new NotFoundError("User", query.UserId.ToString());

        return Result<UserDto>.Ok(new UserDto(user.Id, user.Name, user.Email));
    }
}

5. Usar no Controller

[ApiController]
[Route("api/users")]
public sealed class UsersController(IDispatcher dispatcher) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Create(CreateUserRequest request, CancellationToken ct)
    {
        var result = await dispatcher.Execute<CreateUserCommand, Result<Guid>>(
            new CreateUserCommand(request.Name, request.Email), ct);

        return result.Match(
            onSuccess: id => CreatedAtAction(nameof(GetById), new { id }, new { id }),
            onFailure: error => BadRequest(error));
    }

    [HttpGet("{id:guid}")]
    public async Task<IActionResult> GetById(Guid id, CancellationToken ct)
    {
        var result = await dispatcher.Query<GetUserByIdQuery, Result<UserDto>>(
            new GetUserByIdQuery(id), ct);

        return result.Match(
            onSuccess: dto => Ok(dto),
            onFailure: error => error is NotFoundError ? NotFound() : BadRequest(error));
    }
}

Opções de configuração

builder.Services.AddBotasCQRS(options =>
{
    // Assemblies a escanear (obrigatório ao menos um)
    options.AssembliesToScan.Add(typeof(Program).Assembly);

    // Behaviors (todos habilitados por padrão)
    options.EnableValidation = true;
    options.EnableLogging = true;
    options.EnablePerformance = true;
    options.EnableTransactions = true;
    options.EnableCorrelation = true;
    options.EnableAudit = true;

    // Notificações em paralelo (padrão: sequencial)
    options.EnableParallelNotificationPublishing = false;

    // Behaviors customizados
    options.PipelineBehaviors.Add(typeof(MeuBehaviorCustomizado<,>));
});

Estrutura recomendada de projeto

src/
├── MinhaApi/                          # Camada de apresentação
│   ├── Controllers/
│   └── Program.cs
├── MinhaApi.Application/              # Casos de uso
│   ├── Users/
│   │   ├── Commands/
│   │   │   └── CreateUser/
│   │   │       ├── CreateUserCommand.cs
│   │   │       ├── CreateUserCommandHandler.cs
│   │   │       └── CreateUserCommandValidator.cs
│   │   └── Queries/
│   │       └── GetUserById/
│   │           ├── GetUserByIdQuery.cs
│   │           └── GetUserByIdQueryHandler.cs
│   └── Notifications/
│       └── UserCreated/
│           ├── UserCreatedNotification.cs
│           └── SendWelcomeEmailHandler.cs
└── MinhaApi.Domain/                   # Entidades e regras de domínio

Comparação com MediatR

Todos os pacotes do ecossistema

CQRS

Database

Mensageria

Requisitos

• .NET 10.0+
• Microsoft.Extensions.DependencyInjection
• Microsoft.Extensions.Logging

Licença

Consulte o arquivo LICENSE.